Dream 52/Amiga_Dream_52.iso/RiscOS/APP/DEVS/LIB/WIMPEX.ZIP/WimpExt/Manual

Text File | 1993-08-16 | 87KB | 2,347 lines

                      ________________________________

                      WimpExtension 2.18 (16-Aug-1993)
                      ________________________________


                     (c) Jon Ribbens of DoggySoft, 1993


Licence
=======


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

There is no warranty at all, express or implied or whatever. If anything goes
wrong, don't blame me. I will, however, try to fix any problems you find.


NB  If you find any bugs in WimpExtension, or you think I should include some
--  extra feature, don't just sit there muttering to yourself, TELL me about
    it.



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 a year, 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, etc.,
etc.

This manual explains all the features of WimpExtension, and how to use them.
For a quick overview of the SWI calls read the file 'SWIs'.

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.



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



Essential SWIs
==============

These are SWIs you MUST call if you are going to use ANY of the features of
WimpExtension.


WimpExt_Initialise       &45780
-------------------------------
R0 = 16
R1 = task handle
R2 = features flags
       bit     meaning
       0       semi-automatic slabbing if set, automatic otherwise
       1       automatically recreate menus if set
       2       task wants to use font menus if set
       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      Don't allow TAB for moving between writeable icons
       12-31   reserved; MUST BE 0
Exit:
R0 = WimpExt version number * 100
R2 = pointer to WimpExt's sprite pool

Must be called prior to using any other WimpExt calls. R0 must be 11 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. If bit 1 of R2 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 2 of R2 is set then
you are allowed to call WimpExt_GetFontMenu and WimpExt_DecodeFontMenu - you
are NOT allowed to call them if you do not set bit 2. If bit 4 of R2 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.


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

Must be called prior to the task exiting.


WimpExt_PrePoll          &457B4
-------------------------------

To be called immediately before Wimp_Poll or Wimp_PollIdle.


WimpExt_Action           &45784
-------------------------------
R0 = task handle
R1 = Wimp_Poll block
R2 = Wimp_Poll reason code
Exit:
R0 = Wimp_Poll reason code (possibly altered)

To be called immediately after Wimp_Poll. 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"...
    SYS "WimpExt_Initialise"...
    WHILE NOT quit%
      SYS "WimpExt_PrePoll"
      SYS "Wimp_Poll"...
      SYS "WimpExt_Action"...
    ENDWHILE
    SYS "WimpExt_CloseDown"...
    SYS "Wimp_CloseDown"...
    END



3D icons and window redraws
===========================

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,4,15,4,0,1,14,12. These defaults can be changed by the user, using the
command 'WimpExt Defaults' - see below. You can specify only some, eg:
w2,4,20 or w2,,,,3. The border numbers are:

     0  : Standard 3D border. Used for headings and buttons. Pops in if
          clicked on.
     1  : Ridged grouping border. Put it around things of a similar nature.
     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.

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 if you want
them to change colour when clicked on (which is definitely recommended), and
you should initially set the background colour of the icon to the out-colour.

Anti-aliased font icons are now supported. The icon 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
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, if the icon is filled (as
it should be using this border) then WimpExtension fills the icon at the same
time. This means that you only very very briefly see the ridged border behind
it.


WimpExt_SlabIcon         &45782
-------------------------------
R2 = window handle or 0 for slabbed icon
R3 = icon handle
If semi-automatic slabbing is enabled, then:
R4 = 0 to pop out, any other to pop in

To be called to force an icon to be slabbed (for example to slab the default
action icon if RETURN is pressed). If semi-automatic slabbing is enabled then
the icon will be popped in or out depending on R4, otherwise it will be
popped in and then out again. If R2 is zero then the last icon to be slabbed
in (either implicity or explicity) is used. Note that in this case the SWI
might return an error (eg. if the window has been deleted), so use the X form
if the SWI.


WimpExt_Redraw           &45783
-------------------------------
R1 = Wimp_RedrawWindow block

To be called in the window redraw loop, to draw the 3D borders round icons.


