Format and usage description of all messages used by
the OmniDesk suite of utilities. These messages have
been officially allocated by Acorn.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Message_UtilDeclare (&825C0):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the message block that an OmniDesk utility
must send to OmniDesk if OmniDesk has started it up.

The message contains 208 bytes, starting at Block+20
(ie taking into account the standard 20-byte message
header):

Offset: Length: Contents:
~~~~~~~ ~~~~~~~ ~~~~~~~~~
+20     4       Task handle
+24     20      Task name (for Utilities menu and
                Preferences window) 19 chars+CHR$13
+44     11      Leafname of application within
                Utilities directory (ending CHR$13)
+55     77      Help message detailing SELECT- or
                ADJUST-click action of utility. This
                is used both for the icon bar icon
                and for the menu entry.
+132    77      Help message detailing DRAG action
                (or blank for none) used for icon-
                bar icon and drag target window.
+209    End of message

NB The utilities should not provide an ADJUST action
for the icon bar icon, since the SELECT action may
be assigned to either SELECT or ADJUST by OmniDesk.
The help message should omit the opening "Click
SELECT/ADJUST to ", since this is provided as
appropriate by OmniDesk.

The Drag message should be of the form "Drag ...
here to ...", since it is used both by the help
message for the icon bar icon and as the text label
in the drag target window.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Message_UtilOpen (&825C1):
~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the message block received by an OmniDesk
utility if it is chosen from the Utilities menu, or
if it has been selected to receive SELECT or ADJUST
clicks on the icon bar icon, or file-drags to the
icon bar icon.

Offset: Length: Contents:
~~~~~~~ ~~~~~~~ ~~~~~~~~~
+20     4       4 for a mouse click
                2 for a file to receive
+24     20      Taskname of RECEIVER
-------
If Block!20=2, then:
+44     4       Estimated size of data in bytes
+48     4       File type
+52     ?       Path name

When a utility receives this message from OmniDesk,
it should check that the taskname in Block+24 is its
own taskname, since it may be picking up a message
broadcast for another utility.

If the message is for the utility which receives it,
the utility should take the following actions:

If Block!20=4, then behave as if SELECT had been
clicked on the icon bar icon.

If Block!20=2, then load the file using the supplied
pathname (as if it had been dragged to the icon bar
icon). When processing is complete, send a message
UtilAckLoad to OmniDesk so it can tidy things up as
necessary (i.e. delete <Wimp$Scrap> if appropriate).

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Message_UtilQuitting (&825C2):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is used under three circumstances:

1) OmniDesk broadcasts the message when Quit has
been chosen from its icon bar menu. Any utility
which has been started by OmniDesk must now exit
immediately.

2) OmniDesk sends the message to each appropriate
utility when 'OK' is clicked in the Preferences
window: i.e. any utility which is running and whose
'load' switch is deselected will be told to quit.

3) If a utility quits unexpectedly, or is quit from
the task manager, it sends the message to OmniDesk
so that its internal utility record can be updated.

Offset: Length: Contents:
~~~~~~~ ~~~~~~~ ~~~~~~~~~
+20     4       Task handle

For circumstances (1) and (2), the task handle will
be that of OmniDesk.

For circumstance (3), the task handle will be that
of the quitting utility.

The message is only *broadcast* under circumstance
(1), and unless the task handle received is that of
OmniDesk, a receiving task should ignore it.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Message_UtilReside (&825C3):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No contents
~~~~~~~~~~~
A utility receiving this message should update its
status to one of permanence.

Specifically, update the Exit variable to FALSE and
become permanent: i.e. do not quit until actually
told to do so by OmniDesk.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Message_UtilLoadAck (&825C4):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No contents
~~~~~~~~~~~
A utility should send this message to OmniDesk once
it has finished processing a file which it was told
to load by a previous Message_UtilOpen with a
Block!20 code of 2.

Specifically, the process is as follows:

1. The user drags a file to the OmniDesk icon or
drag target window.

2. OmniDesk sends a Message_UtilOpen to the utility
in question.

3. The utility processes the file if appropriate or
puts up an error if it's the wrong file type etc.

4. The utility sends a Message_UtilLoadAck back to
OmniDesk.

5. OmniDesk deletes <Wimp$Scrap> if that's where the
input file came from.

N.B. If any utility which accepts dragged files is
run alone (i.e. not via OmniDesk, but installing its
own icon on the icon bar), then it must handle all
drags, including those involving <Wimp$Scrap>,
itself. This will of course also apply to utilities
started by OmniDesk if they allow the user to drag
a new file into one of their own windows.
