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

This document describes how to write extension modules for Place It.  Please
read all this document (I know it is rather long) before starting to write a
module as you will then know what you can do and what conventions you need to
adhere to.

Your module should be put in a directory titled with the name of your module
in the Extensions directory.  The module itself must have the filename Module
but can have any filetype (I did originally give them a filetype but upon the
request of Roger Wilson, because there are so few filetypes left, I no longer
use one.  The modules were recognised by an identification word at their
start anyway).  Other names you should use in the directory are !ReadMe for
documentation about the module, Messages for a MessageTrans file, Templates
for a template file, Config for a configuration file (you can have more of
these if needed, just use your common sense) and a directory called Source
containing all the source files.

There are two libraries in the Extensions directory which you can use.  The
file called FNadrxx provides a simple means of setting a register to an
address when it is out of range of an adr instruction.  To use it include the
library, call PROCadrinit, and then replace any out of range adr's by
FNadrxx(<r0-r14 or pc>, <address>) where xx is either nothing or one of the
available conditions (except AL, use nothing for this).

The second library is called PROCExtnVs and is used to set several variables
which are useful when writing extension modules.  The variables are set by
including the library and then calling PROCExtnVs.  The variables set fall
into the categories: identifier and version number, interface calls, offsets
with module headers and offsets within a register icon block.  Look at the
library to see the names of the variables set.

You should try and make it so that your module can survive without any
configuration files, so that any user receiving your module can delete any
configuration files and start again (this is most important if your module
stores the full path name of files as these will not exist on someone else's
system).  You should set suitable defaults when no Config files are present.

Each module starts with a header which tells Place It where the code is to
perform certain actions and what poll actions it needs to be passed.

The modules communicate to Place It via jumping to an address passed to the
module during initialisation, having set r9 to indicate what action is
required, and any other entry conditions that are needed.



Header
======

        (4)     identification word = "PMFS" = &53464D50
        (4)     version, currently 0
        (4)     offset to initialise code
        (4)     offset to finalise code
        (4)     offset to return initial pollidle time
        (4)     offset to null event handler
        (4)     offset to redraw background window code
        (4)     offset to message before code
        (4)     offset to message after code
        (4)     offset to create menu code
        (4)     offset to menu select code
        (4)     offset to menu warning code
        (4)     offset to load config file
        (4)     offset to save config file
        (4)     offset to select icon code \
        (4)     offset to remove icon code |
        (4)     offset to open parent code  \ these apply to
        (4)     offset to move icon code    / registered icons
        (4)     offset to save icon code   |
        (4)     offset to run icon code    /
        (4)     offset to general window handler code
        (4)     offset to name text        \
        (4)     offset to purpose text      \ these will be inserted into the
        (4)     offset to author text       / info window for your module
        (4)     offset to version text     /
        (4)     poll flags
        (12)    title extended with zeros (NB must be terminated by zero, so
                can only be eleven characters long).  The title is used in
                the menu structure if more than one module has been loaded.

All the offsets to code (except create menu) may be zero if there is no
action to be performed.

The offsets to text are the fields to be put in the info window for the
module.  Place It will automatically fill them in when the window is opened.
Each field can be upto 29 characters long (excluding the terminating zero
which must be present).

The poll flags are as passed to Wimp_Poll in r0.  For efficiency you must
mask out all messages that you do not want (especially null messages).  You
may change the flags at a later date so if, for example, you only want null
events only after the user has selected a menu entry until the mouse is
clicked again, set bit zero in the word, and change this later as required.

If the null event bit (0) is set then you will receive no null messages.

The redraw bit (1) only applies to other windows you may create not the
backdrop window as there is a separate entry point for that.

The menu select bit (9) is ignored as it has its own entry point.

The message action bits (17, 18 and 19) are ignored entirely.


Entries
=======

There is no need to preserve any registers apart from r13 (which is set up to
a full descending stack with a guaranteed ten words free) in any of the
entries.


Initialise
----------

Entry
        r0 = address to call to interface to Place It
        r1 = address of modules entry in Place It's table
Exit
        V set on error
        If V set then r0 -> error block

Action
        You should store both the values passed.  The table entry is an
altered copy of the header of the module.  The only values you should change
are the poll flags and the pollidle time.  If you change these you should
inform Place It via the appropriate interface call.


Finalise
--------

Entry
        None
