Interface 2.00 
 Software Interrupt 1990

See notes at end for update info......

This manual and software is public domain.  It may be copied and distributed
freely as long as:

    It is not separated from the documentation (except for commercial use)
    The module is not tampered with
    You do not claim that you have written the module
    Do not use any of the code contained in this module in your own code

If you wish to use this in a commercial product please contact me so that I
can make sure you have the latest release, please send a disk.

In no circumstances shall the author be liable for any damage, loss of
profits, time or data or any indirect or consequential loss rising out of
the use of this software or inability to use this software.

Contacts:
       Arcade BBS          (081 654 2212)                   
       The World Of Cryton (0749 679794)     

       All mail on the above Bulletin Bords should be mailed to JICK

**************** Introduction ***********************************************
 
Interface is a small module that allows application programmers to implement
a colourful and pleasant graphical user interface.  Interface provides many
more functions that allows you to change the pointer shape easily and to
interface with the !Help or !Spy application.

The Interface module provides functions to improve the friendliness and
appearance of the application. The application should still operate as
stated in the Acorn guidelines in the Programmers Reference Manuals.

The module implements a number of SWIs which are described further in this 
manual, these SWI calls can be called from any language.  Most of the
functions provided are specified in the icons validation string, and so no
complex programming is needed to make the application look good.

This guide tells you how to fully implement the features of Interface. It is
split into the follow sections:

   The first section explains the validation strings options provided
   by Interface.
   The next section gives details of the SWI calls provided.
   The remaining section covers hints and tips on programming.



**************** Technical details ******************************************

An indirected text icon can have a validation string which is used to pass
further information to the WIMP, such as what border type the icon has and
also what pointer, if any should be displayed whilst over this icon. The
syntax of a validation string is:

  validation string ::- command {;command}*
  command           ::- (b | z) border-type {border-spec} | 
                        r on/off-type {,icon-number}* |
                        u on/off-type {,icon-number}* |
                        p text-string {,x} {,y} |
                        i text-string |
                        k key-code
  border-spec       ::- {,button-slabbing-mask} {,slabbing-time} {,colour}*

The parameters above are described under the relevant validation command.
In simple terms, a validation string consists of a series of 'commands',
each starting with a single letter and seperated from the following command
by a semi-colon. {}* means zero or more of the thing inside the {}. The
following commands are available with the Interface module.

These commands are provided in addition to the standard Wimp validation
strings. I suggest that you edit the !FormEd program to allow you to enter
larger validation strings, otherwise when entering a help command you will
only be allowed a maximum of 80 characters.

The (B)order command tells Interface which border to use when rendering an
icon. The border types available at present are :

   border type 0, this is a single border used mainly for headings and
     action icons. The icon will slab inwards if the user clicks a button
     whilst the pointer is over the icon providing it is not setup to ignore
     mouse clicks.

   border type 1, this is a double border and should be used to group
     together icons that perform an operation.

   border type 2, this is a triple border and should be used on the default
     action button. The icon will slab inwards when the user clicks a button
     whilst the pointer is over this icon providing it is not setup to
     ignore mouse clicks.

   border type 3, this is a wide inverted border and should be used on
     writable icons. This border type is usually used in-conjunction with
     the writable pointer.
        
   border type 4, this is an inverted version of border type 0
       
   border type 5, this is a double wide border as used by acorn in ros 3
        
   border type 6, etched in border
        
   border type 7, similar to border type 0, thinner in mode 20

The second optional parameter is the button slabbing mask, this states
whether the icon should be slabbed until the button is released. The values
contained in this parameter can be from 0 to 7. The button slabbing mask can
be calculated in the following way:

        Value   Button          Meaning
        1       Adjust  slab icon until adjust is released
        2       Menu    slab icon until menu is released
        4       Select  slab icon until select is released

The button slabbing mask can then be calculated by adding together the
required button values.  

The button slabbing time is the minimum time that the icon will be slabbed
for, the default time is for 15cs.  This value is a decimal number in
centi-seconds. The colours are specified in the following order:

        {,border colour1} {,border colour2} {,slabbing out colour} 
        {,slabbing in colour} {,inner channel colour}

These colours can be any valid WIMP colour in the range of 0 to 15, the 
default selection is 4, 0, 1, 14, 12.

The (R)adio command specified in the validation string is used to set the
state of other radio button type icons.  The R command is followed by a
decimal number in the range 0 to 2, the action that these perform is:

Radio type              Operation
  0               this has the effect of switching off the specified icon(s).
  1               this has the effect of switching on the specified icon(s).   2               this has the effect of toggling the icons current state.

