Implementation notes for the !ResEd Shell
=========================================

Contents
--------

1  Recovering data from CSEs
2  Responding to HelpRequest messages
  2.1  Application icon
  2.2  Dialogue box
  2.3  Menu
  2.4  Document window
  2.5  Palette window


1  Recovering data from CSEs
----------------------------

I'm slightly concerned about the delicate operation of entering into
the data recovery loop when "just about to" do a save of some kind.
The worry about this is that the code has do send/receive multiple messages
and poll the wimp in the middle of some other protocol (DataSave,
Drag-n-Drop). The situations are:-

1) SaveAs

1.1) Late

At the latest, the up-to-date objects are needed by the Get Block Size
step.  The code to obtain them could be put in the Get Block Size
callback, but that entails entering into a mini-poll-loop rather than
using the main poll loop.  Is this safe?  The code for it would
probably have to call the main event despatcher on unknown events...

1.2) Early

Alternatively, we could make the shell recover the data at the first
sign that it might be needed, such as when the menu is first opened.

menu_open()     /* installs menu inter. */
if there are modified objects in the document
  install and initialise recover data interactor, push it on the interactor
  stack

recover data interactor:
  Initialisation: send RESED_OBJECT_SEND to first modified object
  RESED_OBJECT_LOAD: obtain data for object, mark unmodified,
                     send RESED_OBJECT_SEND for next modified object
  RESED_OBJECT_SEND bounces: ignore, try next modified object
  No more objects: pop self, leaving saveas interactor behind

Note that the interactor needs no state information to work its way through
the resources in the document, everything it needs to do this is available
in the messages.


2) DragDrop

At the latest, the data must be secured by the time we DataSave to the
drop point.


3) Close document / quit program "save/abandon" dialogues


Decision:

I think the easiest way to code for all of these is to use a
mini-poll-loop.  The loop should call the main event dispatcher if the
event is not for us.  The despatcher must therefore be reentrant, as
must the interactor code.  This is probably already the case providing
we use our own return buffer for Wimp_Poll.

Modify the event code in main() to export the functions main_next_event()
and main_dispatch_event().  (Done).

When we need to recover objects, write a little loop using
the above functions.  This method avoids writing restartable code
in the middle of an existing interaction, and it also means that
we can (say) ack a recorded message and then send the reply when the
object recovery is complete, if this proves to be necessary in order to
avoid upsetting other protocols.

[ Note (MFC) after the event:

   This is, indeed, what is done - see the document_recover_resource(..)
   in c.document.

   I suspect - like Steve - that there is a fairly deep hole here into
   which some unsuspecting user will eventually fall, although reports
   of unreproducible errors from ResEd have been very few indeed.

   My advice is to let sleeping dogs lie .... ]


2  Responding to HelpRequest messages
-------------------------------------

The following contexts are distinguished, each giving rise to a "base" help
token as shown. If there is no entry for the base token in the Messages file,
then simpler derived tokens are looked up until one is found to be present:
the priority order is as shown.

Note that the shell does not use the substitution mechanism (!<id>/...;)
described in the general notes about Help message processing.


2.1  Application icon
---------------------

  Token:  Hlp.Icon


2.2  Dialogue box
-----------------

  Token:  Hlp.W<n>.<icon-name>     - if pointer over named icon
          Hlp.W<n>                 - if pointer not over named icon

    where  <n> is the registered window type:

                 2  ObjFlags
                 3  Info
                 4  FileInfo
                 5  Copy
                 6  Rename
                 7  SaveAs
                 8  DocWarn
                 9  ExitWarn
                10  ImpWarn

     and   <icon-name> is the name of the icon.

  Examples:  Hlp.W5.OK,  Hlp.W2

  Lookup order:  Hlp.W<n>.<icon-name>
                 Hlp.<icon-name>
                 Hlp.W<n>


2.3  Menu
---------

  Token:  Hlp.M<n>.<h1>.<h2>...

    where  <n> is the registered menu type:

                 1  icon bar menu
                 2  document window menu

     and   <h1>, <h2>, ... is the "hit list" which identifies the entry
            chosen from the menu (the first entry has index 0).

  Example:  Hlp.M2.0.1   - when the pointer is over "File => Save"

  Lookup order:  Hlp.M<n>.<h1>.<h2> ... <hn-1><hn>
                 Hlp.M<n>.<h1>.<h2> ... <hn-1>
                           ...
                 Hlp.M<n>.<h1>
                 Hlp.M<n>


2.4  Document window
--------------------

  Token:  Hlp.E             - if pointer not over icon

    If the pointer is over an icon representing an object of class
    <class-name>, then the help response text is made up of two parts:

      a) The result of looking up the token Hlp.EI and replacing the
         (first) occurrence of %s in it by <class-name>;

      b) The result of looking up the token Hlp.EIS (if the icon is
         selected) or Hlp.EIN (if the icon is not selected).

  Example:

    Suppose the pointer is over a selected icon representing a Quit object
    template, and that the Messages file contains the following entries:

        Hlp.EI:This represents a %s template.
        Hlp.EIN:\Sselect, \Aadd to selection.
        Hlp.EIS:\Adeselect.

    Then the help response text will be:

        This represents a Quit template. Click ADJUST to deselect.


2.5  Palette window
-------------------

  Token:  Hlp.P             - if pointer not over icon

    If the pointer is over an icon representing an object of class
    <class-name>, then the help response text is made up of two parts:

      a) The result of looking up the token Hlp.PI and replacing the
         (first) occurrence of %s in it by <class-name>;

      b) The result of looking up the token Hlp.PIS (if the icon is
         selected) or Hlp.PIN (if the icon is not selected).