Exit
        None

Action
        You should close all message files, free any RMA claimed, etcetera as
Place It will be closing down.  You should not report any errors due to
closing down, and should just ignore them.  This is the case, as Place It may
be closing down due to a fatal error, and the user does not want to be
bombarded by a plethera of errors.


Return Initial PollIdle Time
----------------------------

Entry
        None
Exit
        r0 = 0          => want null messages as often as poss (ie call
                           wimp_poll with null messages enabled
           bit 31 unset => initial pollidle time if bit 31 unset
           bit 31 set   => want message every (r0 bic 1 << 31) centiseconds

Action
        You must have this entry if you want to receive null messages (have
bit zero in the poll flags unset).
        Three types of timing are available.  If you want as many null
messages as possible then set r0 = 0.  If you want null messages at specific
times (for example for a clock) then leave bit 31 unset.  If you want null
messages at even intervals but do not care when they start) then set bit 31,
and Place It will schedule all the null messages from the modules
intelligently.  It is up to you to make sure that the time you want to call
is after the current OS_MonotonicTime.
        When you next want a null message to be asked for when you receive
your first null message.
        Using bit 31 in this way is not really a serious restriction, as the
computer would have to be on for at least two thirds of a year without being
reset to need to set this bit otherwise.


Null Event Handler
------------------

Entry
        r0 = current OS_MonotonicTime
        r1 = time you wanted to be called if not want all null messages
Exit
        r0 = time you next want to be called if not want all null messages

Action
        You should do whatever you want to do upon null events, then return.
        To set the time you next want to be called (assuming you still have
r0 and r1 set as at entry), code such as that below should be used :-

.loop
        add     r1,r1,#time_between_calls
        cmp     r1,r0
        blt     loop
        mov     r0,r1

        Note if your process took a long time you should reread
OS_MonotonicTime (into r0) and execute the code above just before returning.

        Again it is up to you to make sure that the time you want to called
is after the current OS_MonotonicTime.

        If you want all the null messages (pollidle time table entry = 0)
then r1 will not be set on entry and you do not have to set r0 before
returning.


Redraw Background Window
------------------------

Entry
        r1 -> block as returned by Wimp_RedrawWindow or Wimp_GetRectangle
Exit
        None

Action
        You should redraw any icons you have on the background.  If you have
used the Interface manager, then the calls to it will be made automatically
by Place It, so you need not have this entry just to do that.


Message Before
--------------

Entry
        r0 =  17,18 - the action returned by Wimp_Poll
        r1 -> block as returned by Wimp_Poll
Exit
        None

Action
        This entry is called whenever a message (action 17,18) is sent to
Place It.  It is called before Place It gets a chance handle the message.
You must NOT alter the data block pointed to by r1.
        For efficiency you should only make this entry defined if you wish to
perform an action upon receipt of a message that Place It handles.

        The messages handled by Place It are :-

Message no  |  Name
------------+----------------------
 0          |  Closedown
 2          |  Datasave acknowledge *
 3          |  Dataload             *
 4          |  Dataload acknowledge *
 9          |  Palette change
 502        |  Help request         *
 400c0      |  Menu warning
 400c1      |  Mode change
 400c7      |  Task name is

        The starred (*) messages are only handled by Place It if they apply
to the backdrop or load sprite windows otherwise they passed through to the
general wimdow handler of the module of the registered the window concerned.
        Datasave and Dataload acknowledges are passed onto message after if
the original datasave or dataload message was not originated by Place It.
These messages are passed to all modules so you must check the message
reference to make sure it as a reply to message that you sent.
        As it is not described on the PRM's anywhere here is format of a
message sent by !Help requesting help :-

        block+16        &502 = the message action
             +20        mouse x coordinate
             +24        mouse y coordinate
             +28        mouse button state
             +32        window handle (-1 if not over a window)
             +36        icon handle (-1 if not over an icon)

        To reply you should send a message as follows :-

        block+12        block+8 of the message sent by !Help
             +16        &503 = the message action
             +20        help message terminated by 0

Don't forget to set the length of the message in block+0.
        However the best way to reply is via the call reply_to_help (23).


Message After
-------------

Entry
        r0 =  17,18,19 - the action returned by Wimp_Poll
        r1 -> block as returned by Wimp_Poll
Exit
        None

Action
        This entry is called whenever a message (action 17,18 or 19) is sent
