*********************  Interface 1.25 (c) Simon Huntington ******************* 


*********************************************************************************
*********************************************************************************
*********************************************************************************
*********************************************************************************
*                                                                               *
* Modification : You now pass the task handle in R2 when using Wimp_PollPointer *
*                                                                               *
* Shading is now done with the light from the top left as in Impression II      *
*                                                                               *
*********************************************************************************
*********************************************************************************
*********************************************************************************
*********************************************************************************

 Software Interrupt 1990


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

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)     
       Charron BBS         (0420 63115)
       Noah BBS            (0272 572322)
       MegaNet             (0924 223456)

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


A version of this document in Impression format can be obtained by sending a 
blank disc and return postage to me.  I will also stick on a modified Formed
to display Interface windows


All correspondence should be addressed to:

        SoftWare Interrupt
        40 Castle Ings Gardens
        New Farnley
        Leeds
        LS12 5EG


**************** 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 border-type {border-spec} | 
                        r on/off-type {,icon-number}* |
                        u on/off-type {,icon-number}* |
                        p text-string {,x} {,y} |
                        i text-string   
  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.

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

if 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 SWI Calls *********************************

Wimp_BorderIcon (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 n 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 (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 (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 (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 (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 (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 (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_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


************************* Programming Hints & Tips **************************

This section gives hints and tips on how to program your application to make the 
most of Interface Manager.  In the examples q% is used as a block of memory, 
action% is the reason code returned by SWI "Wimp_Poll" and task_handle% is the 
task handle.

The following code should be used to claim Interface so that the pointers may be 
used.

        SYS "Wimp_Initialise", 200, &4b534154,"Interface" TO , task_handle%
        SYS "Wimp_ClaimInterface", task_handle%        : REM claim interface


The following code should be used when a redraw event is returned from 
Wimp_Poll.

        SYS "Wimp_RedrawWindow",, q% TO flag%           : REM  get area to redraw
        WHILE flag%                                     : REM  redraw = TRUE
                SYS "Wimp_BorderWindow",, q%            : REM  border all icons
                SYS "Wimp_GetRectangle",, q% TO flag%   : REM  get next rectangle
        ENDWHILE                                        : REM  see if anymore


The following code should be used when a mouse_click event is returned from 
Wimp_Poll.

        SYS "Wimp_BorderIcon",, q%                      : REM  highlight icon
        ....                                            : REM  insert your code
        ....                                            : REM  here
        q%!8 = 0                                        : REM  set button state to
                                                        : REM  0 (switch off)
        SYS "Wimp_BorderIcon",, q%                      : REM  switch off


The following code should be used to to install a on the workarea.  Note this pointer 
will take up the whole of the window workarea.

        q%!0 = window_handle%                           : REM window to install pointer  
        q%!4 = -1                                       : REM whole workarea = - 1
        q%!8 = -1                                       : REM whole workarea = - 1
        q%!12 = -1                                      : REM whole workarea = - 1
        q%!16 = -1                                      : REM whole workarea = - 1
        $(q%+20) ="ptr_hand,5,5" + CHR$0                : REM ptr & point (no spaces)
        SYS "Wimp_SetWorkareaPointer",, q%              : REM set the pointer


The following code should be used to to remove all pointers from a window.  This 
should be called when you delete a window.

        q%!0 = window_handle%                           : REM window to clear
        q%!4 = 0                                        : REM all pointers = 0
        q%!8 = 0                                        : REM all pointers = 0
        q%!12 = 0                                       : REM all pointers = 0
        q%!16 = 0                                       : REM all pointers = 0
        SYS "Wimp_ReleaseWorkareaPointer", task_handle%, q%     
                                                        : REM release the pointers

The following code should be used to to send help to the help application.  This 
should be called when you receive a message with an identifier of &502.

        CASE q%!16 OF                                           : REM check message
                WHEN &502 : SYS "Wimp_SendInformation",, q%     : REM message help              
                                                                : REM request, so
                                                                : REM send help



The following code should be placed directly after your SYS "Wimp_Poll" to switch 
pointer.

        SYS "Wimp_PollPointer", action%,, task_handle%  : REM call swi with reason code



The following code should be used to to release Interface.

        SYS "Wimp_ReleaseInterface", task_handle%       : REM release Interface


 