If you use 3D borders, you MUST call WimpExt_Redraw, or they won't appear.
Your redraw loop would probably look something like:

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


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



Iconbar sprites
===============

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 = pointer to 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 = pointer to sprite name
R4 = pointer to 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.



Linked windows
==============

Linked windows are good for option setting and lists of things. 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.
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
  ...

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.


WimpExt_LinkWindows      &45787
-------------------------------
R2 = main window handle
R3 = sub-window handle
R4 = flags
     bit    meaning
     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-30   reserved; MUST BE 0
     31     link is hidden

Will link two windows so the sub-window moves with the main window. Currently
there is a limit of 16 linked windows - this may be removed in a later
version.


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_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
     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-30   reserved; MUST BE 0
     31     link is hidden
R5 = X offset between main and sub-window
R6 = Y offset between main and sub-window

Will link two windows so the sub-window moves with the main window. Currently
there is a limit of 16 linked windows - this may be removed in a later
version.



Templates
=========

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 = pointer to buffer for storing window handles
R1 = pointer to user buffer for template (big enough for largest template)
R2 = pointer to workspace for indirected icons
R3 = pointer to end of workspace for indirected icons
R4 = 256-byte font reference array (-1 for no fonts)
R5 = pointer to filename of templates file
R6 = pointer to sprite area control block (+1 for Wimp sprite pool)

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
    2     centre window vertically

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


Another SWI is provided for RAM templates. 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 = pointer to user buffer for window definition
R2 = pointer to workspace for indirected icons
R3 = pointer to end of workspace for indirected icons
R4 = -1 for no fonts - fonts not supported at present
R5 = pointer to template
Exit:
R2 = pointer to 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 I have never seen
a program which uses this feature anyway.



Icon handling
=============

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


WimpExt_SetIconString    &4578D
-------------------------------
R0 = non-zero for ellipsis (only if enabled in WimpExt_Initialise)
R2 = window handle
R3 = icon handle
R4 = pointer to 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 R1 then value in the iconblock at offset 20. For
an indirected text icon this will be a pointer to the text.


WimpExt_SetNumberIcon    &45791
-------------------------------
R0 = base
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_GetNumberIcon    &45792
-------------------------------
R0 = default base
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_IncNumberIcon    &45793
-------------------------------
R0 = base
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
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 = pointer to 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 doesn't flicker). This call will now 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.



Pointer handling
================

Pointer changes over icons are controlled by the 'wp' validation command.

   '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 with SELECT
       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
WimpExtension module 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 = pointer to sprite name in the Wimp sprite pool, or 0 to reset pointer
If R0>0:
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 0 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 - 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. Note that this call resets the graphics origin and the
graphics and text windows (ie. it does a 'VDU 26').



Colour menus
============

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 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 (it's in RMA). The 17th option
will be ticked if R0 on entry is 16.



Window handling
===============


WimpExt_CentreWindow     &45799
-------------------------------
R1 = pointer to 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 = Pointer to 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.


WimpExt_SetWindowTitle   &4579F
-------------------------------
R2 = window handle
R3 = pointer to 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 = pointer to 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.



Key handling
============

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.


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.



Radio icons
===========

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

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;ws2,5;ws0,1'.



Menu handling
=============


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 (see 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 = pointer to 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 = pointer to 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 = pointer to 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).



Incrementing and decrementing icons
===================================

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.

See 'icon handling', WimpExt_IncNumberIcon and WimpExt_DecNumberIcon for more
information.



Requester windows
=================

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 don't want a multitasking requester, see
'Immediate windows'.)


WimpExt_OpenRequester    &457A6
-------------------------------
R2 = title (eg. 'Message from MyTask')
R3 = text (eg. 'Document not saved. Save?')
R4 = pointer to block containing button definitons
       text for default button    (eg. 'Save')
       text for button 1          (eg. 'Discard')
       text for button 2          (eg. 'Cancel')
       ...
R5 = button to be used if 'Escape' is pressed (0-3)

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.



Help
====

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

    '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 = pointer to 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, or WimpHelp's Standard 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.