to Place It that Place It does not want to process itself (see above for a
list of messages Place It processes).  Any messages Place It processes are
not passed through to this call.
        Message acknowledgements (r0 = 19) are only sent if they are not
acknowledgements to messages originated by Place It.
        You must NOT alter the data block pointed to by r1 as it may be
passed onto other modules.


Create Menu
-----------

Entry
        None
Exit
        r0 -> menu structure

Action
        The title of this entry point is slightly deceptive.  The menu need
not actually be created here.  In fact it is more efficient to create the
menu (from a message file) during initialisation, and then simply return the
pointer to the menu.  Every extension module must have a menu.  This is
because the first menu item must by Info.  This item must have a submenu
pointer (the hollow arrow) and have the generate message bit (bit 3) of the
menu flags set.  Place It will open the info window with the fields filled in
from the information given in the header.


Menu Select
-----------

Entry
        r1 -> list of menu entries selected.  The list starts at your menu
Exit
        None

Action
        You should perform the relevant action depending upon what was
clicked.  Note the module will not be called if the Info item is clicked
upon, or, no menu item was selected (eg click over dashed line).  If the item
was clicked upon with adjust the create menu entry will be called again to
reopen the menu.
        This entry must exist if you have any menu items apart from the info
one.


Menu Warning
------------

Entry
        r1 -> menu structure rooted where needed to be opened
        r2 =  x coordinate of where to put top left of menu/window
        r3 =  y coordinate of where to put top left of menu/window
        r4 -> list of menu entries selected.  The list starts at your menu
Exit
        None

Action
        This entry is called if you have set any item within your menu
structure to produce a menu warning (bit 3 of the menu flags set) and it is
not the info item, (Place It handles this automatically).  You should open
the relevant menu/window using Wimp_CreateSubMenu.
        This entry must exist if you have set the menu warning bit anywhere
in your menu structure, apart from on the info item.


Load Config File
----------------

Entry
        r0 = 0 => first load during initialisation
        r0 = 1 => restore has been selected
Exit
        None

Action
        This entry is called in the two cases shown above.  In either case
you should reinitialise any parameters you read from your config file(s).


Save Config File
----------------

Entry
        None
Exit
        None

Action
        This entry is called when save is selected upon the backdrop menu.
You should save your config file(s).


Select Icon, Remove Icon, Open Parent, Move Icon, Save Icon and Run Icon
------------------------------------------------------------------------

        These entry points are described in the section on registered icons.



Interface
=========

When the interface is called, r9 indicates what action is required, and r14
must be set to the return address.  All registers are preserved apart from
those used to pass back results.  In the section below, the number in
brackets is the value of r9.  Sorry about the rather random order but they
were written in an order which made them easy to test.


Fatal Error (0)
---------------

Entry
        r0 -> error block
Exit
        Doesn't

Action
        Produces an error box informing of a fatal error, and then aborts
Place It.


Read Window Handle (1)
----------------------

Entry
        None
Exit
        r0 = window handle of the background window


Get Heap Block (2)
------------------

Entry
        r3 = amount of space wanted
Exit
        r2 -> heap block if succeeded
        r2 =  0 if could not allocate the space, r3 corrupted in this case

Action
        Tries to obtain the amount of memory requested by first using the
available memory, and then extending the wimp slot if necessary.


Extend Heap Block (3)
---------------------

Entry
        r2 -> heap block
        r3 =  amount of change wanted (signed integer)
Exit
        r2 -> heap block if succeeded
        r2 =  0 if could not allocate the space, r3 corrupted in this case

Action
        Tries to obtain the amount of memory requested by first using the
available memory, and then extending the wimp slot if necessary.


Free Heap Block (4)
-------------------

Entry
        r4 -> heap block
Exit
        All registers preserved

Action
        Frees the heap block allocated by get heap block.  If this was the
last heap block, then the wimp slot is shrunk if possible.


Open Message File (5)
---------------------

Entry
        r0 -> word aligned 16 byte block to hold information
              this must be passed to all further MessageTrans calls
        r1 -> filename, this must remain unchanged while the file is open
Exit
        V and r0 set on error

Action
        Open the message file passed in r1 for later use.  This call is best