This command is then followed by the numbers of the icons you wish to alter,
these should be separated by commas. This command may be specified more than
once in a validation string, for example to switch icons 1 & 2 off, 3 & 4 on
and toggle the state of icons 5 & 6 you could use the following validation
string

        R0,1,2;R1,3,4;R2,5,6

The (U)nselectable command in the validation string has the effect of
shading the icon grey so that it cannot be selected by the user. It is
followed by a decimal number in the range 0 to 2, the action that these is
described above in the radio command.

This command is then followed by the numbers of the icons you wish to alter,
these should be separated by commas.  This command may be specified more
than once in a validation string, for example to shade icons 1 & 2, un-shade
3 & 4 and toggle the state of icons 5 & 6 you could use the following
validation string

        U0,1,2;U1,3,4;U2,5,6

The (P)ointer command is used to define a pointer to be displayed when the
pointer is over that icon.  The first parameter is a sprite name to use for
the pointer, this should be no longer than 12 characters and should be
present in the WIMP sprite pool. The optional parameters specify the x and y
offsets to the active point in the sprite, these should be specified in
pixels.

The (I)nformation command is used to define a message to be sent to the
interactive help application when the pointer is over the icon. If you wish
to use a semi-colon then you must place two next to each other. The maximum
length of the help message is 235 characters.

The Interface module will change to the specified pointer when the mouse
pointer is over the icon/workarea, if no pointer is specified then the
pointer will default to shape one (the default arrow shape). There are 5
pointer shapes designed in the sprite file in the !Interface directory,
these are:

   ptr_write - this pointer should be used on writable icons, the suggested
     active point is at coordinates x = 4, y = 4.

   ptr_menu - this pointer is used where a menu can be activated by pressing
     the menu button over the icon.  This stops the user having to search
     all over the window to find where the menu is. The suggested active
     point is x = 6, y = 5.

   ptr_direct - this pointer is used where an object may be re-sized, the
     suggested active point is at x = 13, y = 7.

   ptr_hand - this pointer is used where and icon may be dragged.  It is
     usually set on the workarea, but it can be used on any icon (the save
     file icon looks great when using it), its suggested active point is at
     x = 12, y = 8.

   ptr_cross - this pointer is used as a crosshair, it is the same as the
     one used in the Draw application. This icon gives the user a precise
     point when working with line drawings, its suggested active point is at
     x = 13, y = 7.

You may also design your own pointers, which should be loaded into the WIMP
sprite pool.  There are a few points that you should note when designing
pointers these are :

Pointer sprite names should have the form ptr_XXXXX, although this is not
compulsory it helps so that you do not get confused with pointers and normal
sprites.

Do not use logical colour 2 in the pointer sprites, as this is unavailable
in very high resolution modes.

The pointers used should only be valid in your application, so you must not
mask out the Pointer_Leaving_Window in your application. You should claim
Null_Reason_Code when passed to your application, otherwise the pointer will
not change when the pointer is over the icon/workarea, see the examples for
more.

You should support the !Help application to help new users using your
application, this is why I implemented a feature in Interface to make this
easier. The following was for some reason not published in the Programmers
Reference Manuals, but was in the pre-release disc version of the manuals.

For an application to use interactive help, two WIMP messages are employed.
One is used by the Help to request help, and the other is used by the
application to return the help message.

To request help, the Help application sends a message of the following form:

block   +16     &502 - indicates request for help
                +20     mouse x co-ordinate
                +24     mouse y co-ordinate
                +28     mouse button state
                +32     window handle               (-1 if not over a window)
                +36     icon handle                 (-1 if not over an icon)

The WIMP system will pass this message automatically to the task in charge
of the appropriate window/icon. If the application receiving the message
wishes to produce some help, it should respond with the following message:

block   +16     &503
                +20     help message terminated by 0

This message can be sent to the Help application by using Wimp_SendHelp,
which is provided by the Interface module (SWI &81687).

The help text may  contain any printable character codes. If the sequence |M
is encountered then this will be treated as a line break and subsequent text
will be printed on the next line in the window. If the text is too long for
one line then it will be split at a word boundary (space character).

The text should consist of  simple complete English sentences, each starting
on a new line and ending with a full stop. The sentences should usually be
simple imperatives or information such as:

        Click SELECT to set the alarm.

        You are in Select mode.

        Click ADJUST to change to path edit mode.

        This is the icon for Edit.

In general you need not mention menu entries, except when specific ones
interact with pointer operations. As a general rule present information of
interest to the beginner near the top, and expert tips or information lower
down.