Graphics handling
=================


WimpExtension can help you with plotting sprites (including 256-colour ones)
and also with operations on Draw files (including displaying them).


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 = pointer to 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 = pointer to 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 = pointer to 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 = pointer to 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 = pointer to 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.

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.


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

This SWI performs various operations on Draw files, including rendering them
onto the screen (or printer).

R0 = 0 : Render draw file
-------------------------
R1 = pointer to 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 = pointer to first object (ie. beginning of Draw file+40)
R3 = pointer to end of file
R4 = pointer to graphics clip box, or 0 for no clipping:
       R4+00 = XMin
       R4+04 = YMin
       R4+08 = XMax
       R4+12 = YMax
Exit:
F0-F2 corrupted

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 = pointer to first object
R3 = pointer to 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.)

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

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  = pointer to object
  R4  = pointer to 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 = pointer to 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



WimpExtension's Sprite Pool
===========================

WimpExtension has a built-in



Font menus
==========


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. Note that you must set bit 2 of R2 when you call
WimpExt_Initialise if you wish to use font menus.


WimpExt_GetFontMenu      &457B7
-------------------------------
R0 = 0 to unshade 'System font' entry, 1 to shade it
R1 = pointer to 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. This
SWI may only be called if you set bit 2 of R2 when you called
WimpExt_Initialise.


WimpExt_DecodeFontMenu   &457B8
-------------------------------
R0 = pointer to buffer for font name
R1 = pointer to 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. This SWI may only be called if you set bit 2 of R2 when you called
WimpExt_Initialise.



Immediate windows
=================


Immediate windows are nothing to do with the Wimp. They are redrawn entirely
by WimpExtension, and do not multitask. They can be for reporting the
progress of a non-multitasking operation, or for getting an immediate
response from the user. Because the redraw routine is entirely within
WimpExtension, not all features of windows and icons are supported. Windows
are fully supported apart from scrollbars and the control icons in the window
border. Icons at the moment don't include sprites, but this will be improved
upon in a later version of WimpExtension.


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
  >= &8000     : open immediate window using data pointed to by R1
If R1 = 2 then rest of registers as for WimpExt_OpenRequester
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 iconwas 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. You do not need to have an immediate
window open to use this reason code.
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_Poll[Idle].
Icon types currently supported are:
  sprite-only non-indirected
  text-only, all types
Unknown icon types will be ignored.



Heap manager
============

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 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-zero otherwise
  +1C  hp_created    created flag; 0 if heap is uncreated, non-zero 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

See the file "Heap" for a detailed explanation of the heap memory manager.


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

R0 = 0 - Initialise standard heap:
----------------------------------
R1 = pointer to 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 = pointer to 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.

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 = pointer to 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 = pointer to 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 = pointer to 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.



Data transfer
=============

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. Note that if you are saving from a WimpExt_Heap
block, you should fix the heap beforehand, and unfix it afterwards.

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 = Pointer to filename (pathname or leafname)
R2 = File type
R3 = Pointer to data
R4 = Zero to allow files to be saved to your own task, non-zero otherwise
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. 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
        1 = file saved but is 'unsafe' (eg. saved to another task)
        2 = file saved
If the code is 2, then the filename the file was saved as is at R1+24.


WimpExt_DataLoad         &46383
-------------------------------
R0 = 0 : Load into heap block
  R1 = pointer to 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 = pointer to DataSave or DataLoad message block
  R2 = pointer to 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).



Dragging icons
==============


To make dragging icons about easier, WimpExtension provides a single SWI
'WimpExt_DragIcon'. Normally this will produce an ordinary rotating dash-box
like normal. If you have the DragASprite module loaded, however, it can be
made to use that instead (if the user has configured the computer to use this
module by setting bit 1 of CMOS RAM location 28).

