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 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.


*Configure WimpClickSubmenu

Allows submenus to be opened by clicking on the parent menu item. Mostly
useful for touchscreen devices.


*WimpSlot

Can now take memory sizes in megabytes or even gigabytes.


*WimpVisualFlags

See *Help message.