used during your initialisation entry.  If you do, then Close Message File
must be called during your Finalise entry.  Note you should store a flag
which indicates whether the message file has been opened, as the Finalise
entry may be called before the Initialise entry (because of an error in
another module's or Place It's initialisation), or the message file may fail
to open. See one of the example message files provided for the format.  Note
';' starts a comment and %0, %1, %2 and %3 are parameters.


Message Lookup (6)
------------------

Entry
        r0 -> 16 byte block passed to open message file
        r1 -> token
             /  0  => don't copy the message out
            /   1  => copy the message into poll space
        r2  \   2  => copy the message into poll space+4
             \  >2 => copy the message at r2
        r3 = length of free memory at r2 if r2 > 2

                  r2 = 2 is used during fatal error and report error
                  token routines

        r4 => first parameter
        r5 => second parameter
        r6 => third parameter
        r7 => fourth parameter
Exit
        r0    corrupted
        r1 -> terminator of token
        r2 -> result string (read only if r2=0 on entry)
        r3 =  length of result before terminator

Action
        Lookup a message indicated by token performing any necessary
parameter substitution.  If the message cannot be found, an error will be
reported automatically and Place It aborted.  If a parameter is needed and
the corresponding register (eg r4 for %0) is 0 then the %0 is left in the
message.  Set the register to point to a null string to replace the %<number>
by ''.
        The ability to copy the message into poll_space (and +4) is used
primarily by the error routines.  This means if you plan to pass an error to
fatal error, you must create the message somewhere else.


Message Make Menus (7)
----------------------

Entry
        r0 -> 16 byte block passed to open message file
        r1 -> menu definition (see below)
        r2 -> RAM buffer to hold menu structure
        r3 =  size of RAM buffer
Exit
        V and r0 set on error

Action
        Build a menu structure from entries in a message file.  Things like
the width of the menu are automatically calculated for you.

Menu definition
        The menu definition is a sequence of menu definitions terminated by a
zero word.  Each definition has an initial bit which defines the title,
colour and dimensions then a sequence of menu item definitions.

  Initial bit
        +0  (n)  token for menu title, terminated by any char <= 32, or ","
                 or ">".  Null => no more menus, otherwise
        +n  (1)  menu title foreground and frame colour
            (1)  menu title background colour
            (1)  menu work area foreground colour
            (1)  menu work area background colour
            (1)  height of menu items
            (1)  gap between menu items

  Menu item definition
            (n)  token for menu item, terminated by any char <= 32, or ","
                 or ">"
  Word align now
            (4)  menu flags (bit 7 => last item)
            (4)  offset in RAM buffer from menu start to submenu start
                 0 => no submenu
            (4)  icon flags

If a menu entry is writable (bit two of menu item flags set), and indirected
(bit eight of the icon flags set), then it is assumed that the 3 words in the
RAM buffer have already been set, and the token is expanded into the buffer
(it is truncated to the specified length if need be).


Close Message File (8)
----------------------

Entry
        r0 -> 16 byte block passed to open message file
Exit
        V and r0 set on error

Action
        Closes an open message file.  This is normally called during a module
finalise entry (see Open Message File for more information).  You should
ignore any errors returned by this call because Place It will, if you include
this in your finalise code, either be closing down or have suffered a fatal
error.


Token Report Error (9)
----------------------

Entry
        r0 +0 = error number
           +4 = error token
        r1    = flags as for Wimp_ReportError
        r2    = 16 byte block used to open the message file
        r4-7 -> parameters if wanted
Exit
        r1 = return status
                1 => 'OK' Selected
                2 => 'Cancel' selected
        flags preserved
        r0,2 corrupted

Action
        Report an error using the token and error number given.


Report Error (10)
-----------------

Entry
        r0 +0 = error number
           +4 = error text
        r1 =    flags as for Wimp_ReportError
Exit
        r1 = return status
                1 => 'OK' Selected
                2 => 'Cancel' selected
        flags preserved
        r0,2 corrupted

Action
        Report an error using the error text and number given.


Read Window Size (11)
---------------------

Entry
        None
Exit
        r0 = min x of window
        r1 = min y of window
        r2 = max x of window
        r3 = max y of window

Action
        As Place It keeps a track of the screen dimensions (by monitoring the
mode changed message), this call is provided to efficiently read the window
size.
        Note, although it may seem that min x and min y will not vary, min y