The DragASprite module is included with RISC OS 3 and above. However, the
module can be altered to work on RISC OS 2 by simply removing the call to
OS_ReadSysInfo in the initialise entry. I have no idea whether it is legal to
take a copy of DragASprite from a RISC OS 3 machine, alter it, and put it on
a RISC OS 2 machine, so I haven't supplied a RISC OS 2-compatible copy of
DragASprite.


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 = pointer to sprite block, +1 for Wimp sprite area, 0 to use dash box
R2 = Window handle
R3 = Icon handle
R4 = pointer to sprite name (if R1<>0)
R5 = pointer to 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.
This SWI has been altered since version 1.63 of WimpExtension - if you wish
to use it as before simply set R0 and R1 to zero.



Defaults and sprites
====================

The 'WimpExt Defaults' command is intended to allow the user to customise the
colours of the 3D borders, or to make the 3D borders flat. Whenever the
command is issued, a message (no. &45791) is broadcast, and then the screen
is redrawn. You can read the defaults settings by using WimpExt_MiscOp 0.

The problem with making the 3D borders flat is that sprites in the window
will still be 3D. For this reason, WimpExtension contains both flat and 3D
versions of the most commonly used sprites. A pointer to the sprite area
containing these sprites in returned in R2 when you call WimpExt_Initialise.
The sprites available are: radioon, radiooff, optoff, opton, yes, no, inc1,
dec1, dec, inc. A copy of the 3D sprites group is included in the file
'3DSprs' so you can see the sprites while you're designing your templates.

When you receive the 'defaults changed' message, you should read the new
defaults, and make whatever alterations are necessary if the style has
changed.



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



Miscellaneous SWIs
==================


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_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_CopyString       &4579E
-------------------------------
R2 = 'From' pointer
R3 = 'To' pointer

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 = Pointer to pathname
Exit:
R0 = Pointer to 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.second.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] ).


WimpExt_MemCopy          &457BB
-------------------------------
R0 = 'From' address (word aligned)
R1 = 'To' address (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_PlotBorder       &457BD
-------------------------------
R0 = reason code
 R0 = 0  =>  R1 = pointer to icon block
             R2 = window handle (or -1 for no window)
 R0 = 1  =>  R1 = pointer to 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_Sort             &46380
-------------------------------
R0 = number of objects to sort
R1 = pointer to array of objects
R2 = pointer to comparison routine
R3 = workspace pointer for comparison procedure
R4 = size of object
R5 = address of 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  = address of object a
  R1  = address of 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...
Although R5 doesn't have to be word-aligned, the sort will probably be faster
if it is.


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


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 = pointer to XMin1,YMin1,XMax1,YMax1
  R3 = pointer to 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_BorderOp         &46388
-------------------------------
R0 = reason code
other registers as appropriate for reason code

R0 = 0 : Get border number
--------------------------
R1 = pointer to 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 = pointer to 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.


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

R0 = 0 : Read defaults
----------------------
R1 = pointer to block to read values (64 bytes long)
Exit:
R1 +  0 = top-left colour
R1 +  4 = bottom-right colour
R1 +  8 = in colour
R1 + 12 = channel colour
R1 + 16 = minimum slabbing time
R1 + 20 = sprite style
          bit    meaning
          0      0 = 3D, 1 = flat
          1-31   reserved

Reads in the default values as specified by *WimpExt Defaults. The block
should be at least 64 bytes long, to allow room for future expansion.

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.


WimpExt_SubstituteArgs   &4638C
-------------------------------
R0 = pointer to template string
R1 = pointer to buffer to hold resulting string
R2 = pointer to string %0
R3 = pointer to string %1
R4 = pointer to string %2
R5 = pointer to string %3
R6 = pointer to string %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 zero, in
which case WimpExtension will fault that string's use. To include a % in the
template, use %%.


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

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



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

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

WimpExtension also provides a command 'WimpExt Defaults'. This is used to
specify the default colours and slabbing time for 3D borders. The syntax is:

  *WimpExt Defaults <top-left> <bottom-right> <in> <channel>
                    <time> <sprite style>

The default defaults (ie. those used if you don't issue a WimpExt Defaults
command) are 4 0 14 12 15 0. 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 Defaults 7 7 3 1 15 1

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

The sprite style parameter is 0 for 3D sprites, and 1 for flat sprites. This
allows you to choose whether you want flat or 3D sprites in WimpExtension
applications which take note of this value.

The Defaults 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 Defaults does and
a lot lot more (TM). :-)