You must use the terminology defined. For mouse operations you must use
initial capitals (for example Click). The mouse buttons must be in capitals
(for example SELECT), as must key names (for example ESC, RETURN, SHIFT,
CONTROL, A, B, F1, COPY). miss out speedups and shortcuts - just provide
enough to help a beginner without drowning them with information.

Provide interactive help thoroughly - include the icon bar, and the workarea
of all your windows.  If no actions are possible in a window, just

        This window shows....

is better than nothing.

You should assume a user knows:

        what a MENU key is
        how to navigate menu trees and choose entries
        what the icon bar is
        how to move/size/toggle/close windows, and so on
        what 'dragging an icon' means
        what 'filling in a field' (writable icon) means

The keycode command should be placed in the icon that is activated by the 
keycode.  It should be a decimal integer specifying the key.  The up/down
arrows, tab etc.. are dealt with.


**************************** The SWI Calls *********************************

Wimp_BorderIcon (Interface_SlabButton) (SWI &81680)

R1 = pointer to block
R1 preserved

Interrupts are not defined
Fast interrupts are enabled

Processor is in SVC mode

SWI is not re-entrant

The block contains the following on entry:

        R1+0    mouse x (screen coordinates - not window relative)
        R1+4    mouse y
        R1+8    buttons (depending on icon button type)
        R1+12   window handle
        R1+16   icon handle  

This call is used to update an icons border.  It is typically called as a
result of a Mouse_Click event, if the icon has a border type of 0 or 2 then
the icon will slab inwards. The format of the validation string is described
in the previous section.

The application should the perform the task and then force the icon to normal
status by calling Wimp_BorderIcon (SWI &81680) with R1+8 set to 0.

The code to border icons and windows is outlined in the section Programming 
Interface. 

Note that the mouse coordinates specified in R1+0 and R1+4 are not used by
the SWI and are only present to make the block compatible with a Mouse_Click
event block.

Wimp_BorderWindow (SWI &81681)

None





Wimp_BorderWindow (Interface_Render3dWindow) (SWI &81681)

R1 = pointer to block
R1 preserved

Interrupts are not defined
Fast interrupts are enabled

Processor is in SVC mode

SWI is not re-entrant

The block contains the following on entry:

        R1+0    window handle
        R1+4    visible area minimum x coordinate
        R1+8    visible area minimum y coordinate
        R1+12   visible area maximum x coordinate
        R1+16   visible area maximum y coordinate
        R1+20   scroll x offset relative to work area origin
        R1+24   scroll y offset relative to work area origin
        R1+28   current graphics window minimum x coordinate
        R1+32   current graphics window minimum y coordinate
        R1+36   current graphics window maximum x coordinate
        R1+40   current graphics window maximum y coordinate

This call is used to redraw the borders of icons in the window that are not
up-to-date, this SWI is typically called during the redraw loop of a window.
The SWI will update the window, drawing borders around any icons which have
the b command specified in the validation string and are within the
specified graphics window.

The code to border icons and windows is outlined in the section Programming 
Interface. 

Wimp_BorderIcon (SWI &81680)

None 




Wimp_ClaimInterface (Interface_Initialise) (SWI &81682)

R0 = task handle
R0 preserved

Interrupts are not defined
Fast interrupts are enabled

Processor is in SVC mode

SWI is not re-entrant

This SWI allows your application to use pointers via the Interface module.
This SWI should be called at the beginning of your program. If you don't use 
Wimp_ClaimInterface then your pointers will not be displayed.

Wimp_ReleaseInterface (SWI &81683)

None




Wimp_ReleaseInterface (Interface_CloseDown) (SWI &81683)

R0 = task handle
R0 preserved

Interrupts are not defined
Fast interrupts are enabled

Processor is in SVC mode

SWI is not re-entrant

This SWI stops your application from using pointers. When this SWI is called 
Interface Manager will erase any workarea pointers assigned to your
application and free the memory. This should be called in your exit handler,
also if an error occurs you should also call this SWI to stop other
applications from gaining your pointers.

Wimp_ClaimInterface (SWI &81682)

None




Wimp_SetWorkareaPointer (Interface_SetWorkareaPointer) (SWI &81684)

R1 = pointer to block
R1 preserved

Interrupt status is undefined
Fast interrupts are enabled

Processor is in SVC mode

SWI is not re-entrant

The block contains the following on entry:

        R1+0    window handle
        R1+4    minimum x coordinate of bounding box
        R1+8    minimum y coordinate of bounding box
        R1+12   maximum x coordinate of bounding box
        R1+16   maximum y coordinate of bounding box
        R1+20   24 bytes of pointer data