can have (by recompiling the source) other values than that just above the
iconbar.  This is because someone donated five pounds to Breakout (see the
!Charity documentation file) to get me to allow the window to cover the whole
screen as they had made the iconbar moveable.  This I gladly did.


Change Poll Mask (12)
---------------------

Entry
        Changed value of poll_mask in the header for your module.
        Updated value of pollidle_time in the header if re-enabling null
        messages.
        Set to time or 0 if want all null messages.
Exit
        None

Action
        Place It will work out the new mask it needs to pass to Wimp_Poll (or
Wimp_PollIdle).  You should change the mask (and possibly pollidle_time) in
the header block (using the address passed to you in r1 when initialising)
before making this call.
        Note you MUST call this entry if you change between wanting all null
messages and only wanting some null messages (or vice versa) so that Place It
knows whether to use Wimp_Poll or Wimp_Pollidle.


Force Redraw Background Window (13)
-----------------------------------

Entry
        None
Exit
        None

Action
        The background window will be redrawn.  You will be called via your
redraw entry (if not zero).  If you want to redraw just part of the window
you should call Wimp_ForceRedraw yourself (you can obtain the window handle
of the background window via the interface).


Read Got Backdrop Flags (14)
----------------------------

Entry
        None
Exit
        r0 = 0 => no backdrop is loaded
        r0 = 1 => a backdrop is loaded

Action
        Read the flag indicating whether a backdrop is loaded.


Read Colour Menu Address (15)
-----------------------------

Entry
        None
Exit
        r0 -> address of colour menu data block

Action
        Returns the address of the colour menu data block.  This is provided
for you to use within your own menu trees.  You should make the menu entry
which points to this as needing a menu warning message.  When you receive
this message you should call the routine below to make the entry you want
ticked. If you want no tick on the menu you must still call the routine
below, as an entry is likely to have been ticked by another use of the menu.


Tick Colour Menu Entry (16)
---------------------------

Entry
        r0 = -1   => remove ticks from all entries
        r0 = 0-15 => colour menu entry to tick
Exit
        None

Action
        Removes any previous tick on the colour menu and if r0 is between 0
and 15 ticks the new entry.  You should call this when you receive the menu
warning message for the colour menu and when an entry is selected by the
mouse incase it is selected by adjust (in which the menu will be reopened by
Place It).


Calls 17-19
-----------

        These are to do with registered icons.  See the section on these
later.


Check Create Error (20)
-----------------------

Entry
        r0 = error block returned by Wimp_CreateWindow, Wimp_CreateMenu or
             Wimp_CreateSubMenu
Exit
        r0 corrupted
        if the error was 'Too many windows', 'Wimp unable to claim work area'
        or 'Window definition won't fit' then the call returns with V set if
        it was another error then the call does not return

Action
        If the error was 'Too many windows', 'Wimp unable to claim work area'
or 'Window definition won't fit' then the error is reported and the call
returns.  Otherwise the error is reported as a fatal error and the call does
not return.
        This call should be made whenever you call Wimp_CreateWindow/Menu or
SubMenu and an error is returned.  The V flag is left set so that you can do
any further action you want to upon the window or menu failing to open.  You
should not report another error though.


Register Window (21)
--------------------

Entry
        r0 = window handle
        r1 = table address of module as passed during initialisation
Exit
        V set if Place It ran out of memory to register the window

Action
        Informs Place It that a window belongs to your module.  You should
call this entry immediately after you create the window incase it cannot be
registered (very unlikely as only 2 words per window are needed), in which
case you should delete the window from the wimp immediately (you should NOT
call deregister window).
        Any redraw, open window, close window, pointer entering/leaving
window, mouse click, key pressed, scroll request or lose/gain caret messages
that you want (as indicated by the value of your poll mask entry) will be
passed on to you via your general window handler entry.  Note unlike the Wimp
if you mask out some of these message they are not queued for later
processing, you just miss them. This entry must be defined if any of the
above may be generated for your window and the relevant bit is unset in the
poll mask.
        Any messages for the window, ie dataload, datasave or help request
will be passed to the general window handler provided the relevant bit (17,18
or 19) of the poll mask is unset.
        Note the poll mask may be changed at any time.


Deregister Window (22)
----------------------

Entry
        r0 = window handle
Exit
        None

Action
        Informs Place It that the window no longer exists and therefore you
do not want to be called when any poll action is returned for the window.
This entry should be called when you delete the window.



