Sugar 1.00                                          RISC User magazine 1998
                                                                Noel Crombie
                                                Documentation by Matt Browne


Introduction and Overview

Currently RISC OS provides no easy way of letting Wimp tasks receive module
service calls. Sugar adds this facility in a small, easy-to-use module, and
is suitable for use with RISC OS 3.1 and later.

A Wimp task provides a list of the service calls it needs to receive to
Sugar, using a format similar to the Wimp_AddMessages and
Wimp_RemoveMessages SWIs provided by the Window Manager (see pages 3-226 and
3-227 respectively). When the relevant service calls are received by Sugar,
they are sent to the task through a standard Wimp message.


SWI Calls and Wimp Messages

The following section documents the two SWI calls and one Wimp message
provided by Sugar.

============================================================================
Sugar_AddServices       (SWI &4FB00)
* Registers service calls that will be received by the Wimp task.

On entry
   R0 = pointer to word array of services to add for task

On exit
   R0 preserved

Interrupts
   Interrupts are not defined
   Fast interrupts are enabled

Processor Mode
   Processor is in SVC mode

Re-entrancy
   SWI is not re-entrant

Use
   This SWI allows you to update the list of service calls that will be sent
to a certain task by Sugar. It should be treated in the same way as most
Window Manager SWIs - the calling task should have been registered with
Wimp_Initialise before using this SWI.
   When registered service calls are received by Sugar they are transmitted
to the task by use of the Message_SugarService Wimp message (documented
below).

============================================================================
Sugar_RemoveServices    (SWI &4FB01)
* Removes service calls from the list of those that will be received by the
  Wimp task.

On entry
   R0 = pointer to word array of services to remove from task

On exit
   R0 preserved

Interrupts
   Interrupts are not defined
   Fast interrupts are enabled

Processor Mode
   Processor is in SVC mode

Re-entrancy
   SWI is not re-entrant

Use
   This SWI removes service calls from the list of those that will be sent
to a certain task by Sugar, in a similar way to Wimp_RemoveMessages.

============================================================================
Message_SugarService    (Message &4FB00)
* The Wimp message used by Sugar to transmit details of relevant service
  calls to a Wimp task.

     R1+20   contents of R0 provided with service call
     R1+24   service call number             (i.e. R1)
     R1+28   contents of R2 provided with service call
     R1+32   contents of R3 provided with service call
     R1+36   contents of R4 provided with service call
     R1+40   contents of R5 provided with service call
     R1+44   contents of R6 provided with service call
     R1+48   contents of R7 provided with service call
     R1+52   contents of R8 provided with service call

   Of course, not all of the information provided will necessarily be
needed - see individual documentation on service calls you need to receive.
