Programming
© nemo 2020-2024
This stuff will only be of use to RISC OS programmers
UnReadC
Current version is 0.03 (07 Aug 2024) [32bit]
This is only here for Bluesky
The Un_ReadC SWI allows you to push back a value received from OS_ReadC, so that the next call will read it again. It can also be used to push any amount of text into "the keyboard buffer" so that it will appear as if typed. It’s DeepKeys compatible.
Un_ReadC (&5A8C0)
=> R0 character code to push back (32b)
This allows a value returned from OS_ReadC to be pushed back, regardless of its source (which may have been redirection, exec file, soft key expansion etc.
Note that R0 is a WORD, not a byte. When OS_ReadC is called, the value in R0 will be returned. If the DeepKeys extended OS_ReadC API is used, no modifiers will be returned in R1 (b15 is set).
Un_DeepC (&5A8C1)
=> R0 character code to push back
R1 modifiers & physical key in DeepKeys format:
b0 = Left Shift b1 = Right Shift
b2 = Left Ctrl b3 = Right Ctrl
b4 = Left Alt b5 = Right Alt
b6 = Left Logo b7 = Right Logo
b8 = Menu key b15 = 0, always
b16-31 = internal key number
This SWI allows the keypress and modifiers read from the DeepKeys extended OS_ReadC to be pushed back.
!Modules
The current version is 1.06 (19 Dec 2024)
At your ServiceCall, sir...
Module management in the desktop. Sort into many orders. Select the ones you want to fiddle with, then reinitialise, delete, or even send a Service Call to only those modules.
This is a generally useful program, but will be especially valuable to module developers, because it also allows you to kill a module that refuses to die – though in the absence of SaferModules you’ll have to tidy up afterwards. More on this subject another day, perhaps.
Note that RMA modules are highlighted in blue, and 32bit modules have a tick next to them (except in RO5 where it’s superfluous).
!NZCV
The current version is 0.01 (11 Apr 2022)
Flip those flags, consider those conditions
This machine code programming utility makes it easier to predict the sometimes counter-intuitive results of a simple comparison.
It’s also useful when writing CPU-agnostic code by confirming what manipulation of values you already have will produce the flags you require, without resorting to architecture-dependent PSR-modification instructions.
!SprTypes
The current version is 0.03 (16 Dec 2024)
Just a simple matter of clicking a few buttons...
This program allows you to design Sprite Type words via a complicated comprehensive user interface (it’s a complicated user interface because Sprite Type words are complicated).
Yes, you can use this to create a “CMYK” Sprite Type whose Extended data format says it is RGB. To understand what that’s supposed to mean I must direct you to ROOL with the very greatest of luck. [Though I have declared that Extended paletted sprites that claim to be CMYK are perfectly acceptable – as that means the palette is CMYK.]
!LangTest
The current version is 0.04 (16 Dec 2024)
!LangTest about to switch to Japanese
The tool allows you to test the localisation of your application without having to reboot your machine (or locate mythical Territory modules).
Select the desired country/language, click Set, then drag an application to the icon to launch it in its own little language bubble.
Includes the UTF8Alphabet module which you can also download with support material here.
GUID
The current version is 0.10 (24 Jul 2024) [32bit]
“Globally Unique Identifiers” and “Universally Unique Identifiers” are two contested terms for the same concept – a 16 byte identifier which, by its sheer magnitude (when viewed as a 128 bit number) and the rules for creating one, render the result effectively unique without resorting to a central allocation agency. As such they are fantastically useful, and are heavily used by Microsoft and internet protocols. It's about time RISC OS had them.
Unfortunately, due to vague documentation of the original implementation, the ubiquity of Microsoft's early adoption of the concept, and the unhelpful determination of the Open Software Federation to adopt the most incovenient interpretation of the design, the terms UUID and GUID and the order of the bytes that make them up are ill-defined and confusing in the real world.
So in RISC OS we are VERY strict about the terms WE use to refer to them: We so declare that “GUID” means little-endian (Microsoft order), and “UUID” means network-byte-order. This strict terminology is not portable – one must normally infer byte-order contextually, but in RISC OS we will be merciless. As our CPUs are little-endian, we prefer the Microsoft order and hence we shall call this “GUID”. The network-byte-order that is used in network packets shall be called “UUID”.
GUID is good. UUID is weird.
The Cerilica GUID module provides the most complete implementation of GUIDs imaginable. It can create the original UUID, the OSF variants, and Microsoft GUIDs (and it should be stressed that the overwhelming majority of GUIDs, AppIDs, CLSIDs, ProgIDs etc used in Microsoft Windows are actually the OSF format) incorporating time/date, MAC address, hashed and random elements, in TEN different formats.
It can compare GUIDs in the FIVE different ways they are typically ordered, plus read and write string form, eg “e181f43a-014a-ef01-c000-5bb1c0a80027”, with or without brackets.
It can load and store to memory in both byte orders, convert between byte-orders in memory or registers, and it can SHA-1 and MD5 hash stuff too.
Furthermore, it extends OS_File and OS_SpriteOp to build GUID capability into filing systems and sprites (requires MetaSprite). Plus there's some star commands for you to use at the command line.
The API is large and complex, so please refer to the included StrongHelp manual for programming information, and there is an AAsm/ObjAsm header file in SWINames. There are 27 SWIs, 3 star commands, 5 OS_File reasons and an OS_SpriteOp. Enjoy.
AutoPrefix
The current version is 0.05 (26 Sep 2022) [32bit]
This module works with (and requires) DDEUtils to allow nominated filetypes to have their own Currently Selected Directory via the DDEUtils *Prefix command. i.e. after *AutoPrefix BASIC, double-clicking a Basic program sets its CSD to its directory. This means that a Basic program can access files in the same directory by just using a leafname. You can nominate as many filetypes as you like – it automatically saves its configuration.
Syntax: *AutoPrefix [filetype] | -save [filename] | -load [filename]
There's an Install script and a trivial demo.
Note that this doesn’t change the actual CSD – DDEUtils does the relative-to-absolute-filename mapping per task. There’s at least three ways of doing so better than DDEUtils but that’s a project for a different year.
!Bowdler
The current version is 0.03 (16 Dec 2024)
!Bowdler doing its Bowdlerising
A tool for making safe SysVar names
RISC OS System Variables (SysVars) have machine-readable names despite friendly examples such as “Font$Path” or “Wimp$Scrap” – these names are hardwired into code and do not get localised with changes of language. They are machine-readable, but as a convenience for the programmer they are treated as "case insensitive".
Unfortunately in some cases human-readable parts are used in SysVars and this causes a vulnerability, as the very poor “case insensitivity macro” that infected the Kernel in RISC OS 3.50 can utterly corrupt human-readable text written in some alphabets. Disasterously, this includes UTF-8 so can potentially afflict ALL languages in addition to the Hebrew and Cyrillic alphabets. This corruption can result in the wrong SysVar being written or read, confusing different SysVars for each other. This is a very serious failing. It is certainly best to stick to ASCII where possible, but there are cases where it is unavoidable.
If your SysVar names do not contain human-readable elements, then stick to ASCII and you will not need this program. But if it contains accented characters, symbols, or is derived from ANY user input – such as machine, drive, file or user names – you MUST Bowdlerise it before using OS_SetVarVal or OS_ReadVarVal and decode it before display or comparison.
!Bowdler encodes unsafe names into a safe form that can be used as a SysVar name, and the ReadMe contains code for decoding the most difficult cases (although OS_GSTrans is enough if the original did not contain wildcard characters).