Reply To Help (23)
------------------

Entry
        r0 -> 16 byte block that describes a message file (see open message
              file)
        r1 -> token
Exit
        None

Action
        Sends a message to !Help giving the Help on the requested icon.  You
should call this entry when you receive a Help Request message (&502).  You
must NOT have altered the message block passed in r1 to you via the message
before or message after entry points.


Open Main Menu (24)
-------------------

Entry
        r1+0 = current x coordinate of mouse
        r1+4 = current y coordinate of mouse
Exit
        None

Action
        Opens the main Place It menu at the current mouse position.  You
should call this entry when the menu button is pressed over any windows you
open which do not have their own menus.
        Note that the values required to be stored at r1 are such that the
value of r1 returned from Wimp_Poll when a mouse click occurs could be used.


Register Menu (25)
------------------

Entry
        r0 = address to call when a menu entry is selected
        r1 = address to call when a menu warning message occurs
Exit
        None

Action
        Allows you to open your own menu instead of the Place It main menu.
You can only do this over one of your own windows. When you open the menu you
should call this entry with r0 and r1 set appropriately. R1 need not be
defined if your menu structure never produces a menu warning message.
        When a menu entry is selected the address passed in r0 is jumped to
with r1 pointing to the list of selected menu entries as returned by
wimp_poll.
        When a menu warning message occurs the address passed in r1 is jumped
to with r1 pointing to the block returned by Wimp_Poll.
        When the Place It main menu is opened it sets up its own handlers.


Register User Drag (26)
-----------------------

Entry
        r0 = address to call when a user drag event (7) occurs
Exit
        None

Action
        This call works in a similar way to the above. If you wish to set up
a drag yourself then you should call this entry.
        When Place It starts a drag it sets up its own handler.



Registered Icons
================

        This section describes all the calls and entry points which concern
registering icons on the backdrop.
        A registered icon data block consists of :-


        (4)     offset to icon data (see later)
        (4)     offset to name to use in main menu (where file/dir/...
                usually appears) when only this icon is selected
        (4)     offset to name to use as title of file/directory/...  menu
                when only this icon is selected.  This is a group name and
                is also used in some error messages
                This entry and the one above should start with capital
                letters
        (1)     icon handle, filled in when registered or reregisted
        (1)     flags to indicate whether selected or not.  This is updated
                automatically by Place It
                The values it can have are
                  0 => unselected
                  1 => selected
                  2 => selected by menu (ie a menu has been opened over the
                       icon when no other icons were selected)
        (1)     identifier byte to indicate that this is a registered icon
                and not a Place It icon.  You must not alter this value which
                is set when the icon is registered
        (1)     flags.  The bits when set indicate
                  0 => call select icon entry point when the icon is selected
                       or unselected
                  1 => the icon can be removed
                  2 => the icon can have its parent opened
                  3 => call move icon entry point when the icon is moved
                  4 => the icon can be saved to the filer
                  5 => the icon can be saved to applications
                  6 => the icon can be run (when double clicked upon)
         (4)    address of your table entry as passed in r1 during
                initialisation
         (4)    address of text to pass to !Help.  This can contain the string
                |M to indicate a newline.  It must be terminated by a control
                character.  It should be looked up from a message file during
                initialisation

        The icon data consists of a data block suitable to be passed to
Wimp_CreateIcon.  The window handle is filled in automatically by Place It.

        (4)     one word gap for the window handle of the backdrop window
        (4)     minimum x coordinate
        (4)     minimum y coordinate
        (4)     maximum x coordinate
        (4)     maximum y coordinate
        (4)     icon flags
        (12)    icon data


        The interface calls provided are :


Register Icon (17)
------------------

Entry
        r0 => register icon data block
Exit
        None

Action
        This call registers an icon with Place It.  The icon is created and
the icon handle filled in in the data block.  The icon may have border types
0-2 as provided by the interface manager (the others are too wide and parts
of them will be lost during the redrawing that occurs).
        The icon will be set as unselected.


Deregister Icon (18)
--------------------

Entry
        r0 => register icon data block
Exit
        None

Action
        This call deregisters an icon with Place It.  The icon is deleted but
no redraw message is sent so it is not actually removed from the screen.
However if you are making this call in response to a move or remove icon
request, then a redraw request will be sent which covers the whole area moved
or removed, and so there is no need for you to send one.


