Wimp API changes since Ursula

In general, APIs that take pointers which have formerly been documented as assigning the same special meaning to all values less than or equal to zero now only follow that special meaning for value of 0 and -1. This is to allow pointers to the top half of memory to be used.

Service_ErrorButtonPressed (Service call &400C1)

Minimal environment handlers are now installed around this service call, so its handler can call OS_Exit without leaving the Wimp state undefined.

Wimp_CreateWindow (SWI &400C1)

The feature introduced in the nested wimp, whereby a Wimp_Initialise version of 380 allowed window foreground colour &FF to turn off single-pixel borders, was unhelpfully being applied according to the version of the current task, rather than the version of the creator of the window. In this way, old tasks accessing windows created by other tasks could cause all the window furniture bits to be unset.

Window flag byte +39 is extended as follows:
bit 1    reserved for use by RISC OS Select

bits 3 and 2:

01 =>    never give window a 3D border
10 =>    always give window a 3D border (subject to WimpVisualFlags)
00,11 =>    automatic 3D border mode (subject to WimpVisualFlags)
bit 4 set =>    allow Wimp_GetPointerInfo to detect shaded icons (for example,

   this allows interactive help messages to work with shaded
   icons). Note that mouse click behaviour remains unchanged.

Wimp_CreateIcon (SWI &400C2)

New validation string command, 'U' followed by a decimal number, will set a limit on the number of characters accepted in a writable icon. This is distinct from the byte limit specified in the icon data (which still applies) when the system alphabet is set to UTF-8. Theoretically, you should allow 6 bytes storage per character for writable icons, but in practice 4 bytes will cover all the planes of UTF-16 and all therefore all the characters that are likely ever to be defined by ISO.

Note that the 'A' and 'D' validation string commands accepts multi-byte characters when the alphabet is UTF-8.

The 'C' command is extended to allow separate foregroud and background 24-bit colours to be specified when the icon is selected.

Wimp_Poll (SWI &400C7)

Multibyte UTF-8 characters are reported using multiple Key_Pressed events.

Callbacks are now triggered when there are no null event recipients waiting.

The default UpCall handler is now installed when a task is being paged out, so there is no danger of aborts due to UpCallV being called from an interrupt routine (note that such use of UpCallV is to be avoided, not least to prevent this very problem under older Wimps).

Wimp_SetCaretPosition (SWI &400D2) / Wimp_GetCaretPosition (SWI &400D3)

Indexes into strings are by byte, not character. (This distinction only matters when the alphabet is UTF-8.)

Wimp_ProcessKey (SWI &400DC)

This SWI can now be called multiple times between calls to Wimp_Poll - this is important for the input of multi-byte UTF-8 characters.

Wimp_StartTask (SWI &400DE) / *WimpTask

Now accept long command lines.

Wimp_CreateMenu (SWI &400D4)

Dialogue boxes can now contain nested windows.

Menu titles can end in a key name without being aligned as though it were a keyboard shortcut.

Wimp_AddMessages (SWI &400F6)

This can now safely be called for tasks that wanted all messages - previously, it would have caused all other messages to be hidden from such tasks!

Wimp_TextOp (SWI &400F9)

Two are new reason codes: 3 (gets split point), and 4 (truncates with ellipsis).

On entry:
  r0  bits 0-7  =   3 (reason code)
      bits 8-31 =   reserved (must be zero)
  r1            ->  string
  r2            =   width, OS units
  r3            =   split character

On exit:
  r0            ->  split point
  other registers preserved

On entry:
  r0  bits 0-7  =   4 (reason code)
      bits 8-31 =   reserved (must be zero)
  r1            ->  string
  r2            ->  output buffer
  r3            =   buffer size (may be zero if you just want to
                                  query the required size)
  r4            =   max width, OS units

On exit:
  r0            =   size of buffer needed
  other registers preserved
  The buffer is filled with a string, truncated (if necessary) with either
  an alphabet-dependent ellipsis character or three full stops, depending
  upon the current alphabet and whether the ellipsis character is defined in
  the current desktop font.

Wimp_Extend (SWI &400FB)

A new reason code, 13, can be used to find the appropriate "resolution" suffix to a sprite file name:

On entry:
  r0  =   13 (reason code)
  r1  ->  pathname of file without suffix
  r2  ->  buffer for result
  r3  =   size of buffer (0 to read size required)

On exit:
  r0      corrupted
  r3  =   space left in buffer (ie negative of size required if r3=0 on entry)
  other registers preserved
  contents of buffer are only valid if r3>=0
  error "File not found" may be returned

This employs the full multi-pass scheme required to fully support EX0 EY0 modes. Older Wimps don't return an error, but can be detected because all registers are preserved - in which case Wimp_ReadSysInfo 2 should be used to construct the appropriate filename.