Programmer Interface to Wimp 30/6/93

This document describes the extensions to the programmer interface (as
defined by the RISC OS 3 PRMs) implemented by the modules supplied with
this document. Note that since the modules supplied are development
software, the interfaces described here may be subject to further change
or extension. It is therefore unwise at this date to build an understanding
of these interfaces into product software. The main purpose of this disc
release is to help ISV's build future-proof dialogue boxes, so the following
information is supplied only as the basis for experimentation.

The Wimp responds to a new message, when broadcast as a user message:
        mblock+16       Message_FontChanged (&400CF)
    On receiving this the Wimp loses the current font, examines the
variables as defined above and attempts to find the defined font with the
font manager. If this happens successfully then the Wimp broadcasts the
following message to all tasks:
        mblock+16       Message_FontChanged
        mblock+20       Font handle or 0
    then all the open windows are redrawn. This is necessary so that old
applications which do not understand this message will appear correctly. If
the font could not be found (eg. because wimp$font was unset) then the
system reverts to the VDU text system. The font handle is used in the filer
for instance so that it can calculate how wide the directory viewer columns
should be (see the section on external dependencies).

The SWI Wimp_ReadSysInfo has the following new Reason codes for returning
information about the desktop such as the system font handle:

on entry:
  r0 = 8 (read wimp font handle)
on exit:
  r0 = 0 (and other registers undefined) if there is currently no wimp font
handle OR
  r0 = wimp font handle
  r1 = wimp symbol font handle

on entry:
  r0 = 9 (read wimp tool sprite pointer)
on exit:
  r0 = pointer to wimp toolsprite control block
    This returns the CB pointer for the window furniture so that
applications can use the same tools within a window, eg. scrollbars.

A new SWI is added for returning information about an icon as it would
appear on the screen.

Wimp_GetIconInfo (&400F7)
Entry:  R0 reason code  R1              R2              Exit:
        1              text ptr         -               R0 has width
        2              text ptr         no. chars       R0 has width of first R2
                                                        characters

This is used for instance by the Filer when calculating the widths of the
columns in the viewer.

    As mentioned above, when the wimp finds a sprite called tile_1, this is
then used whenever the background is of a window is cleared to colour 1. In
this way an application can control which sprite is used by setting up a
sprite control block and putting the pointer to this area on the window.

At the moment, Wimp_ReportError provides the following: (see RISC OS 3 PRM,
page 3-179 )

On entry
  R0 -> error block (code + message)
  R1 = flags
  R2 -> application name
On exit
  R0 corrupted
  R1 = 0 for no key click, 1 for OK, 2 for Cancel

Flags:
  0 => provide OK
  1 => provide Cancel
  2 => highlight Cancel
  3 => immediate return from Wimp_CommandWindow text window
  4 => dont prefix Error from in title bar
  5 => return immediately with box up
  6 => close the box (using 0 and 1 to select a button)
  7 => do not beep
  8-31 reserved - must be 0

The following is added to this:

  R3 -> sprite name
        (if not provided we try the application name prefixed by "!" as a
sprite name, a desperate measure as it may not internationalise well)
  R4 -> sprite area (or 0 to use the Wimp sprite area)
  R5 -> additional button list of buttons, or 0 if none. A comma-separated
sequence of strings, terminated with a control character. These strings are
the text of additional buttons to create in addition to the Continue and
Cancel buttons (if requested). If neither Continue nor Cancel is specified
by bits 0 and 1 then the first of these is the default button. These buttons
will generate return values 3, 4, 5 and so on. The first of them will appear
to the right, the next to the left of that, and so on. If Describe is
added by the system this appears at the extreme left.

  flag bit 8 => R3-5 provided and then
     flag bits 9..11 define the error categories:

        Bits 9..11 = 1 -> This is an information error.
        Bits 9..11 = 2 -> This is a warning error.
        Bits 9..11 = 3 -> This is a program error.
        Bits 9..11 = 4 -> This is a question.
        (other combinations reserved)


    If the error is a program error (either bit 31 of error set or
combination 3 above) then a Cancel button is always provided, but the label
on it is Quit rather than cancel. The error text is replaced by:
   Appname has suffered an internal error. Click Quit to stop Appname.
    A Describe button is added to the button list. If Cancel/Quit is
pressed and the program did not request its presence, then the application
is simply terminated by the Wimp without being reentered. If Describe is
pressed then the message is replaced by the original error message and
buttons provided by the application, ie. the Describe button disappears.

                (Aside: this assumes the convention used by many
applications, that in the case of an unexpected error Cancel is used to
actually exit the program while OK is used to attempt to continue.)

    A new service call interface allows a separate module to replace the
entire system or add new buttons, such as a debug button or a help
button. Pressing these new buttons returns control to the module that sent
them, via the same service call. As a return from this call the module can
specify that the ReportError SWI exits, or that the box is reentered. In
reentering the box the text in the message window can also change.

When Wimp_ReportError is called, the following service is issued:

Service_ErrorStarting
Entry & Exit   R2-R7 as R0-R5 for Wimp_ReportError
    Ie. R2 points to an error block. The actual values of R2-R7 may be
altered, but not the memory pointed to by them. By setting the flags (R3) to
exit immediately a handler claiming this call may handle errors in its own
way. A module may add buttons by copying [R7] and appending (not inserting)
its own button list. It should obviously keep track of the position of its
button for use in the button pressed handler. The toolkit should make this
easier to use.

When any button on the error dialog box is pressed the following service
call happens:

Service_ErrorButtonPressed
Entry   R0      zero
                        R2      button number   (1-OK,2-cancel,3-right most button...)
                        R3      final button list used

Exit            R0    0 - return to application
                                R2      button number to return (normally unchanged)
                            1 - redisplay error dialog
                                R2      new error register block:
                                +0      error block pointer
                                +4      flags
                                +8      title string
                                +12     sprite name pointer
                                +16     sprite area
                                +20     button list (or zero)
                If a module sets up such a block it should probably claim the call.

When the error box is about to close, the following call occurs:

Service_ErrorEnding
Entry           R2      button number to be returned to application
Exit            -