This specifies the pointer for an area of the window.
The bounding box coordinates are given relative to the window's work area
origin. R1+4 to R1+16 can be set to -1 to specify the whole of the window's
work area. The pointer data at +20 to +44 contains the sprite name and any
x, y offset, see validation strings for more information.

Wimp_RemoveWorkareaPointer (SWI &81685)
Wimp_PollPointer (SWI &81686)

None





Wimp_RemoveWorkareaPointer (Interface_RemoveWorkareaPointer) (SWI &81685)

R0 = task handle
R1 = pointer to block

R0 preserved
R1 preserved

Interrupt status is undefined
Fast interrupts are enabled

Processor is in SVC mode

SWI is not re-entrant

The block contains the following on entry:

        R1+0    window handle
        R1+4    minimum x coordinate of bounding box
        R1+8    minimum y coordinate of bounding box
        R1+12   maximum x coordinate of bounding box
        R1+16   maximum y coordinate of bounding box

This call removes a previously installed pointer from the list of active
pointer areas for the specified window. When a window is deleted you should
remove any pointers that were related to the window, otherwise these
pointers may become active on any window which gains the same window handle
in the future.

The bounding box coordinates are given relative to the window's work area
origin. R1+4 to R1+16 can be set to -1 to specify the whole of the window's
work area. R1+4 to R1+16 may be set to 0 to remove all work area pointers
assigned to the window.

Wimp_SetWorkareaPointer (SWI &81684)
Wimp_PollPointer (SWI &81686)

None





Wimp_PollPointer (Interface_Poll) (SWI &81686)

R0 = Wimp_Poll reason code
R2 = task handle

R0 preserved
R@ preserved

Interrupt status is undefined
Fast interrupts are enabled

Processor is in SVC mode

SWI not re-entrant

This call checks to see if the pointer is up-to-date. If the pointer is not
up-to-date it will change to the pointer specified in the icons validation
string. If the pointer is not over an icon then the pointer will change
according to the position on the window background.

Note that wimp_poll reason codes 0 and 4 should not be masked out, otherwise
the pointer will be out-of-date and will not function correctly.

Wimp_SetWorkareaPointer (SWI &81684)
Wimp_RemoveWorkareaPointer (SWI &81685)

None





Wimp_SendInformation (Interface_SendHelp) (SWI &81687)

R1 = message block as returned from help application
R1 preserved

Interrupt status is undefined
Fast interrupts are enabled

Processor is in SVC mode

SWI not re-entrant

This call returns a help text message to the interactive help application.
It should be called when a message with the number &502 is received and the
pointer is over an icon. If there is a message in the icons validation string
that the pointer is currently over then this will be sent to the help
application. It is up to the applications programmer to take care of the
help message when the pointer is over the icon on the icon bar or is over
the window workarea.

None

None


Wimp_PreProcessKey (Interface_PreProcessKey) (SWI &81688)

R0 = event type
R1 = event block
R2 = task handle

R0 = updated to new event type
R1 = updated event block
R2 = 0 if event was not dealt intercepted

This call pre-processes the up, down, tab, shift-tab keys and any specified
in a specific icons validation string using the command k<keycode>. The SWI
will move icon, if neccessary or activate a button. This call should be
called after the wimp_poll command, it will match the key to an icon and if
neccessary modify your wimp poll block and event type.


Wimp_BorderPlotIcon (Interface_Plot3dIcon) (SWI &81689)

R0 = window state (either from wimp_update/redraw or from a wimp_getwindowstate)
R1 = icon block as for Wimp_PlotIcon

This call plots a border on a window like Wimp_PlotIcon. The icon block
passed in R1 should contain a block as described for Wimp_PlotIcon in the
PRMs.

Wimp_BorderBoundingBox (Interface_BoundingBox) (SWI &8168A)

R1 = icon block as for Wimp_PlotIcon

R1 = updates icon block
          
          offset
          0         min x
          4         min y
          8         max x
          12        max y
          16        border width
          20        button slab state (1 = out, 0 = in)

This call returns information about the icon block passed to it. If you wish
to get the size of an icons box use Wimp_GetIconState and then pass the icon
block returned to this function.



Changes from version 1.32

this version has been fully re-written using the acorn aof assembler.
border type has changed to z to avoid conflicts with risc-os 3
Interface_Plot3dIcon has been changed so the first parameter is a window
state block instead of a window handle  names has changed to interface_....,
old names are still supported better redraw code to correct problems with
multi-sync modes where the icons were not alligned correctly.
Interface_BoundingBox now returns the state of the button new border types

*command to allow changes in the slabbing colours.