Reregister Icon (19)
--------------------

Entry
        r0 => register icon data block
Exit
        None

Action
        This performs the actions of deregistering and the registering your
icon.  You can use this to move an icon about by changing the icon block
before making this call.  This can be used as a response to a move icon
request which you wish to handle yourself or when a load config file request
is sent which corresponds to restore backdrop (r0 = 1).  You should call this
in the later case because your icon(s) may have been moved without the
backdrop being saved, and when restored they should be put back into the
positions in the config file(s).



The entries in your module which concern registered icons are :-


Select Icon
-----------

Entry
        r0 -> pointer to registered icon data block
        r1 = 0 => unselect icon
        r1 = 1 => select icon
Exit
        r0 = 0 => no more processing needed
        r0 = 1 => Place It will invert the icon

Action
        This entry is called whenever one of your registered icon that has
the call code upon (un)select flag set is (un)selected.  The value of r1
determines whether the icon is being selected/unselected.  You may use this
call in two ways.  If you just wish to record the selected/unselected state
of your icons, then update your record and return with r0 = 1, upon which
Place It will invert the icon for you automatically.  If you wish to indicate
that the icon is selected in some other way than by inversion (you must
indicate that the icon is selected), then change the appearance of the icon
yourself and return with r0 = 0.
        Note the selected/unselected byte of the registered icon data block
will have been changed before this call is made.
        This entry point must be defined if any of your registered icons have
the call select code flag set.


Remove Icon
-----------

Entry
        r0 -> pointer to registered icon data block
Exit
        None

Action
        This entry is called whenever one of your registered icons is to be
removed (an error will be produced if one of your icons that cannot be
removed is attempted to be).  You should deregister the icon using the
interface call deregister icon.
        There is no need to force a redraw as Place It will do this
automatically.
        This entry point must be defined if any of your icons can be removed.


Open Parent
-----------

Entry
        r0 -> pointer to registered icon data block
Exit
        None

Action
        This entry is called whenever one of your registered icons needs its
parent opened (an error will be produced if one of your icons that cannot
have its parent opened, is attempted to have it opened).  You should perform
the action you see appropriate.
        This entry point must be defined if any of your icons can have its
parent opened.


Move Icon
---------

Entry
        r0 -> pointer to registered icon data block
Exit
        r0 = 0 => no more processing needed
        r0 = 1 => Place It will move the icon automatically using the
                  interface call reregister icon

Action
        This entry is called whenever one of your registered icons that has
the call code upon move flag set is moved about the backdrop.  The icon block
pointed to by the first word in the registered icon block will have been
updated to contain the new x and y max and min positions when this entry is
made.  Like the select icon code you may use this call in two ways.  If you
just wish to record the position of your icons, then update your record and
return with r0 = 1 upon which Place It will call reregister icon for you
(note this could change the icon handle).  If you wish to move the icon
yourself then do so, and return with r0 = 0.
        This entry point must be defined if any of your registered icons have
the call move code flag set.


Save Icon
---------

Entry
        r0 ->  pointer to registered icon data block
        r1 = 1 if dragged to filer window
        r1 = 3 if dragged to application (either window or iconbar icon)
Exit
        None

Action
        This entry is called whenever one of your registered icons needs to
be saved (either to an application or to a filer window, an error will be
produced if the icon dragged cannot be saved to where it is dragged as
indicated by its flags).
        The seemingly odd values of r1 are because they are the message
number Place It sends in that particular case.  Ie datasave (1) messages are
sent to the filer and dataload (3) messages are sent to applications.
        You should stick to this if you place any actual files on the
backdrop yourself, because sending datasave messages application results in a
scrap file being created instead of loading the actual file.
        This entry point must be defined if any of your icons can be saved to
either the filer or applications.


Run Icon
--------

Entry
        r0 -> pointer to registered icon data block
Exit
        None

Action
        This entry is called whenever one of your registered icons is double
clicked upon (if it cannot be ran, as indicated by its flags, then no error
message is produced).  You should perform the action you wish to.  The icon
will have been automatically deselected before this entry is called.  If it
was doubled clicked on using adjust, the icon will attempt to be removed,
however no error will be produced if the icon cannot be removed, as indicated
by the flags.
        This entry point must be defined if any of your icons can be run.


P.S. Thanks to Al for proof reading this document.  Hope you didn't get too
bored.
