WimpExtension document: Manual                                        Doc 01
============================================================================

                     ___________________________________

                     WimpExtension II 3.38 (13-Apr-1995)
                     ___________________________________


                           (c) DoggySoft, 1992-1995



Licence
=======


You can give copies of WimpExtension II, with or without the accompanying
documentation and example application, to anybody you like, as long as you
do not make any money out of doing so. You can, however, include
WimpExtension II with other commercial products. ie: You can sell a program
which uses WimpExtension II, and include WimpExtension II with it, but you
cannot sell WimpExtension II on its own.

Please note that this licence includes all libraries included with this
distribution of WimpExtension II. Libraries obtained elsewhere, however,
will have a separate licence and you should refer to the documentation for
those libraries.

There is no warranty at all, express or implied. If anything goes wrong
inform DoggySoft and we'll try to fix any problems you find as soon as
possible.


NB  If you find any bugs in WimpExtension II, or you think there should be
--  some extra feature included, don't just sit there muttering to yourself,
    tell us about it.



Authors
=======

WimpExtension I was written by Jon Ribbens of DoggySoft.

WimpExtension II was written by Jon Ribbens and James Ponder, both of
DoggySoft.



Introduction
============

WimpExtension is designed to make the task of programming the Wimp easier.
It also enables you to use 3D icons (like Impression). It is designed to
enable you, when you are writing your programs, to think less 'It's a
Desktop program' and more 'It's a program to do...'. It has been written
over a period of more than three years, reaching over twelve thousand lines
of source code, hopefully carefully designed to be as easy to use as
possible.