BTW, There really IS a good reason for making it a bizarre two-worded
command. All will become clear later ;-)



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

   * Resizeable RamFS and common data area (very very useful)
   * List handling (quite useful when you come to think of it)
   * Fast text displayer (very useful)
   * Libraryification (quite literally, useful)  <--- COMING SOON (hopefully)

Plus anything else useful anybody comes up with...

Improving immediate windows is definitely Acorn's problem - the fact that
they are not provided in the Wimp is a major failing of the RISC OS desktop.
(Or rather, they ARE provided in the Wimp, Acorn just haven't provided a way
for us ordinary mortals to get at them.)

Aha! RISC OS 3 now provides immediate icons, but not immediate windows. I'll
add this into WimpExtension sometime, but I'm still waiting for immediate
windows in the OS... (Look, come on. All we need is a SWI Wimp_FinishRedraw.)

(Basically, by 2022 WimpExtension will be slightly larger than the solar
system and will have more features than are dreamt of in your philosophy.)



Thanks
======


Thanks to Aiden Corey (hope I spelt that right) for helpful suggestions.

Thanks to Jon Thackray for disappearing off to Canterbury and claiming he's
poor when he quite blatantly bought an A410 and an ARM3 and a huge hard
drive, and Impression, and ...

Thanks to James Ponder for uploading stuff to BBSes ( :-)   <- that's a
smiley, for people who haven't used bulletin boards, I mean, I didn't know
what it was at first). James is really annoying and has a 14k4 modem, which
is silly.

Thanks to Mr. Clare, for looking mildly amused at whatever stunning programs
I pass his way...

Thanks to David Cox for being able to get me the SWI chunk for this module,
and being the first person other than me to use it in one of their programs.
(But certainly not the last ;-) )

Thanks to Ben Dooks for winning "Mr. Thinny" Contest three years running.

Thanks to Andrew Clover for not being eight feet tall.

Thanks to Acorn for making sprite and draw-file displaying so incredibly
complicated, and for making RISC OS so flexible, honest.

Finally, thanks to Ben Curthoys for generally complaining at me to get things
finished (maybe I WILL write a game someday), and for a black plastic bag.
(Which has now shuffled off this mortal coil :-( ).



Plugs
=====

Look out for other PD stuff by me... VEnd ... HourMake ... EliteCht ...
RoughTime IV ... SWI ... StopClock ... Quitter ... WimpHelp (coming soon!)
...

Also, products from other members of DoggySoft...

The Hacker, only ú5, the original and BEST games hacker - makes it incredibly
easy to create cheats for games. Many many wonderful features. Just press
Alt-Alt during the game, and The Hacker will pop up... (As seen in Acorn
Computing, BBC Acorn User and Archimedes World...:-) )

Diss, only ú10, by far the best desktop disassembler available for the
Archimedes. Diss has FAR too many features to list them all here, but they
include:
  * Multiple files/multiple views
  * FAST disassembly with optional colour-coding
  * Labels - you can add labels to any address to aid disassembly.
     eg. Instead of:
      B       &381239471
     you get:
      B       mouse_click
  * Automatic un-squeezing of Squeezed files
  * Automatic labels generation for:
      Modules (eg. entry points, SWIs, OS commands, etc.)
      Shared C Library functions
      C programs
      BASIC in-line-assembler programs
      LINKed programs
      ABC programs
  * Search facilities (including search for reference (incredibly useful))
etc. etc. etc... Diss is invaluable for any serious programmer. (As seen in
Archimedes World. :-) )



Finally
=======

Any money, bug reports, information, demos, just about anything to:

                Jon Ribbens
                39 Nutkins Way
                Chesham
                Bucks.
                HP5 2BE

I can also be reached on Arcade BBS, but don't hold your breath...