You use WimpExtension by a set of SWI (BASIC's SYS) commands. There are
calls to put icons on the iconbar, to change the pointer shape, to pop icons
in and out, link windows so they move about together (for toolboxes and
windows-in-windows), there are facilities for options window handling, for
dialogue boxes, for controlling indirected icons, for loading templates, for
colour menus, for RAM templates, for dragging icons, for menu handling, for
draw-files and sprites, for immediate windows, for memory management, for
making sliding bars, etc., etc.

This manual explains all the features of WimpExtension, and how to use them.
There is an accompanying example application, ExtDemo, which should be
included with the WimpExtension module. This shows off some of the features
of WimpExtension. It is written in BASIC so that you can see how it works.

WimpExtension II is improved from WimpExtension I in that the features it
provides are stored in 'library' files, and hence features which are not
being used do not need to be loaded into memory.

New to WimpExtension II is the WExtCols application which you can include
with any program you write and allows the user to configure the style of the
3D Icons that WimpExtension II provides.



Libraries
=========

The useful features of WimpExtension II are provided by 'libraries'. In this
context, a library is a piece of code which can be loaded into memory and
used by many desktop applications simultaneously. WimpExtension II provides
many features, not all of which will be used by all applications. Libraries
are used so that you do not have to load features which you are not using.

The main WimpExtension module file, "WimpExt", provides a set of core
routines which handling loading and processing of libraries. This is
referred to as the 'kernel'. The kernel is almost entirely concerned with
keeping track of which libraries are where, which tasks are using them, and
with passing requests from applications onto the relevant libraries.

Libraries are stored in library files on disc. Each library file can contain
many libraries. An application is provided, "ExtLibMan", to create library
files and to insert and remove libraries from them. With your WimpExtension
applications, you will need to provide a library file containing the
libraries which are used by your application.

Each library can have 'dependencies' - these are other libraries which this
library needs to operate. When you load a library, all the libraries it
depends on will automatically be loaded as well.

The features of WimpExtension II have been grouped together into sets of
related functions, and each set has been placed in a separate library. This
manual details the features of each set in turn. The first set to be
considered will be the kernel functions.



General points
==============

* WimpExtension needs to know which task is calling it. It is told when you
  call WimpExt_Initialise or WimpExt_Action, but calls to Wimp_Poll may
  change it (as other tasks call it). If you have not called
  WimpExt_Initialise or WimpExt_Action since the last Wimp_Poll, therefore,
  you should call WimpExt_CurrentTask to tell WimpExtension your task
  handle.

* In general, all strings are control-terminated, ie. they may not contain
  any characters less than 32, which are treated as terminators.

* Some features of WimpExtension are controlled by the validation strings of
  icons. To have a validation string, the icon must be indirected text (plus
  sprite if you want). (If you don't want text, make it text, just don't put
  any text in it.) Validation commands are separated by semicolons; you can
  put as many as you want on a single icon. You shouldn't use the same
  command twice, unless you are specifically told you can. (The behaviour is
  undefined if you do - ie. different versions of WimpExtension may do
  different things.)

* Since it claims workspace for tasks it knows about, WimpExtension MUST
  know when a task closes down. You should therefore, always call
  WimpExt_CloseDown before your task exits. To catch any unavoidable slips
  (eg. Address Exceptions in BASIC) WimpExtension initialises a module task
  which will call WimpExt_CloseDown for any tasks that exit. You must not
  rely on this though.

* You must assume that all SWIs corrupt R0, even if they are not using it to
  return a result.

* Because WimpExtension provides more than 64 SWIs, another module called
  'WimpExtShadow' appears in the module list. This is perfectly normal and
  should be ignored.  WimpExtension has SWI chunks &45780 and &46380.

* Icon-handling SWIs are intelligent and will only redraw an icon if its
  state has changed - this is to reduce flicker. For example, if you ask
  WimpExtension to set an icon which is already set, it will do nothing.

* If no error is returned from a SWI, then all processor flags will be
  preserved (except the V flag, which is cleared) unless otherwise
  stated in the documentation for that SWI.



============================================================================
Library: --- Kernel
============================================================================
Dependencies: None


WimpExt_Initialise       &45780
-------------------------------
R0 = 17
R1 = task handle
R2 = features flags
       bit     meaning
       0       reserved; MUST BE 0
       1       Automatically recreate menus if set
       2       reserved; MUST BE 0
       3       Automatically compact heap once a second if set
       4       'Correct' radio icons if set
       5       semi-automatic help if set, automatic otherwise
       6       Use alternative parameters for flag-setting SWIs if set
       7       Use R0 of WimpExt_SetIconString[N]
       8       Automatically call WimpExt_MoveCaret
       9       Unset other icons in ESG when setting icons
       10      Automatically call WimpExt_ViewIcon after moving caret
       11      Do not allow TAB for moving between writeable icons
       12-31   reserved; MUST BE 0
R3-> task name (max 32 characters)
Exit:
R0 = WimpExtension version number * 100

Must be called prior to using any other WimpExt calls. R0 must be 17 on
entry. This is so that WimpExtension can work out what version the program
thinks it is calling (so I can change the functionality of calls later whilst
still retaining backwards-compatibility). R2 holds features flags, for
specifying certain things at start-up. Note that WimpExtension will take a
copy of the task name pointed to by R3.

If bit 1 is set then if the user selects a menu option with the ADJUST
button then the menu will automatically be recreated when you next call
WimpExt_PrePoll (assuming you used 'WimpExt_CreateMenu' to create the menu,
that is).

If bit 3 is set then WimpExtension will automatically compact your heap
once a second.

If bit 4 is set then the user won't be able to deselect all of a group
of radio icons by clicking adjust on the selected icon. (This is usually
the desired effect, and the Wimp provides no method of doing it
automatically.)

If bit 5 is set then instead of automatically reading help strings from
validation commands stored in your icons, WimpExtension will send you a
message with a suggested string. You can then pass that to WimpExt_SendHelp
or alter the message. See the "Help" section for more information.

If bit 6 is set then SWIs that allow you to set icons will allow you
to pass unset/set/toggle as 0, 1 or 2 - instead of unset/set as 0 or not 0.

If bit 7 is set then WimpExt_SetIconString[N] checks R0 to see if it
should attempt an ellipsis.

If bit 8 is set then up/down arrows will be processed automatically
for you to move between writable icons.

If bit 9 is set then if you set an icon to be selected then all the
other icons in the ESG will be automatically unset - extremely useful when
set configuration windows.

If bit 10 is set then when the caret is set using WimpExt_PutCaretIcon or
automatically if bit 8, the icon will be made visible by moving the scroll
bar of the window if not in view at the time.

If bit 11 is set then TAB (or SHIFT-TAB) will not move between icons.


WimpExt_CloseDown        &45781
-------------------------------
R0 = task handle

Must be called prior to the task calling Wimp_CloseDown.


WimpExt_PrePoll          &457B4
-------------------------------
R0 = mask
R1-> Wimp_PollIdle block
R2 = Wimp_PollIdle time (OS_ReadMonotonicTime+X)
Exit:
R0 = mask (possibly altered)
R2 = Wimp_PollIdle time (possibly altered)

For WimpExtension to function you must use Wimp_PollIdle and not Wimp_Poll,
this is so that WimpExtension can enable null events if it needs to (for
example to redraw a slider). Note that on exit, R0 will never have bits SET
which were previously CLEAR, and R2 will never be increased, only decreased.
If you do not want any null events set bit 0 of the mask in the usual way.
To receive as many null events as possible, clear bit 0 in the mask and make
R2 = 0.


WimpExt_Action           &45784
-------------------------------
R0 = task handle
R1-> Wimp_PollIdle block
R2 = Wimp_PollIdle reason code
Exit:
R0 = Wimp_PollIdle reason code (possibly altered)
block pointed to by R1 possibly altered

To be called immediately after Wimp_PollIdle. WimpExtension may alter the
code returned - eg. if the user clicks in a requester window then the code
will be translated before your program gets to see it.


The general structure of your program, therefore, will be:

    SYS "Wimp_Initialise",200,"TASK","My Program" TO wimpver%,task%
    SYS "WimpExt_Initialise",17,task%,%010101,"My Program"
    WHILE NOT quit%
      SYS "WimpExt_PrePoll",%010100,q%,time% TO mask%,,time%
      SYS "Wimp_PollIdle",mask%,q%,time% TO reason%
      SYS "WimpExt_Action",task%,q%,reason% TO reason%
      ...
    ENDWHILE
    SYS "WimpExt_CloseDown",task%
    SYS "Wimp_CloseDown",task%,"TASK"
    END


WimpExt_Redraw           &45783
-------------------------------
R1-> Wimp_RedrawWindow block

To be called in the window redraw loop to draw 3D borders, sliders, etc.

You must call WimpExt_Redraw or WimpExt_AutoRedraw when you receive a redraw
request, if the window being redrawn contains anything which is handled
by WimpExtension (eg. 3D borders). Your redraw loop will probably look
something like this:

    SYS "Wimp_RedrawWindow",,q% TO flag%
    WHILE flag%
      SYS "WimpExt_Redraw",,q%
      ...
      SYS "Wimp_GetRectangle",,q% TO flag%
    ENDWHILE

You must set all windows which contain WimpExtension graphics to NOT be
'auto-redraw', so that redraw requests are sent to your program for those
windows.


WimpExt_AutoRedraw       &45798
-------------------------------
R1-> Wimp_Poll reason code 1 block

This call can be used instead of the normal Wimp_RedrawWindow/GetRectangle
loop if the window doesn't contain any graphics drawn by your program. It
does the equivalent of:

    SYS "Wimp_RedrawWindow",,q% TO flag%
    WHILE flag%
      SYS "WimpExt_Redraw",,q%
      SYS "Wimp_GetRectangle",,q% TO flag%
    ENDWHILE


WimpExt_Intersect        &46387
-------------------------------
R0 = 0 : Boxes in registers:
  R2 = XMin1
  R3 = YMin1
  R4 = XMax1
  R5 = YMax1
  R6 = XMin2
  R7 = YMin2
  R8 = XMax2
  R9 = YMax2
R0 = 1 : Boxes in blocks:
  R2-> XMin1,YMin1,XMax1,YMax1
  R3-> XMin2,YMin2,XMax2,YMax2
Exit:
If boxes intersect:
R0 = 1, C flag set
If boxes don't intersect:
R0 = 0, C flag clear

Checks whether the specified rectangles intersect.


WimpExt_MiscOp           &4638A
-------------------------------
R0 = reason code
other registers as appropriate for reason code

R0 = 0 : Read defaults
----------------------
R1-> block to contain values (64 bytes long)
Exit:
R1 +  0 = bottom-right colour (4)
R1 +  4 = top-left colour (0)
R1 +  8 = in colour for sync buttons (14)
R1 + 12 = channel colour (12)
R1 + 16 = minimum slabbing time (15)
R1 + 20 = flags
          bit    meaning
          0-31   reserved
R1 + 24 = in colour for async buttons (2)

Reads in the default values from the 3DIcons library as specified by
*WimpExt Colours. The block should be at least 64 bytes long, to allow room
for future expansion. If 3DIcons is not loaded an error will occur.

R0 = 1 : Read window border thickness
-------------------------------------
Exit:
R2 = title thickness (OS Units)
R3 = vertical scrollbar thickness (OS Units)
R4 = horizontal scrollbar thickness (OS Units)

Reads the thickness of the window borders. Needed because on RISC OS 3 Acorn
rather stupidly decided to make it so that you can change their thickness.

R0 = 2 : Read window handle of requester window
-----------------------------------------------
Exit:
R0 = window handle, or -1 if requester window is closed

Reads the window handle of the requester window.

R0 = 3 : Find validation command
--------------------------------
R1-> validation string
R2 = validation character to find (prefixed with 'w')
Exit:
R1-> parameters of command, or 0 if command not found

Searches a validation string for a 'w<character>' commmand.

R0 = 4 : Read 3D border colour command type
-------------------------------------------
Exit:
R0 = 0 (type) or -1 if 3DIcons is not loaded

This returns the state of the '*WimpExt Colours' command, this present
version of WimpExtension will always return 0 but if the syntax changes
it will be incremented.  This is of use to the WExtCols application.

See the *commands section for more details on WimpExt Colours.

R0 = 5 : Read menu state
------------------------
Exit:
R0 = 0 - closed
   = 1 - unknown
   = 2 - open

This call will tell you if your task has a menu open, it relies on you
calling WimpExt_CreateMenu instead of Wimp_CreateMenu to know when you open
a menu.  On RISC OS 2 there is no way of knowing when the Wimp closes a
menu for you, so it will go into an 'unknown' state.


WimpExt_CurrentTask      &4578B
-------------------------------
R0 = task handle
Exit:
R0 = previous task handle

Informs WimpExtension which task is currently active. Not needed if you have
called WimpExt_Initialise or WimpExt_Action since the last Wimp_Poll. The
previous user is returned in R0.


WimpExt_BackgroundTask   &47390
-------------------------------
R0 = version indicator
R1 = task handle (or 0 if you don't have a task handle)
R2 = features flags
R3-> name (or 0 if you don't have a name)
NB: R0,R2-R3 are not needed if you are passing a task handle.
Exit:
R0 = old version indicator
R1 = old task handle (or 0 if the previous user wasn't a Wimp task)
R2 = old features flags
R3-> old name

Informs WimpExtension that a different program wishes to use WimpExtension's
SWIs. This call is provided so that non-Wimp-tasks can use WimpExtension
SWIs. After finishing using the SWIs you should restore the previous user by
calling WimpExt_BackgroundTask with the parameters returned from when you
claimed it. ie:

  SYS "WimpExt_BackgroundTask",17,0,0,"MyPatch" TO R0%,R1%,R2%,R3%
    ... use WimpExtension SWIs ...
  SYS "WimpExt_BackgroundTask",R0%,R1%,R2%,R3%

Only pass a task handle to WimpExt_BackgroundTask if you have called
WimpExt_Initialise previously (ie. WimpExt_BackgroundTask will call
WimpExt_CurrentTask).


WimpExt_Divide           &45796
-------------------------------
R2 = Numerator
R3 = Denominator
Exit:
R0 = Result
R2 = Remainder

Returns (R2 DIV R3) in R0 and (R2 MOD R3) in R2. Useful for calculating
which area of window needs to be updated. An error is produced if R3 is zero
on entry.


WimpExt_ServiceCall      &46391
-------------------------------
R1 = service number
other registers are parameters and depend on the service number
Exit:
R1 = 0 if service was claimed, preserved otherwise
other registers up to R8 may be modified if the service was claimed

Issues a service call to all currently loaded WimpExtension libraries. Note
that the service numbers are not the same as for module service calls.


WimpExt_CallLibrary      &4638F
-------------------------------
R0 = top two bytes:    library number
     bottom two bytes: reason code
R1-R8 depend on the library
Exit:
R0-R8 depend on the library

Calls the specified library. The registers depend on which library is being
called.


WimpExt_LibraryOp        &4638E
-------------------------------

R0 = 0 : Ensure library module(s) present
-----------------------------------------
R1-> list of library specifiers

The list pointed to as follows consists of zero or more two-word pairs, and
a single-word -1 value for a terminator. Each two-word pair is one word
module specifier, and one word version specifier (the version number
multiplied by 100 - eg. 2.10 is 210).

Library module specifiers, function identifiers and current version numbers
are listed in the library file.

Note that some library routines may require other library routines - eg. Sort
requires MemMove. In these cases the required library will be loaded
automatically for you, even if you don't specify it explicitly.

Note that any libraries you request will be noted as being used by your task.
These libraries will then not be allowed to be killed. When your task calls
WimpExt_CloseDown, the libraries will be freed again. If you wish to free
libraries without quitting your task, use LibraryOp 8.

R0 = 1 : List libraries already loaded
--------------------------------------
R1-> block to contain library numbers and version numbers
R2 = size of block
R3 = continuation value (0 to begin with)
Exit:
R2 = space free in block
R3 = new continuation value (-1 if there are no more libraries)

Reads in a list of the currently loaded libraries.

R0 = 2 : Read highest available version number of library
---------------------------------------------------------
R1 = library number
Exit:
R0 = version number *100 of library in memory, or 0 if the specified library
     isn't in memory
R1 = version number *100 of library on disc, or 0 if the specified library
     isn't on disc

Reads the highest available version number of the specified library in the
library file(s), and the version number in memory.

R0 = 3 : Add file to library search path
----------------------------------------
R1-> full pathname of file

Adds the specified file to the list of files to be searched for libraries.
The file will be automatically removed again from the list when your task
quits.

R0 = 4 : Remove file from library search path
---------------------------------------------
R1-> to full pathname of file

Removes the specified file from the list of files to be searched for
libraries.

R0 = 5 : Add file to library module search path permanently
-----------------------------------------------------------
R1-> full pathname of file

Adds the specified file to the list of files to be searched for libraries.
The file will NOT be removed from the list when your task quits.

R0 = 6 : Read address of library
--------------------------------
R1 = library number
Exit:
R0-> library, or 0 if library not loaded

Locates the specified library in memory.

R0 = 7 : Deregister libraries
-----------------------------
R1-> list of library specifiers

The list pointed to as follows consists of zero or more two-word pairs, and
a single-word -1 value for a terminator. Each two-word pair is one word
library specifier, and one word unused (which may contain any value). The
specified libraries will be noted as no longer being used by your task. You
cannot use any of the facilities of any libraries you de-register.

R0 = 8 : Deregister all libraries
---------------------------------

Deregisters all libraries that your task is registered with.

R0 = 9 : Kill library
---------------------
R1 = library number

This removes the library from memory. Returns an error if the library is
currently in use.

R0 = 10 : Library file modified
-------------------------------
R1-> full pathname of file

Informs WimpExtension that the specified library file has been modified.
WimpExtension will rescan the file and update its cached data. If the file
is not registered with WimpExtension as a library file then no action is
taken.


Hotkeys
-------

If you aren't using WimpExtension, and you want your task to provide a
hot-key (ie. a key which does something even when your task doesn't have the
caret) then you have to open a window permanently somewhere off the screen.
This wastes memory on RISC OS 3, and means that you run out of windows even
more quickly than usual on RISC OS 2.

WimpExtension opens a hot-key window for you, and then will tell you about
any key-press events it is given. This saves on resources because one window
is shared between all WimpExtension tasks.

When WimpExtension receives a keypress event, it broadcasts a message as
follows:
  R1+16 = &45790
  R1+20 = key code

If you decide to do something with the keypress, you should acknowledge the
message to prevent WimpExtension from passing it on to other tasks.



============================================================================
Library: &18 3DIcons 1.00
============================================================================
Dependencies: &16 Caret, &12 Icons

The 3DIcons library provides a validation command and several SWIs. It is
used for giving your program a 3D look.

3D borders are treated as user graphics, so the 'auto-redraw' flag in the
window definition should not be set. 3D borders are controlled by the 'w'
validation command:

  'w' (border type)
    Syntax:
      w<border number>,<slabbing mask>,<slabbing time>,<top left colour>,
       <bottom right colour>,<popped in colour>,<popped out colour>,
       <channel colour>

All the numbers apart from the border number are optional. The defaults are:
wxx,5,15,4,0,1,14,12. These defaults can be changed by the user, using the
WExtCols application. You may specify only some, eg: w2,4,20 or w2,,,,3. It
is recommended that you specify as few as possible parameters, as the values
which you leave unaltered can be set by the end-user, who can then change
the colour scheme to his/her preferred choice.

The border numbers are:

     0  : Standard 3D border. Used for buttons. Pops in if clicked on.
     1  : Ridged grouping border. Use it to group functional sections of a
          window.
     2  : Like 0, with a channel round it. Used for the default button (ie.
          the one that is pressed if you press RETURN).
     3  : Wide border for writeable icons - leave the normal black border on
          the icon and make the background white.
     4  : Popped in border - for things that are for information only.
     5  : Trenched border - the opposite of border 1. Can be clicked on.
          Suggested use is as an alternate border 1.
     6  : Title border - similar to border 0, but with two 'dents'.
          This border is designed to be used as the title of a group, with
          a border 1 icon behind it as the frame - see ExtDemo for examples.

The slabbing mask specifies which mouse buttons will cause the icon to be
popped in. This is normally 5 (which is %101, ie. both select and adjust
cause the icon to be popped) but sometimes 7 is used - for example on icons
which a menu appears on all three buttons.

If you add 8 to the border number, it will become inert - ie. it will ignore
all mouse clicks and not pop in. Bordered icons should be filled, and you
should initially set the background colour of the icon to the out-colour.

If you add 16 to the border number, it will become an async button - ie. it
will pop in and stay popped in until the user clicks on it again or you call
WimpExt_SlabIcon to force it out. This is for tool-bars and you can look at
ExtDemo to see what it looks like. There is a BorderOp to read the current
popped in async button in an ESG (WimpExtension will autotmatically pop out
all other async buttons in the same ESG).

Anti-aliased font icons are now supported. If a font is used in the icon, it
MUST have an 'F' validation command, as the Wimp needs this to specify the
icon's colour. Note that slabbing font icons doesn't look very good in
16-colour modes, due to there not being enough colours for effective
anti-aliasing (this isn't WimpExtension's fault, it's just a fact of life).

If you set the in-colour and out-colour the same then the icon won't ever be
slabbed in or out. If you really really want an icon which doesn't change
colour when slabbed in and out unset the 'Filled' flag. I don't recommend
having icons which don't change colour, anyway - they look awful.

Note that when WimpExtension redraws border type 6, WimpExtension fills the
icon at the same time. This means that you only very very briefly see the
ridged border behind it, if at all.


WimpExt_SlabIcon         &45782
-------------------------------
R2 = window handle or 0 for slabbed icon
R3 = icon handle
R4 = flags:
     bit     meaning if set
      0      slab in, otherwise slab out
      1      use async list, otherwise use sync list
     2-31    reserved; MUST BE 0

To be called to force an icon to be slabbed (for example to slab the default
action icon if RETURN is pressed). The icon will be popped in or out
depending on R4. If R2 is zero then all the icons in the specified list are
used (remember that if you do this to the async list then it could leave
some ESGs with no icon selected).

If you specify an async button and list, then the other icons in the ESG
(if the ESG is not 0) will be unslabbed and removed from the list.


WimpExt_PlotBorder       &457BD
-------------------------------
R0 = reason code
 R0 = 0  =>  R1-> icon block
             R2 = window handle (or -1 for no window)
 R0 = 1  =>  R1-> block:
               R1 + 0  Minimum work area x coordinate
               R1 + 4  Minimum work area y coordinate
               R1 + 8  Maximum work area x coordinate
               R1 + 12 Maximum work area y coordinate
               R1 + 16 Border type
             R2 = window handle (or -1 for no window)

Like Wimp_PlotIcon, except it just redraws the 3D border. R0 specifies how
the coordinates and border type are to be specified. If bit 31 of R0 is set
then the border will be plotted slabbed in.


WimpExt_BorderOp         &46388
-------------------------------
R0 = reason code
other registers as appropriate for reason code

R0 = 0 : Get border number
--------------------------
R1-> icon block
Exit:
R0 = border number, or -1 if the icon has no 3D border

Returns the number of the 3D border of the specified icon. -1 is returned if
the icon has no 3D border.

R0 = 1 : Get border width
-------------------------
R2 = border number (0-6)
Exit:
R0 = width in OS units, or 0 if R2 did not contain a valid border number

Returns the width of the 3D border outside the icon's bounding box. 0 is
returned if an invalid border type is specified.

R0 = 2 : Get bounding box in registers
--------------------------------------
R1-> icon block
Exit:
R2 = XMin
R3 = YMin
R4 = XMax
R5 = YMax

Returns the bounding box of the icon, including the 3D border if present.

R0 = 3 : Get bounding box in block
----------------------------------
R1-> pointer to icon block
R2-> pointer to 16-byte block to receive bounding box
Exit:
R2 +  0 = XMin
R2 +  4 = YMin
R2 +  8 = XMax
R2 + 12 = YMax

Returns the bounding box of the icon, including the 3D border if present.

R0 = 4 : Get border parameters
------------------------------
R1-> icon block
Exit:
R0 = slabbed-out colour + slabbed-in colour * 16 or -1 for bad validation
R2 = border-1 colour + border-2 colour * 16
R3 = channel colour + slabbing time * 16

Returns the parameters of the border command, substituting defaults for
unspecified parameters.

R0 = 5 : Read async button state
--------------------------------
R2 = window handle
R3 = icon handle
Exit:
R0 = current state of icon (0 for popped out, 1 for popped in)

R0 = 6 : Get selected async button
----------------------------------
R2 = window handle
R3 = ESG group
Exit:
R0 = Async icon number that is popped in, or -1 for none

Checks the specified window and returns which icon in the ESG is currently
popped in using the async list.



============================================================================
Library: &01 Misc 1.00
============================================================================
Dependencies: None

WimpExt_CopyString       &4579E
-------------------------------
R2-> source string
R3-> destination string

Copies the control-terminated string from R2 to R3. The string stored at R3
will be zero-terminated whatever the terminator was for the original string.


WimpExt_FindLeaf         &457A1
-------------------------------
R0-> pathname
Exit:
R0-> leafname

Finds the last occurence of '.' in the string pointed to by R0, and returns
a pointer to the next character. eg. given 'scsi::HardDisc.$.first.2nd.last'
it will return a pointer to 'last'. This can be useful for both extracting
the leaf name, and for determining what directory the file is in (by poking
a zero to (R0-1) - eg. MOV R2,#0  STRB R2,[R0,#-1] ).



============================================================================
Library: &11 IconBar 1.00
============================================================================
Dependencies: None

Two SWIs are provided for putting icons on the iconbar - one for sprites
only, and one for text-plus-sprite icons. These read the size of the sprite
to get the width of the icon.


WimpExt_IconBarSprite    &45785
-------------------------------
R2 = -2 for left of iconbar, -1 for right
R3-> sprite name
R5 = icon button type (eg. 3)
Exit:
R0 = icon handle

Will place a sprite on the iconbar, returning the icon handle. Note that the
sprite name is copied out of the memory block, which can be reused. Also
note that the number in R5 is just the button type, not the flags.


WimpExt_IconBarText      &45786
-------------------------------
R2 = -2 for left of iconbar, -1 for right
R3-> sprite name
R4-> text (max. 128 chars inc. terminator)
R5 = icon button type (eg. 3)
Exit:
R0 = icon handle

Will place a sprite on the iconbar, with a text message underneath,
returning the icon handle. Note that the sprite name is copied out of the
memory block, which can be reused, but the text remains where it is; this is
so you can change the text after creating the icon. Also note that the
number in R5 is just the button type, not the flags.


WimpExt_MemCopy          &457BB
-------------------------------
R0-> area to copy from (word aligned)
R1-> area to copy to (word aligned)
R2 = length (not necessarily word aligned)
Exit:
R0 preserved

Copies an area of memory very quickly. Can cope with overlap, R0=R1 or R2=0.


WimpExt_SubstituteArgs   &4638C
-------------------------------
R0-> template string
R1-> buffer to hold resulting string
R2 = number or pointer to string for %0
R3 = number or pointer to string for %1
R4 = number or pointer to string for %2
R5 = number or pointer to string for %3
R6 = number or pointer to string for %4
Exit:
R0 = pointer to zero-byte terminator of substituted string

Takes a string of the form 'This is an %0 of the %1 of %2_%3' and
substitutes the given strings when %0,%1,%2,%3 or %4 is encountered. eg:

  SYS "WimpExt_SubstituteArgs","This is an %0 of the %1 of %2_%3",q%,
      "example","use","WimpExt","SubstituteArgs" TO ,string$

would give 'This is an example of the use of WimpExt_SubstituteArgs'. Any
strings not used in the template do not need to have sensible values in the
corresponding register, although you may like to make the register -1, in
which case WimpExtension will fault that string's use. To include a % in the
template, use %%.

WimpExtension II now interprets 0<=Rx<&8000 as a number to be inserted into
the string.



============================================================================
Library: &02 LinkedWindow 1.00
============================================================================
Dependencies: None

Linked windows are good for options windows, lists, toolbars, etc. They
consist of a main window, which is normal, and a subwindow, which moves
around with the main window. The subwindow normally has no titlebar and no
horizontal scrollbar, just the vertical scrollbar, although this is a matter
of style.

WimpExtension makes linked windows very easy - to set up a linked window,
just use SWI WimpExt_LinkWindows, and use WimpExt_OpenLinked and
WimpExt_CloseLinked instead of Wimp_OpenWindow and Wimp_CloseWindow.

To have more than one subwindow in a main window you should link the
subwindows together. eg:
  SYS "WimpExt_LinkWindows",,,mainw%,link1w%,0
  SYS "WimpExt_LinkWindows",,,link1w%,link2w%,0
  SYS "WimpExt_LinkWindows",,,link2w%,link3w%,0
  ...

Note that the sub windows should have the pane flag set.

WimpExt_LinkWindows      &45787
-------------------------------
R2 = main window handle
R3 = sub-window handle
R4 = flags
     bit    meaning if set
     0      clip linked window to the left of the main window
     1      clip linked window to the right of the main window
     2      clip linked window above the main window
     3      clip linked window below the main window
     4      link scroll bars together
     5      link window to the left
     6      link window to the right
     7      link window to the top
     8      link window to the bottom
     9-30   reserved; MUST BE 0
     31     link is hidden

Will link two windows so the sub-window moves with the main window, the
positioning of the sub-window is determined by where the windows are at the
time of this call (eg. you should create your windows in a template editor
so that they are where you want them to be when linked together).

Bit 4 will link the scroll bar offsets of both windows together, so that if
you scroll either window the other window follows suit.

Under WimpExtension II you must specify how to link the window, normally you
will set bits 5,7 and clear 6,8.


WimpExt_OpenLinked       &45788
-------------------------------
R1-> Wimp_OpenWindow block

To be used instead of Wimp_OpenWindow. It does the same thing, but if the
window is linked then it will handle the link. If the window is not linked,
it has the same effect as Wimp_OpenWindow.


WimpExt_CloseLinked      &45789
-------------------------------
R1-> Wimp_CloseWindow block

To be used instead of Wimp_CloseWindow. It does the same thing, but if the
window is linked then it will close the linked window as well. If the window
is not linked, it has the same effect as Wimp_CloseWindow.


WimpExt_DeleteLinked     &
--------------------
R0 = main or sub window

Deletes all windows associated with the window you want deleting including
ones linked to the ones linked to the one you specifed etc.

eg. winA-->winB-->winC-->winD

If you ask to delete window B then windows C and D will also be deleted, and
window A will be unlinked from window B


WimpExt_UnLinkWindows    &4578A
-------------------------------
R2 = main window handle
R3 = sub-window handle

Will remove the link between the specified window and its subwindow. Note
that this just removes the pointer in WimpExtension workspace, if the
windows are on the screen they will remain there. You do not have to call
UnLinkWindows before you exit - it is here so that you can unlink windows
while your application is still running.


WimpExt_HideLink         &457A8
-------------------------------
R0 = main window handle
R2 = sub-window handle

Temporarily hides the link between the specified window and its sub-window.
This is useful, for example, for removing toolboxes in such a way that they
can be replaced later. Note that this call does no screen update - ie. the
sub-window remains where it is.


WimpExt_UnHideLink       &457A9
-------------------------------
R0 = main window handle
R2 = sub-window handle

Unhides the previously hidden link. Note that this call does no screen
update - ie. the sub-window remains where it is.


WimpExt_ManualLink       &46389
-------------------------------
R2 = main window handle
R3 = sub-window handle
R4 = flags
     bit    meaning if set
     0      clip linked window to the left of the main window
     1      clip linked window to the right of the main window
     2      clip linked window above the main window
     3      clip linked window below the main window
     4      link scroll bars together
     5      link window to the left with offset of R5
     6      link window to the right with offset of R6
     7      link window to the top with offset of R7
     8      link window to the bottom with offset of R8
     5-30   reserved; MUST BE 0
     31     link is hidden
When applicable (see bits 5-8):
R5 = X offset between left of main and left of sub-window
R6 = X offset between right of main and right of sub-window
R7 = Y offset between top of main and top of sub-window
R8 = Y offset between bottom of main and bottom of sub-window

Will link two windows so the sub-window moves with the main window, the
positioning of the sub-window is not determined by where the windows are
unlike WimpExt_LinkWindows but instead is determined by the offsets you
provide in R5 to R8.

Bit 4 will link the scroll bar offsets of both windows together, so that if
you scroll either window the other window follows suit.

Under WimpExtension II you must specify how to link the window, normally you
will set bits 5,7 and clear 6,8.

If the link is set to only one side instead of both, then the width (or
height) of the window is used.



=============================================================================
Library: &0E LoadTemplates 1.00
=============================================================================
Dependencies: &14 Windows

Using templates usually is quite tedious, as you have to open the template
file and read in the definitions for each window individually, calling
Wimp_CreateWindow for each one and storing the window handle. Using
WimpExtension you just call WimpExt_LoadTemplates and all the windows in the
named file will be loaded and created, and the handles stored in a buffer.

The only time you cannot do this is if you have more than one window that
you want to open multiple copies of. If you have no such windows, you're OK,
if you want one such window then you simply make sure it's the last window
in the templates file, and its definition will be in the buffer after the
SWI call.

Note that by using this call your program is dependent on the order of the
templates in the file. This shouldn't matter, as when you make the templates
file you know what order you've got them in, and nobody else has any
business changing your templates file.


WimpExt_LoadTemplates    &4578C
-------------------------------
R0-> buffer for storing window handles
R1-> user buffer for template (big enough for largest template)
R2-> workspace for indirected icons
R3-> end of workspace for indirected icons
R4-> 256-byte font reference array (-1 for no fonts)
R5-> filename of templates file
R6-> sprite area control block (+1 for Wimp sprite pool)
Exit:
R2 = first free byte in indirected workspace

Loads in all the templates from the file whose name is pointed to by R5, and
called Wimp_CreateWindow for each one. The value in R6 is placed in the
window block at offset +64. Stores the window handles sequentially in the
buffer pointed to by R0, in the order they are found in the templates file.
On exit the buffer pointed to by R1 will contain the template for the last
window in the file. The buffer for window handles should be big enough to
store all the window handles, each of which is a word. For each window, if
the word on entry is zero the window will be created as usual. Bits that are
set have the following meanings:

    Bit   Meaning if set
    ----------------------------------------------
    0     centre window horizontally
    1     don't create window (leave data in buffer)
    2     centre window vertically
    3     ignore window
    4-31  reserved; MUST BE 0

Bit 1 is useful if you have a window in the file as one that you want
repeatedly, but you don't want it created at once.

When a window with bit 1 is encountered R1 (the data pointer) is stored as
the handle and R1 is increased so that the next template can be loaded above
the previous one.

WXI treated bit 1 like bit 3 in WXII.

=============================================================================
Library: &0F LoadRAMTemplate 1.00
=============================================================================
Dependencies: None

This is provided mainly for module tasks, where the templates must be part
of the main code. You can use the supplied BASIC function 'FNtemplate' to
include the template as part of your code, and then use
WimpExt_LoadRAMTemplate to turn this into a window definition.


WimpExt_LoadRAMTemplate  &457A5
-------------------------------
R1-> user buffer for window definition
R2-> workspace for indirected icons
R3-> end of workspace for indirected icons
R4 = -1 for no fonts - fonts not supported at present
R5-> template
Exit:
R2-> end of workspace used (ie. first free byte)

This call is similar to Wimp_LoadTemplate except that it uses templates in
RAM. This is designed to be used in Module tasks, where you cannot have a
separate Templates file. You would use the supplied 'FNtemplate' function to
insert the template in your module, and then call WimpExt_LoadRAMTemplate to
convert this to a window definition. At present fonts in templates are not
supported - this shouldn't cause too much of a problem as fonts in templates
are made largely unnecessary by RISC OS 3.5.



============================================================================
Library: &12 Icons 1.00
============================================================================
Dependencies: &16 Caret

Lots of SWIs are provided for handling icons, eg. setting the string in a
text icon, shading icons, reading a number from an icon, etc... Also some
validation commands are provided for automatic icon shading/setting, etc.


WimpExt_SetIconString    &4578D
-------------------------------
R0 = non-zero for ellipsis (only if enabled in WimpExt_Initialise)
R2 = window handle
R3 = icon handle
R4-> string

Copies the string pointed to by R2 into the specified indirected text icon,
and updates the screen if necessary. If the caret was in the icon then it is
moved to the end of the new string. Only updates the screen if anything was
changed - ie. if the new string is the same as the old string then nothing
will happen.

If R0 is non-zero and bit 7 was set in R2 in WimpExt_Initialise and the
string is longer than the icon can hold then the string will be post-fixed
with '...'.


WimpExt_SetIcon          &4578F
-------------------------------
R2 = window handle
R3 = icon handle
R4 = 0 to deselect icon, non-zero to select icon
If bit 6 of R2 was set in WimpExt_Initialise:
R4 = 0 to deselect icon, 1 to select icon, 2 to toggle icon
Exit:
R0 = old state of icon (0 for unset, 1 for set)

Selects the icon if R4 is non-zero, deselects it otherwise. Updates the
screen if necessary. If bit 6 of R2 was set in WimpExt_Initialise then the
alternative parameters are used as shown. If bit 9 of R2 was set in
WimpExt_Initialise and you are setting the icon, then other icons in the
same ESG will be unset.


WimpExt_GetIcon          &45790
-------------------------------
R2 = window handle
R3 = icon handle
Exit:
R0 = 0 if icon is not selected, 1 if it is selected
R3 = word at iconblock+20 (ie. pointer to indirected text for indirected text
     icon)

Detects whether the icon is selected, and returns 1 in R0 if it is, 0
otherwise. Also returns in R3 then value in the iconblock at offset 20. For
an indirected text icon this will be a pointer to the text.


WimpExt_GetNumberIcon    &45791
-------------------------------
R0 = default base (10=decimal)
R2 = window handle
R3 = icon handle
Exit:
R0 = value

Converts the string in the icon to a signed integer and places it in R0. The
base to be used by default is specified in R0 - it must be in the range
2-36.


WimpExt_SetNumberIcon    &45792
-------------------------------
R0 = base (10=decimal)
R2 = window handle
R3 = icon handle
R4 = value

Converts the signed integer in R4 into a string and places it in the icon.
Updates the screen as necessary. The base to be used is specified in R0 - it
must be in the range 2-36.


WimpExt_IncNumberIcon    &45793
-------------------------------
R0 = base (10=decimal)
R2 = window handle
R3 = icon handle
R4 = maximum value
R5 = step
Exit:
R0 = new value

Converts the string in the icon to an signed integer, adds the step, and
puts it back. Updates the screen as necessary. The value will not go beyond
the value passed in R4, and the new value is returned in R0.


WimpExt_DecNumberIcon    &45794
-------------------------------
R0 = base (10=decimal)
R2 = window handle
R3 = icon handle
R4 = minimum value
R5 = step
Exit:
R0 = new value

Converts the string in the icon to an signed integer, subtracts the step,
and puts it back. Updates the screen as necessary. The value will not go
beyond the value passed in R4, and the new value is returned in R0.


WimpExt_SetIconStringN   &457A0
-------------------------------
R0 = non-zero for ellipsis (only if enabled in WimpExt_Initialise)
R2 = window handle
R3 = icon handle
R4-> string

Copies the string pointed to by R2 into the specified indirected text icon,
and updates the screen if necessary. If the string is longer than the size
of the buffer then the right-hand end of the string is copied (as opposed to
the left-hand end, which is the case if you use WimpExt_SetIconString). If
the caret was in the icon then it is moved to the end of the new string.

If R0 is non-zero and bit 7 was set in R2 in WimpExt_Initialise and the
string is longer than the icon can hold then the string will be pre-fixed
with '...'.


WimpExt_SetIconColour    &457B0
-------------------------------
R2 = window handle
R3 = icon handle
R4 = foreground colour (0-15 or -1 to keep the same)
R5 = background colour (0-15 or -1 to keep the same)
Exit:
R0 = old foreground colour + old background colour * 16

Changes the specified icon's colour(s). If there is no change then the icon
is not updated (ie. it will not flicker). This call will work for anti-
aliased fonts, but the icon MUST have an 'F' validation command, as the Wimp
needs this to specify the icon's colour.


WimpExt_ShadeIcon        &457B1
-------------------------------
R2 = window handle
R3 = icon handle
R4 = 0 to unshade icon, non-zero to shade icon
If bit 6 of R2 was set in WimpExt_Initialise:
R4 = 0 to unshade icon, 1 to shade icon, 2 to toggle shade flag
Exit:
R0 = old state of icon (0 for unshaded, 1 for shaded)

Shades the icon if R2 is non-zero, unshades it otherwise. Updates the screen
if necessary. If the caret was in the icon and you are telling WimpExtension
to shade it then the caret is removed (disowned). If bit 6 of R2 was set in
WimpExt_Initialise then the alternative parameters are used as shown.


WimpExt_ViewIcon         &4638B
-------------------------------
R0 = movement type:
     0 = scroll window minimum amount necessary
     1 = centre icon in window (only if it's currently outside the window)
     2 = choose 0 or 1 depending on how far outside the window the icon is
R2 = window handle (or -1 for caret window and icon)
R3 = icon handle (if R2<>-1)

Checks to see if the specified icon is in the portion of the window which is
visible on the screen, and scrolls the window to display it if it isn't. If
R2=-1 then the icon containing the caret (if if belongs to your task) is
used. R0=2 is the recommended movement type to use.


WimpExt_DragIcon         &4579A
-------------------------------
R0 = flags:
      0-1 Horizontal position:
            00 = left
            01 = middle
            10 = right
            11 = undefined
      2-3 Vertical position:
            00 = bottom
            01 = middle
            10 = top
            11 = undefined
      4-5 Mouse bounding box:
            00 = whole screen
            01 = constrain to parent window
            10 = constrain to box pointed to by R5
            11 = undefined
      6   constrain sprite if set, otherwise constrain pointer
      7   shadow if set
      8   use DragASprite even if CMOS flag isn't set
     9-31 reserved; MUST BE 0
R1-> sprite block, +1 for Wimp sprite area, 0 to use dash box
R2 = window handle
R3 = icon handle
R4-> sprite name (if R1<>0)
R5-> mouse bounding box (only if necessary - see flags)
      +00 xmin
      +04 ymin
      +08 xmax
      +12 ymax

This SWI does one of two things. If the DragASprite module is loaded, and
bit 1 of byte 28 of the CMOS RAM is set, and R1<>0 then it will use the
DragASprite module as follows:
  Work out the parameters to 'DragASprite_Start' and call it. If this
  produces an error then try again with dash box as described below.
Otherwise it makes an ordinary rotating dash box as follows:
  Work out the parameters to 'Wimp_DragBox' and call it. Bits 0-3 and 7 of
  the flags are ignored.
If you are using this SWI at any time with R1<>0 then remember to call
XDragASprite_Stop at appropriate points. You MUST use the X form of the SWI,
and you must ignore errors.

Note that if you want to have the simplest form of drag, with the bounding
box being the entire screen and using a rotating dash-box rather than a
sprite for the drag, then you can simply set R0=R1=0, and not worry about
R4 and R5.


Validation commands: ws, wu
---------------------------

There are a couple of validation commands for helping with radio icons. 'ws'
allows icons to select and deselect other icons when clicked on, and 'wu'
allows icons to shade and unshade other icons.

  'ws'
    Syntax:
      ws<action>,<icon>[,<icon>][,<icon>][,<icon>]...

  'wu'
    Syntax:
      wu<action>,<icon>[,<icon>][,<icon>][,<icon>]...

The action code is as follows:

  0   deselect specified icons
  1   select specified icons
  2   toggle specified icons

The syntax is exactly the same for 'wu' except that the icons will be shaded
instead of selected. You can specify several of these commands in one
validation string - eg. 'ws1,4;wu2,5;ws0,1'.

These SWIs use WimpExt_SetIcon and WimpExt_ShadeIcon and do not need bit 6
in WimpExt_Initialise to use action 2 (toggle).


Validation command: wi
----------------------

If, as is often the case, you have a number in an indirected icon on the
screen and you want the user to be able to alter it, it is nice to have
bumper icons next to it as well as making it writeable. For this purpose, you
can specify that an icon should decrement/increment another icon when clicked
on in the validation string. The syntax of the command is:

   'wi' (increment)
     Syntax:
       wi<icon>,<minimum>,<maximum>,<step>

The default values are: wixx,0,&7FFFFFFF,1. All the values are optional apart
from the icon number. To make it decrement the icon instead, use a negative
step value. If the user clicks with Adjust instead of Select then the icon
will be incremented instead of decremented, or decremented instead of
incremented, in keeping with other RISC OS features.



===========================================================================
Library: &15 Pointer 1.00
===========================================================================
Dependencies: None


Validation command: wp
----------------------

The Pointer library provides a validation command, 'wp', for automatic
pointer changes over icons, and also some SWIs for changing the pointer
shape and bounding box.

   'wp' (change pointer)
     Syntax:
       wp<pointer name>,<x hotspot>,<y hotspot>

The x and y hotspots are optional. What happens is that when the pointer is
over the icon it will changed to the named sprite. The 'hotspot' is the area
that is the actual 'point' of the pointer. Apart from the following supplied
standard pointers, the sprite must be in the Wimp sprite pool.

Standard supplied pointers are:

       ptr_write    (4,4)
        should be used over writeable icons
       ptr_menu     (6,5)
        should be used over icons that lead to menus when clicked on
       ptr_direct   (12,6)
        should be used for resizing objects
       ptr_hand     (10,9)
        should be used for dragging objects
       ptr_cross    (8,4)
        should be used for accurate pointing

All these pointers are stored (with hi-res versions as well) inside the
Pointer library itself, so they are always available.

Pointer sprites should be designed in mode 8, maximum size 32x32 pixels. You
should be wary of using logical colour 2 in pointer sprites, as it doesn't
work in high-res mono modes. The pointer can have a palette if you want it
to.

If you are in a hi-res mode then WimpExtension will try to use a sprite of
name "<pointer>22", and then try "<pointer>" if that didn't work. Therefore
you can supply hi-res pointers as well (they should be in mode 19).

The pointer changing is done entirely by the WimpExtension task, so you can
disable null events and pointer changing will still work.

On RISC OS 3 the 'p' command is attempted by the operating system, so
WimpExtension uses the 'wp' command as RISC OS gets the pointer changing
wrong.

There is also a SWI provided so that your program can change the pointer
directly:


WimpExt_SetPointer       &45795
-------------------------------
R0-> sprite name in the Wimp sprite pool, or 0 to reset pointer
If R0>=&8000:
R2 = hotspot X
R3 = hotspot Y

Stores the old pointer palette, and changes the pointer palette and shape to
the sprite specified in R0 (palette optional). The 'hotspot' is defined by
the X and Y coordinates (pixels) in R2 and R3. If R0 is <&8000 then it will
reset the pointer to its original state. You don't need to check if the
pointer is already reset or changed as WimpExtension will do this for you.
Note that the pointer will keep changed until you specifically ask for it to
be reset, or there is a mode change - ie. pointer changes over icons will be
suspended, and the pointer will remain changed outside your window's
workarea.


WimpExt_LimitPointer     &457A2
-------------------------------
R0 = window handle

Limits the mouse pointer to the visible area of the window specified. Note
that if there are draggable objects within this area and these are used then
the mouse rectangle is reset. It is also reset if there is a change of mode,
eg. if the user presses F12 and then Return.


WimpExt_ReleasePointer   &457A3
-------------------------------

Releases the limits on the mouse pointer - ie. sets the mouse rectangle to
be the entire screen.



============================================================================
Library: &03 ColourMenu 1.00
===========================================================================
Dependencies: None

Colour menus are useful if you want the user to be able to select any Wimp
colour for some reason. WimpExtension will automatically create a colour
menu for you, and will work out whether each menu item text should be black
or white.


WimpExt_ColoursMenu      &45797
-------------------------------
R0 = colour to be ticked
R2 = 0 to have just colours, 1 to have extra option
Exit:
R0-> pointer to colour menu

Creates a colour menu (like Edit's 'Background' and 'Foreground' ones),
making the text of each option black or white depending on the brightness of
that colour in the current palette. If the value in R0 on entry is in the
range 0-15 then that colour will be ticked in the menu. The call returns a
pointer to the menu block (in RMA workspace). If the value in R2 on entry is
1 then a 17th option will be added, 'Transparent'. You can change the text of
this by changing the menu block if you want. The 17th option will be ticked
if R0 on entry is 16.



============================================================================
Library: &14 Windows 1.00
============================================================================
Dependencies: None

The Windows library provides many facilities for handling windows.


WimpExt_OpenWindowTop    &4578E
-------------------------------
R0 = window handle

Opens the specified window at the top of the window stack. If the window's
'back' bit is set then it is opened at the bottom instead.


WimpExt_OpenWindowTopC   &46395
-------------------------------
R0 = window handle

Opens the window to the front of the window stack; if the window was not
already open, the window is centred on screen.


WimpExt_CentreWindow     &45799
-------------------------------
R1-> block:
      R1 +  0   visible area minimum x coordinate
      R1 +  4   visible area minimum y coordinate
      R1 +  8   visible area maximum x coordinate
      R1 + 12   visible area maximum y coordinate
      R1 + 28   window flags
Exit:
      Block contains altered coordinates

This call shifts the X coordinates in the supplied block so that the window
described would be centred horizontally on the screen. You can use this call
before Wimp_CreateWindow - eg:
       SYS "WimpExt_CentreWindow",,q%
       SYS "WimpExt_CreateWindow",,q% TO handle%
or you can use it before Wimp_OpenWindow - eg:
       SYS "WimpExt_CentreWindow",,q%+4
       SYS "WimpExt_OpenWindow",,q%
If you are using WimpExt_LoadTemplates then windows can be centred
automatically for you (see description above).


WimpExt_CentreWindowV    &457BE
-------------------------------
R1-> block:
      R1 +  0   visible area minimum x coordinate
      R1 +  4   visible area minimum y coordinate
      R1 +  8   visible area maximum x coordinate
      R1 + 12   visible area maximum y coordinate
      R1 + 28   window flags
Exit:
      Block contains altered coordinates

This call shifts the Y coordinates in the supplied block so that the window
described would be centred vertically on the screen. You can use this call
before Wimp_CreateWindow - eg:
       SYS "WimpExt_CentreWindowV",,q%
       SYS "WimpExt_CreateWindow",,q% TO handle%
or you can use it before Wimp_OpenWindow - eg:
       SYS "WimpExt_CentreWindowV",,q%+4
       SYS "WimpExt_OpenWindow",,q%
If you are using WimpExt_LoadTemplates then windows can be centred
automatically for you (see description above).


WimpExt_CheckWindowOpen  &4579D
-------------------------------
R0 = window handle (or -3 for requester window)
Exit:
R0 = 0 if window closed, 1 if open

Checks to see if the specified window is open or closed.


WimpExt_SetWindowTitle   &4579F
-------------------------------
R2 = window handle
R3-> string

Copies the string in R3 into the window whose handle is in R2. The title
must be indirected. Updates the screen if necessary.


WimpExt_OpenFullSize     &457A4
-------------------------------
R2 = window handle
R3 = window to open behind (-1 = top, -2 = bottom)

Opens the window to maximum size - ie. the same as clicking on the toggle
icon.


WimpExt_SetExtent        &457B5
-------------------------------
R0 = window handle
R1-> block
     R1+00 = new work area minimum x
     R1+04 = new work area minimum y
     R1+08 = new work area maximum x
     R1+12 = new work area maximum y

Sets the work area extent of the specified window, altering the values to be
whole pixels, and reopening the window (if already open) so that the change
is reflected on the screen.


WimpExt_RedirectSprites  &4638D
-------------------------------
R0-> sprite area control block, or +1 for Wimp sprite area
R1-> Wimp_CreateWindow block

Sets the sprite area control block pointer of all the indirected,
sprite-only icons in the CreateWindow block to R0.



============================================================================
Library: &16 Caret 1.00
============================================================================
Dependencies: None

The Caret library provides facilities to help with handling the caret, and
keypresses.


Validation command: wr
----------------------

As it is often needed that RETURN do the same as clicking on the default icon
(the one with border type 2), and also that the up and down arrow keys move
to writeable icons above and below, WimpExtension will handle these keys for
you. Simply include the validation code 'wr' in the writeable icon's
validation string:

  'wr'
    Syntax:
      wr[RETURN icon number],[up icon number],[down icon number]

The icons specified will be used when the user presses RETURN, up arrow (or
shift-tab) and down arrow (or tab) respectively. If the icon specified is a
writeable icon then the caret will be moved to that icon, otherwise
WimpExtension will generate a fake Mouse_Click event for that icon, which
will make it appear to your task as if the user clicked with button status
%100 on the icon (the mouse coordinates given will be those of the caret).

You may leave out any of the numbers in the syntax, if you do so then
WimpExtension will not affect the handling of that key.

WimpExtension can automatically move the caret around for you without the
need for this validation command, see bits 8 and 10 in WimpExt_Initialise.


WimpExt_PutCaretIcon     &4579B
-------------------------------
R2 = window handle
R3 = icon handle

Works out the length of the text icon specified and calls
Wimp_SetCaretPosition to position the caret at the end of the string.


WimpExt_MoveCaretIcon    &46384
-------------------------------
R2 = window handle
R3 = icon handle

Moves the caret into the specified icon, keeping its vertical position as
nearly unchanged as possible. If the caret is currently disowned then it is
placed at the end of the string in the icon.


WimpExt_MoveCaret        &457B6
-------------------------------
R0 = key
R2 = window handle
R3 = icon handle
Exit:
R0 preserved if no action taken, 0 otherwise

Moves the caret from its current writeable icon to the next one above or
below (in number) if the key in R0 is up arrow (or shift-tab) or down arrow
(or tab).

If you set bit 8 of R2 on entry to WimpExt_Initialise then this SWI will be
called automatically for you in WimpExt_Action, and the reason code
translated to a null event if the key is processed.



===========================================================================
Library: &13 Menus 1.00
===========================================================================
Dependencies: None

WimpExtension can do a couple of helpful things with menus. If you use
WimpExt_CreateMenu instead of Wimp_CreateMenu and you set bit 1 in R2 when
you call WimpExt_Initialise then WimpExtension will automatically recreate
menus when the user clicks Adjust.


WimpExt_OpenDialogue     &4579C
-------------------------------
R2 = window handle
R3 = X Offset
R4 = Y Offset

Opens the specified window using Wimp_CreateMenu at the pointer position,
offset by R3 and R4. The coordinates used are PointerX-R3,PointerY+R4.


WimpExt_CreateMenu       &457AC
-------------------------------
R1 = pointer to menu structure, or window handle, or -1 to close menus
R2 = menu X
R3 = menu Y

Exactly the same as Wimp_CreateMenu, except that the parameters are stored so
that, after you have processed the selection, if the user clicked ADJUST you
can call WimpExt_ReCreateMenu (see below) to reopen the menu, or this can be
done for you by setting bit 1 in R2 passed to WimpExt_Initialise.


WimpExt_ReCreateMenu     &457AD
-------------------------------

Reopens the last menu opened with WimpExt_CreateMenu. Generates an error if
the last operation was to close a menu, or if you have not called
WimpExt_CreateMenu yet.


WimpExt_ShadeEntry       &457AE
-------------------------------
R1-> menu structure
R2 = number of option to shade/unshade (0...nn)
R3 = 0 to unshade, any other to shade
If bit 6 of R2 was set in WimpExt_Initialise:
R3 = 0 to unshade entry, 1 to shade icon, 2 to toggle shade flag
Exit:
R0 = old state of menu entry (0 for unshaded, 1 for shaded)

Shades or unshades the specified menu entry. If bit 6 of R2 was set in
WimpExt_Initialise then the alternative parameters are used as shown.


WimpExt_TickEntry        &457AF
-------------------------------
R1-> menu structure
R2 = number of option to tick/untick (0...nn)
R3 = 0 to untick, any other to tick
If bit 6 of R2 was set in WimpExt_Initialise:
R3 = 0 to untick entry, 1 to tick entry, 2 to toggle tick flag
Exit:
R0 = old state of menu entry (0 for unticked, 1 for ticked)

Ticks or unticks the specified menu entry. If bit 6 of R2 was set in
WimpExt_Initialise then the alternative parameters are used as shown.


WimpExt_MenuWidth        &46382
-------------------------------
R1-> menu structure

This SWI scans through the specified menu, altering its width and the widths
of all its submenus, so that all the menus are the minimum width possible
while still displaying the text correctly (and neatly).

Note that under RISC OS 3.5 the Wimp ignores the menu width and calculates
it itself.



============================================================================
Library: &04 Requester 1.00
============================================================================
Dependencies: &0F LoadRAMTemplate, &12 Icons, &14 Windows, &15 Pointer,
              &18 3DIcons

A requester window has a title message, a text string, and up to four
buttons. It can be used as a general-purpose way of asking the user for some
response which must be answered before anything else happens - like the
Wimp's Wimp_ReportError window, but a lot nicer and more flexible. An
advantage of the requester windows is that you can specify the text of the
buttons, what Escape and Return do, and the computer still multitasks while
the requester is open. (If you want a non-multitasking requester, see
'Immediate windows'.)


WimpExt_OpenRequester    &457A6
-------------------------------
R2-> title (eg. 'Message from MyTask')
R3-> text (eg. 'Document not saved. Save?')
R4-> block containing button definitons
       text for default button    (eg. 'Save')
       text for button 1          (eg. 'Discard')
       text for button 2          (eg. 'Cancel')
       text for button 3          (eg. '')
R5 = flags:
      0-2 button to be used if 'Escape' is pressed (0-3)
      3-6 reserved; MUST BE 0
      7    won't produce a beep even if WimpFlags bit 4 is clear
     8-31 reserved; MUST BE 0

Opens a requester box with a title, a message and some buttons along the
right-hand edge. The pointer is constrained to the requester window. The
buttons may contain any text up to 8 characters. You can have up to 4
buttons. They are filled with the text specified from the bottom one (the
default) upwards. If the text for a button is a null string then that button
will not be created.

If the user presses Return then the default button is pressed. If the user
presses Escape then the button specified in R5 is pressed. Mouse_Click
events to the requester window will be passed from WimpExt_Action filtered
so that only Select and Adjust are passed through, the window handle is -3,
and the icon handle will be 0-3. You can check whether the requester window
is open by using WimpExt_CheckWindowOpen.


WimpExt_CloseRequester   &457A7
-------------------------------

Closes the requester window and releases the mouse pointer. This is done
automatically if the user selects a button in the requester box, or presses
Escape or Return. If the window wasn't open then no error is generated.



===========================================================================
Library: &09 Help 1.00
===========================================================================
Dependencies: None

WimpExtension provides a couple of SWIs and a validation command to make
providing multitasking help easier.


Validation command: wh
----------------------

    'wh' (help)
      Syntax:
        wh<message>

When the pointer is over the icon, Acorn's Help application would display
the message specified.

If you set bit 5 of R2 when you called WimpExt_Initialise, specifying
'semi-automatic' help then, instead of sending the message to Help for you,
WimpExtension will instead give YOU a message, &45783, giving you the
suggested help string. This feature was suggested by Peter Greenham, so that
help strings can be converted via MsgTrans. The message format is as
follows:
    R1+16  &45783
    R1+20  mouse X
    R1+24  mouse Y
    R1+28  button state
    R1+32  window handle (-1 for background, -2 for icon bar,
           -3 for requester window)
    R1+36  icon handle
    R1+40  suggested text

You may notice that this is the same as message &502, with the message number
changed and the suggested text tagged on the end. To send this on unchanged,
you would use:
    SYS "WimpExt_SendHelp",q%+40,q%


WimpExt_SendHelp         &457AA
-------------------------------
R0-> message text
R1-> message block containing message of type &502 or &45783

Sends a reply to message type &502, with the specified text. The message
will appear in Help's Interactive Help Window.


WimpExt_SendWimpHelp     &457AB
-------------------------------
R2-> keyword
R3-> filename

Sends a message to WimpHelp, telling it to open a hypertext help window from
a file as specified in R3, with the keyword as specified in R2.  WimpHelp
was never released as a public domain hypertext help system, so you
shouldn't use this SWI.



============================================================================
Library: &0D SpriteOp 1.00
============================================================================
Dependencies: None

WimpExtension can help you with plotting sprites (including 256-colour
ones).


WimpExt_SpriteOp         &46386
-------------------------------
R0 = reason code
     +256 for user sprite area, R2 points to sprite name
     +512 for user sprite area, R2 points to sprite
unless otherwise specified:
R1 = sprite control block pointer (or +1 for Wimp sprite pool)
R2 = sprite pointer
other registers as appropriate for reason code

This SWI performs various operations on sprites, including displaying them
onto the screen (or printer). Note that these calls need ColourTrans if you
are using them with 256-colour sprites. Sprites in the system sprite area
are not supported.

R0 = 0 : Display sprite
-----------------------
R3 = x coordinate (OS units)
R4 = y coordinate (OS units)
R5 = plot action

Plots the specified sprite on the screen. This call is mode-independent, so
if necessary the sprite is changed size and/or the colours are chosen
appropriately.

R0 = 1 : Get palette
--------------------
Exit:
R3-> sprite's palette, or 0 if it doesn't have one
R4 = number of entries in palette

Locates the specified sprite's palette.

R0 = 2 : Make pixel translation table
-------------------------------------
R3-> block to contain table (1 byte per colour)
Exit:
     block contains pixel translation data

Calculates a pixel translation table for displaying the specified sprite in
the current mode. If the sprite has no palette then the desktop's colours
are used.

R0 = 3 : Make scaling table
---------------------------
R3-> 16-byte block to contain table
Exit:
     block contains scaling table

Calculates a scaling table for displaying the specified sprite at normal
size in the current mode.

R0 = 4 : Display sprite scaled
------------------------------
R3 = x coordinate (OS units)
R4 = y coordinate (OS units)
R5 = plot action
R6-> sprite scaling table:
     R6 + 00  x multiplier
     R6 + 04  y multiplier
     R6 + 08  x divisor
     R6 + 12  y divisor

Plots the specified sprite on the screen, scaled according to the table.
This call is mode-independent, so if necessary the sprite is changed size
and/or the colours are chosen appropriately. The sprite is first scaled to
be the correct size in the current mode, then the specified scaling table is
used.

R0 = 5 : Copy sprite
--------------------
R3-> destination sprite area (or +1 for Wimp sprite pool)

Copies the specified sprite into the destination sprite area. Gives an error
if there isn't enough room. Note that sprites with duplicate names will NOT
be overwritten; you will end up with two sprites with the same name (use
WimpExt_SpriteOp 7 to remove duplicate names).

R0 = 6 : Copy sprite area
-------------------------
R1 = source sprite control block pointer (or +1 for Wimp RMA sprite pool,
     or +2 for Wimp ROM sprite pool)
R2 = target sprite control block pointer (or +1 for Wimp sprite pool)

Copies ALL the sprites from the source sprite area to the target sprite
area. Gives an error if there isn't enough room. Note that sprites with
duplicate names will NOT be overwritten; you will end up with two sprites
with the same name.

R0 = 7 : Remove duplicate names
-------------------------------
R1 = sprite control block pointer (or +1 for Wimp sprite pool)

Checks for sprites with duplicate names. If any exist, all copies except the
LAST one will be deleted.

R0 = 8 : Copy sprite area sprite by sprite
------------------------------------------
R1 = source sprite control block pointer (or +1 for Wimp RMA sprite pool,
     or +2 for Wimp ROM sprite pool)
R2 = target sprite control block pointer (or +1 for Wimp sprite pool)

Copies ALL the sprites from the source sprite area to the target sprite
area. Gives an error if there isn't enough room. The sprites will be copied
one by one, with duplicate sprite names removed before each copy. This means
that this call, while being slower than 'Copy sprite area' followed by
'Remove duplicate names', often requires less free memory in the target
sprite area.

R0 = 9 : Check if sprite needs to be transformed
------------------------------------------------
R3 = mode to check for, or -1 for current mode
Exit:
R0 = bit   meaning if set
     0     a pixel translation table would be needed
     1     a scaling table would be needed
     2-31  undefined; will be 0 if the sprite doesn't need transforming

Checks whether the specified sprite needs to be scaled or needs a pixel
translation table to be plotted correctly in the specified mode. If either
of these things are required, other WimpExt_SpriteOp calls exist to
calculate them for you.

R0 = 10 : Global replace
------------------------
R3 = search colour
R4 = replace colour

Replaces all pixels of colour R3 with pixels of colour R4. This routine
isn't very fast, but it works. Currently it won't work with 256-colour
sprites.



============================================================================
Library: &0C DrawOp 1.00
============================================================================

WimpExtension provides several operations on Draw files, including
displaying them on the screen (or printer).


WimpExt_DrawOp           &46385
-------------------------------
R0 = reason code
other registers as appropriate for reason code

R0 = 0 : Render draw file
-------------------------
R1-> scaling and position table:
       R1+00 = amount to multiply X by * 65536
       R1+04 = 0
       R1+08 = 0
       R1+12 = amount to multiply Y by * 65536
       R1+16 = X origin (OS units)
       R1+20 = Y origin (OS units)
R2-> first object (ie. beginning of Draw file+40)
R3-> end of last object (ie. end of file)
R4-> graphics clip box, or 0 for no clipping:
       R4+00 = XMin
       R4+04 = YMin
       R4+08 = XMax
       R4+12 = YMax
Exit:
F0-F2 corrupted if scaling is not 1:1

This call displays a draw file. Objects will be checked one by one to see if
they are in the clipping area, and redrawn if they are. Currently the
following objects are supported:
      0 - font table
      1 - text
      2 - path
      5 - sprite
      6 - group
      7 - tag
This is all the objects specified in the RISC OS 2 PRMs, except for text
AREA objects, which are hardly ever used and are very very complicated.
Magnifying a draw file by more than about 8 times is probably not a good
idea because rounding errors in the Draw module will start to become
significant.

Note that this call requires the ColourTrans module. It also requires the
FPEmulator module, if and only if the scaling is not 1:1. This call replaces
the old SWI WimpExt_RedrawDraw, which should now not be used. (This call is
much better anyway.)

R0 = 1 : Calculate bounding box
-------------------------------
R2-> first object
R3-> end of last object
Exit:
R4 = XMin (Draw units)
R5 = YMin (Draw units)
R6 = XMax (Draw units)
R7 = YMax (Draw units)

Calculates the bounding box of the specified objects. The coordinates are
returned in Draw units (which are OS Units * 256). Grouped objects are not
checked individually - the group's bounding box is used. Unknown object
types will not be checked. (This call 'knows' all the types described in the
RISC OS 2 PRMs.) If no objects with bounding boxes are in the set specified
then R4-R7 on exit are undefined.

R0 = 2 : Register unknown object handler
----------------------------------------
R2-> routine (or 0 for no unknown object handler)
R3 = workspace pointer

This routine will be called if the Render Draw File code encounters an
unknown object. The routine has the following entry and exit conditions:
Entry: (SVC mode)
  R2 -> object
  R4 -> scaling and position table
  R6  = clipping rectangle XMin (pretransformed)
  R7  = clipping rectangle YMin (pretransformed)
  R8  = clipping rectangle XMax (pretransformed)
  R9  = clipping rectangle YMax (pretransformed)
  R12 = your workspace pointer
  R13-> supervisor stack (at least 256 bytes guaranteed)
  R14 = return address
Exit:
  R1-R11,R13 preserved
  V flag set on error, with R0 pointing to standard error block



============================================================================
Library: &05 FontMenu 1.00
============================================================================
Dependencies: None

Font menus have tended to be huge and impossible to use, with every single
variety of every single font listed all in one menu. WimpExtension will
automatically create a hierarchial font menu for you, with all the fonts
listed by family.


WimpExt_GetFontMenu      &457B7
-------------------------------
R0 = 0 to unshade 'System font' entry, 1 to shade it
R1-> menu title (12 chars max), or 0 for default title ('Font')
Exit:
R1-> pointer to menu structure

Reads in the list of fonts currently available and creates a hierarchial
menu structure with all the fonts listed by family. 'System font' is also on
the root menu. This menu structure is guaranteed to remain in the same place
for as long as your task is active. The font list MAY be read in the first
time you call WimpExt_GetFontMenu, or it may have been read in earlier.


WimpExt_DecodeFontMenu   &457B8
-------------------------------
R0-> buffer for font name
R1-> Wimp_Poll block, reason code Menu_Selection

The font menu is decoded and the correct font name is placed in the buffer.
If the user selects, for example, 'Trinity' of 'Trinity.xxx','Trinity.yyy'
the submenus will be followed through, and the font name at the top of each
menu used.



============================================================================
Library: &06 ControlImmediate 1.00
============================================================================
Dependencies: &04 Requester

Immediate windows do not multitask. They can be for reporting the progress
of a non-multitasking operation, or for getting an immediate response from
the user.


WimpExt_ControlImmediate &457B9
-------------------------------
R1 = 0 or -1   : close immediate window
   = 1         : check for mouse click in immediate window
   = 2         : open immediate requester and wait for mouse click
   = 3         : redraw icon - icon handle in R0
   = 4         : slab icon - icon handle in R0 (-1 to use currently slabbed
                 icon), R2 = 1 to slab in, 0 to slab out
   = 5         : limit pointer to immediate window
   = 6         : redraw icon's 3D border - icon handle in R0
   = 7         : redraw icon:
                 R0 = pointer to icon block
                 R2 = 'Work area' X origin
                 R3 = 'Work area' Y origin
   = 8         : open immediate window using handle in R0
  >= &8000     : open immediate window using data pointed to by R1
If R1 = 2 then rest of registers as for WimpExt_OpenRequester
If R1 = 8 then R0 = window handle
Exit:
If R1 = 1 or 2 : R0 = Icon handle of icon clicked on, or -1 for none

This SWI is for using windows like the Wimp_ReportError window that are not
multi-tasking. You can only have one 'immediate window' open at a time, it
is always on top of the window pile, and you MUST NOT call 'Wimp_Poll' while
the immediate window is open.

If R1 is 0 or -1 on entry, the immediate window is closed. If it was not
open then no error is generated.

If R1 is 1 on entry, then the program will check for mouse clicks on icons
in the window. 3D icons will be slabbed automatically. -1 is returned if no
icon was clicked on.

If R1 is 2 on entry, the rest of the registers are as for
WimpExt_OpenRequester. It opens an 'immediate requester' and waits for a
mouse click on one of the action buttons, or ESCAPE or RETURN. The icon
clicked on is returned in R0.

If R1 is 3 on entry, the icon in the immediate window whose handle is in R0
will be redrawn (presumably because you have changed the indirected data).
The 3D border is not redrawn.

If R1 is 4 on entry, the icon whose handle is in R0 will be slabbed in or
out depending on R2 - similar to WimpExt_SlabIcon for normal icons. If the
specified icon handle is -1 and R2 is 0 then the currently slabbed icon (if
any) is used.

If R1 is 5, the mouse rectangle is redefined to be the size of the immediate
window - similar to WimpExt_LimitPointer for normal windows. Use
WimpExt_ReleasePointer to release the pointer again afterwards.

If R1 is 6, the specified icon's 3D border is redrawn.

If R1 is 7, the specified icon is drawn. This call does not work if you have
an immediate window open at the same time.

If R1 is 8 then the window corresponding to the window handle passed in R0
will be forcefully created on the screen NOW rather than at the next
available moment the Wimp has.

If R1 is greater than or equal to &8000 on entry, then an immediate window
is created from the Wimp_CreateWindow block pointed to by R1.

If you call WimpExt_PrePoll while an immediate window is open then it will
be closed automatically - the Wimp does not know about immediate windows and
the screen display would become corrupted if you kept an immediate window
open over a call to Wimp_PollIdle.


============================================================================
Library: &07 HeapManager 1.00
============================================================================
Dependencies: &01 Misc

NB  This file contains a complete, but fairly complicated, description of
--  the heap manager. The documentation file '03-Heap' contains a much
    better and more clearly explained overview.

One of the biggest problems in writing multitasking programs (or single-
tasking ones for that matter) is memory management. For any program which
has more than one memory array which may change size during use it can get
very complicated. For this reason, WimpExtension provides a complete heap
manager. You call the initialise routine at the beginning of your program,
and from then on whenever you need some memory simply ask for it, and return
it when you don't need it any more. WimpExtension will automatically tidy
the heap, and reduce and enlarge the WimpSlot where necessary/possible.

The heap management system takes control of all your task's memory above the
start of the heap (specified when you call the initialise routine). You
should NOT change your task's WimpSlot when using the heap management
routine (ie. don't call Wimp_SlotSize with R0<>-1).

So that the memory blocks can be moved about by the tidy routine, you are
not given the address of the block, but the address of its 'anchor'. This is
a single word which points to the block. The tidy routine can then move the
block about and then update the anchor so you still know where it is. Note
that blocks will not mysteriously move on their own, they will only move on
calls to WimpExt_Heap, and then only for reason codes 5, 6, 11 and 12.
(See below.)

You specify the number of anchors to create when calling WimpExt_Heap's
initialise routine. More anchors can be created later using the increase
anchors routine, but this is quite slow. If you use the 'allocate with
extend' routine for allocating blocks then the increase anchors routine will
be called for you automatically when necessary. You cannot decrease the
number of anchors. If you specify 0 anchors in the initialise entry then a
default value of 256 is used - this is loads and should be more than
sufficient for most needs.

Note that the size of all memory blocks is a multiple of 8 plus 4 (ie.
size = 8N+4). The size will be rounded up on calls to the allocate routine.
The size of the block is stored 4 bytes before the start of the block. All
blocks are guaranteed word aligned.

When calling WimpExt_Heap routines, you can either refer to a block by a
pointer to it, or by a pointer to its anchor. I will refer to this as a
'block pointer'.

The tidy routine can be automatically called once a second in
WimpExt_PrePoll if you set bit 3 of R2 when you call WimpExt_Initialise.
Remember not to mask out null events, though - it's probably best to use
Wimp_PollIdle.

The routines are fairly robust, and will usually produce the error 'Heap
corrupt' or 'Bad heap operation' rather than an address exception or
corrupting memory if something goes wrong. Both of these should probably be
treated as fatal errors, but you can do with them what you like.

Note that when there are no blocks allocated in the heap, it takes no memory
at all - even the list of anchors is destroyed. This means that if you are a
module task with a heap at &8000 then you won't be unnecessarily using 16k
(or whatever page size the computer is using) all the time.

The following information on the 'heap pointer' system is NOT needed for
most users, generally you will just initialise the heap at &8xxx, claim a
block etc. and that's it.

The calls all act on the currently selected heap. Use the call R0=14 to
select different heaps. Heaps are specified through a 'heap pointer', which
is set out as follows:
  +00  hp_heap       offset of heap data area
  +04  hp_free       offset of first free block, or 0 if no free blocks
  +08  hp_anchors    offset of first anchor
  +0C  hp_heapsize   total size of heap in bytes
  +10  hp_heapfix    'fixed' counter
  +14  hp_tidytime   monotonic time of last Tidy call
  +18  hp_heaptidy   tidy flag; 0 if heap is fully tidied, non-0 otherwise
  +1C  hp_created    created flag; 0 if heap is uncreated, non-0 otherwise
  +20  hp_base       pointer to base of heap memory
  +24  hp_pagesize   'page' size
  +28  hp_setsize    pointer to routine to change size of heap, entered in
                     SVC mode:
                       R0  = size required
                       R10 = heap pointer
                       R13 = supervisor stack
                       R14 = return address
                      exit:
                       R0  = 0 indicates failure, non-zero indicates success
                       all other registers preserved
  +2C  hp_numblocks  number of blocks claimed
  +30  hp_rootptr    pointer to pointer to base of heap memory
  +34  hp_misc       depends on what sort of heap this is


WimpExt_Heap             &457BA
-------------------------------
R0 = reason code
other registers as appropriate for reason code

R0 = 0 - Initialise standard heap:
----------------------------------
R1-> base of heap
R2 = number of anchors to allocate

Initialises the standard heap. R1 points to the base of the heap - it will
grow upwards from here. R2 specifies the numbers of anchors to allocate
initially. Each anchor takes 8 bytes. Note that R1 is rounded up to the
nearest multiple of 8 plus 4 (ie. 8N+4). The heap is automatically selected
as the current heap.

R0 = 1 - Describe heap:
-----------------------
Exit:
R0 = currently selected heap pointer, or +1 for standard heap
R2 = largest available block size
R3 = total free
R4 = memory used by heap
R5 = number of anchors allocated
R6 = number of anchors in use

Adds up all the sizes of the free blocks, and returns information about
memory used by the heap. If the heap is empty then R2-R6 will be zero.

R0 = 2 - Allocate block:
------------------------
R2 = size of block required
Exit:
R1-> anchor or zero if allocation failed

Tries to find a block of the required size. Increases the WimpSlot if
necessary. If a call to Wimp_SlotSize fails then zero will be returned. Note
that the size is rounded up to the next multiple of 8 plus 4.

To get a pointer to the actual block just load the word indirected by the
anchor, ie block=!anchor.

R0 = 3 - Free block:
--------------------
R1 = block pointer

Frees the memory used by the specified block.

R0 = 4 - Reallocate block:
--------------------------
R1 = block pointer
R2 = new size required
Exit:
R1-> anchor (the same anchor as before) or 0 if reallocate failed

Tries to resize the specified block. You should check R1 on exit to see if
the resize was successful (only on increasing the size, decreasing the size
will always be successful).

R0 = 5 - Tidy heap:
-------------------

Tries to tidy the heap, reducing the WimpSlot if possible. This can be
automatically performed once a second (in WimpExt_PrePoll) if you set bit 3
of R2 when you called WimpExt_Initialise. Note that this routine does not
tidy the heap fully, it just does a little bit each time it is called. This
is to keep the time cost down.

R0 = 6 - Compact heap:
----------------------

Repeatedly calls Tidy Heap, until the heap is as small as it can get.

R0 = 7 - Find anchor:
---------------------
R1 = block pointer
Exit:
R1-> anchor

Given a block pointer, returns a pointer to that block's anchor.

R0 = 8 - Fix blocks:
--------------------

Fixes the heap. Subsequent calls to the Tidy or Compact routines will have
no effect. Effectively, the heap becomes a non-relocatable heap like the
RMA. This call is provided so that if you temporarily need to rely on the
blocks not moving, you can easily do so. WimpExtension keeps a counter of
the number of times you call this routine, so that if you, for example, fix
the blocks twice in a row then you need to unfix them twice in a row before
they are actually unfixed.

R0 = 9 - Unfix blocks regardless of counter:
--------------------------------------------

Unfixes the heap, so that garbage disposal routines will work again. This
call zeroes the counter straight away - ie. the blocks are immediately
unfixed no matter how many times you called the fix routine.

R0 = 10 - Unfix blocks:
-----------------------

Unfixes the heap, so that garbage disposal routines will work again. This
routine decrements the fix counter, and only actually unfixes the blocks if
the counter reaches zero.

R0 = 11 - Increase anchors:
---------------------------
R2 = number of anchors to add
Exit:
R1 = 0 indicates failure, non-zero indicates success

Increases the number of anchors. This routine is quite slow as it often has
to move the entire heap up in memory so you should use this routine
sparingly, if you need to use it at all. Note that this SWI causes blocks to
be relocated.

R0 = 12 - Allocate with anchor extend:
--------------------------------------
R2 = size of block required
Exit:
R1-> anchor or zero if allocation failed

Tries to find a block of the required size. Increases the WimpSlot if
necessary. If a call to Wimp_SlotSize fails then zero will be returned. Note
that the size is rounded up to the next multiple of 8 plus 4. If no free
anchors are available then the increase anchors call is used to make some
more; therefore using this SWI can cause blocks to be relocated. It is,
however, the recommended call to use for allocating blocks as it isn't
limited by the number of anchors already created.

R0 = 13 - Free all blocks
-------------------------

Frees all blocks in the currently selected heap belonging to your task.

R0 = 14 - Select heap
---------------------
R1 = heap pointer, or +1 for standard heap, or -1 for no change
Exit:
R0 = previous heap pointer, or 0 if no previously selected heap
R1 = current heap pointer, or 0 if no currently selected heap

Selects a new heap to be used by the other WimpExt_Heap calls.

R0 = 15 - Relocate heap
-----------------------

Compares the heap addresses specified by hp_base and hp_rootptr. If they are
different, then hp_base is updated by hp_rootptr, and the anchors are
recalculated to account for the change of address.

R0 = 16 - Create a heap in a heap block
---------------------------------------
R1 = heap pointer (blank, it will be filled in by this call)
R2 = number of anchors to create
Exit:
R1 = heap pointer, or 0 if the call failed due to lack of memory

This call creates a new heap inside a heap block in the currently selected
heap. The new heap is NOT selected as the current heap.



============================================================================
Library: &08 DataTrans 1.00
============================================================================
Dependencies: &01 Misc

WimpExtension can handle saving files if your file is in a contiguous area
of memory (ie. not split up in several chunks all over the place). You just
call WimpExt_DataSave when you receive the User_Drag_Box event from the user
dropping the icon in a filer window or onto another task. When the transfer
is complete (successful or otherwise) you will be sent a message, &45782,
telling you that the transfer is complete, and whether everything went OK.
The SWI supports the full data transfer protocol, including the Wimp$Scrap
method and RAM transfer.

WimpExtension can also handle loading of files. Files can either be loaded
into a WimpExt_Heap block (the preferred method) or they can be loaded into
a fixed-size area of memory. Use is similar to WimpExt_DataSave - you just
pass the DataSave or DataLoad message to WimpExt_DataLoad, and wait for a
message telling you the transfer is complete.


WimpExt_DataSave         &457BC
-------------------------------
R0 = file length
R1-> filename (pathname or leafname)
R2 = file type
R3 = pointer to data or offset into heap block
R4 = flags:
      0   if set, do not allow files to be saved to your own task
      1   if set, save from heap block otherwise save from fixed block
      2   if set, do not produce an error if receiving task cannot load files
     3-31 reserved; MUST BE 0
R5 = pointer to Wimp_GetPointerInfo block if >=&8000, otherwise file will be
     saved to current mouse position
R6-> anchor if bit 1 is set in R4
Exit:
R0 = 0 if failed due to attempt to save to own task, non-zero otherwise

Used to save a file from your program to a filer or to another task. When
you receive the User_Drag_Box event after the user has dragged the icon to
where they want it put, call WimpExt_DataSave to handle the data transfer.
R5 allows you to use this call to save to a specified place - just use R5=0
if you want to save to the pointer position. If R4 is non-zero on entry,
then if the user has dragged the file to a window or icon belonging to your
task then no action will be taken, and R0 will be zero on exit. Otherwise,
when the transfer has finished, WimpExtension will send you a message,
number &45782, with the word at R1+20 having the following meaning:
        0 = file not saved. Error block at R1+24
        1 = file saved but is 'unsafe' (eg. saved to another task)
        2 = file saved. Filename at R1+24
        3 = file not saved, receiver could not accept file (if bit 2 set)


WimpExt_DataLoad         &46383
-------------------------------
R0 = 0 : Load into heap block
  R1-> DataSave or DataLoad message block
  R2 = block pointer of block to receive file, or 0 to create new block
  R3 = offset in block to place file
R0 = 1 : Load into fixed block
  R1-> DataSave or DataLoad message block
  R2-> block to receive file
  R3 = length of block

Use this SWI to load files from the filer or other applications. If R0=0
then the file is loaded into a WimpExt_Heap block, and can be any length,
memory permitting. If R0=1 then the file is loaded into a fixed area of
memory, and will not be loaded if it exceeds the length of the area. When
you receive the DataSave or DataLoad message, pass the block onto
WimpExt_DataLoad, and the transfer will be handled automatically. As long as
this SWI doesn't return an error, when the transfer has finished,
WimpExtension will send you a message, number &45784, with the word at R1+20
having the following meaning:
        0 = file not loaded. Error block at R1+28
        1 = file transferred successfully from another task
        2 = file loaded successfully from disc
A pointer to the block's anchor is at R1+24, if it was loaded into a heap
block. Otherwise a pointer to the area is at R1+24. If R1+20<>0 then the
rest of the block contains:
    R1+28 = length of file
    R1+32 = load address of file
    R1+36 = exec address of file
    R1+40 = filename (leafname if transferred from task)
Obviously you need to have initialised a heap to use this SWI. Note that
WimpExtension won't free the block if there's an error; your error handler
must do this if appropriate. The load and exec addresses don't indicate the
date if the file was transferred from another task (the relevant bits will
all be zero).



============================================================================
Library: &0A Sort 1.00
============================================================================
Dependencies: &0B MemMove

WimpExt_Sort             &46380
-------------------------------
R0 = number of objects to sort
R1-> array of objects
R2-> comparison routine
R3 = workspace pointer for comparison procedure
R4 = size of object
R5-> temporary workspace of R4 bytes (only needed if R4>63)

This SWI will sort an array of objects. It is very similar to the
OS_HeapSort SWI, except that you can use it to sort an array of ANY object,
rather than just arrays of pointers. R2 points to a routine which is
entered, in SVC mode, as follows:
  R0 -> object a
  R1 -> object b
  R12 = value supplied to WimpExt_Sort in R3
  R13-> supervisor stack
  R14 = return address
The routine should compare the two objects and return, preserving all
registers apart from R0,R1,R12 and R14, with flags set as follows:
  a<b   Z=0, C=0
  a=b   Z=1, C=1
  a>b   Z=0, C=1
The actual method of sorting is unspecified; suffice it to say it's fast...
(Currently it's a heap sort.) Although R5 doesn't have to be word-aligned,
the sort will probably be faster if it is.



============================================================================
Library: &0B MemMove 1.00
============================================================================
Dependencies: None

WimpExt_MemMove          &46381
-------------------------------
R0-> from
R1-> to
R2 = size in bytes

Copies R2 bytes from R0 to R1. R0 and R1 need not be word-aligned, and R2
need not be a multiple of 4. This SWI uses the optimised memory copying
routine given in the RISC OS 2 PRMs. It does not cope with overlap (which
is why it's separate from WimpExt_MemCopy).



============================================================================
OS commands
============================================================================

WimpExt Colours (3DIcons, &18)
---------------

*WimpExt Colours is used to specify the default colours for 3D borders. The
syntax is:

  *WimpExt Colours <top-left> <bottom-right> <sync-in> <async-in> <channel>

The default colours used are 0 4 14 2 12.

This command is NOT to be used by your programs; it is provided so that the
user can decide what colour scheme THEY prefer.

This command can also be used if you don't like 3D borders; if you try

  *WimpExt Colours 7 7 3 3 1
  
you will find that all the borders are now completely flat. (And it doesn't
look too bad, either.)

The Colours command really is only to be used by the user, not by any
programs. It'll probably be removed in a later version of WimpExtenion, when
I put in the 'Style manager', which'll do all that WimpExt Colours does and
a lot lot more (TM). :-)


WimpExt Desktop (Kernel)
---------------

*WimpExt Desktop is for internal use only.


WimpExt LibAvailable (Kernel)
--------------------

*WimpExt LibAvailable lists all the available WimpExtension libraries on
disc, categorised by file.


WimpExt LibClear (Kernel)
----------------

*WimpExt LibClear unloads all WimpExtension libraries from memory.


WimpExt LibFile (Kernel)
---------------

*WimpExt LibFile <full pathname> adds a file to the list of known
WimpExtension library files.


WimpExt LibInfo (Kernel)
---------------

*WimpExt LibInfo <hexnumber> displays information about the specified
library, which must be currently loaded.


WimpExt LibKill (Kernel)
---------------

*WimpExt LibKill <hexnumber> removes the specified WimpExtension library
from memory.


WimpExt LibLoad (Kernel)
---------------

*WimpExt LibLoad <hexnumber> loads the specified WimpExtension library.


WimpExt LibLoaded (Kernel)
-----------------

*WimpExt LibLoaded lists all the loaded WimpExtension libraries.


WimpExt LibLoadOld (Kernel)
------------------

*WimpExt LibLoadOld loads in all the libraries that could possibly be used
by an old-style WimpExtension task.


WimpExt LibLose (Kernel)
---------------

*WimpExt LibLose <full pathname> removes a file from the list of known
WimpExtension library files.


WimpExt LibModified (Kernel)
-------------------

*WimpExt LibModified <filename> informs WimpExtension that the specified
library file has changed.


WimpExt LoseTasks (Kernel)
-----------------

*WimpExt LoseTasks forces WimpExtension to forget about any tasks registered
with it. This is provided for emergencies only.


WimpExt StartTask (Kernel)
-----------------

*WimpExt StartTask starts up a Wimp task, returning immediately. Useful for
obey files, etc.


X (Kernel)
-

WimpExtension provides the OS-command 'X'. This is used to execute other OS
commands, but any errors produced by that command will be ignored. This can
be useful in obey files. eg:

  *X Delete <Obey$Dir>.Backup
  *X Rename <Obey$Dir>.Data <Obey$Dir>.Backup

or

  *X Run <Obey$Dir>.Title
  


============================================================================
Upgrading your program from WimpExtension I to II
============================================================================

Modifications you must remember when converting from WimpExtension to
WimpExtension II which might require slight alterations to existing code:

WimpExt_DataSave       - R5 is now a pointer to a Wimp_GetPointerInfo block,
                         or 0 to use in the same manner as before.
                         R4 now contains flags in bits 0 to 2, and is no
                         longer a 0 or non-0 register - this is mainly to
                         allow saving from a heap block.
WimpExt_LoadTemplates  - On exit R2 is now updated to contain the first free
                         byte in the indirected area.
WimpExt_LinkWindows    - Bits 5-8 must be used, %0101 would give the normal
                         WimpExtension I effect, and R7 should contain the
                         Y value instead of R6.
WimpExt_SubstituteArgs - Any registers between 0 and &8000 will no longer be
                         faulted, they will be converted to a number, so to
                         fault a string's use you must set the register to
                         -1, not zero as before.

Also remember to include the WimpExt_LibraryOp calls to register the
task's library file, and to load all the required libraries.



============================================================================
Things possibly to be included in a later version...
============================================================================

   * Resizeable RamFS
   * List handling
   * Better font menus
   * More draw-file stuff (including creating draw-files)

Plus anything else useful anybody comes up with...



============================================================================
Finally
============================================================================

Any and all correspondance to:

                DoggySoft
                Furzefield House
                Furzefield Road
                Beaconsfield
                Bucks.
                HP9 1PQ

or to user 'Jp' on Arcade BBS, or by email to wxii@doggysft.demon.co.uk.
