The following is the Wimp message protocol as used by the Task Window
module (0.29) supplied with Desktop C, and Desktop Assembler.  Note that 
the module only provides pre-emptive scheduling for tasks running under 
its control; a Wimp application (like Edit) is required to display output 
produced by such a task (ie despite the name of the module, it 
doesn't give you a Wimp window!).

Terminology:     Parent == a task which has created a child using
                           the *TaskWindow or *ShellCLI_Task command.

                 Child == a task created by a *TaskWindow or *ShellCLI_Task
                          command, and hence being pre-emptively scheduled by
                          the task window module.

                 Edit == the RISC OS text editors (both !Edit and !SrcEdit).

                 FrontEnd == the FrontEnd module supplied with Desktop C and
                             Desktop Assembler.
 


  Message number:  TaskWindow_Input  (0x808c0)

  Purpose:         Used to send input data from Parent to Child.

  Data:            R1+20     size of input data
                   R1+24 ... input data 

                   Note:  input can also be sent via a normal RAM
                   transfer protocol, ie send a Wimp_MDATASAVE, and
                   then wait for wimp_MRAMFETCH's and send back 
                   wimp_MRAMTRANSMIT's when you get them (see PRM).



  Message number:  TaskWindow_Output (0x808c1)

  Purpose:         Sent to the Parent when one of its children has produced
                   output.

  Data:            R1+20     size of output data
                   R1+24 ... output data 



  Message number:  TaskWindow_Ego (0x808c2)

  Purpose:         Sent to Parent, to inform him of the Child's task-id.

  Data:            R1+4      Child's task-id (as filled in by Wimp)
                   R1+20     Parent's txt-handle (as passed to *TaskWindow
                             or *ShellCLI_Task). 

                             Note: this is the only time the txt-handle is 
                             used.  It allows the Parent to identify which 
                             Child is announcing its task-id.
                             


  Message number:  TaskWindow_Morio (0x808c3)

  Purpose:         Sent to Parent when Child exits.

  Data:            none  (all necessary info is in wimp message hdr).

 

  Message number:  TaskWindow_Morite (0x808c4)

  Purpose:         Sent by Parent to kill Child.

  Data:            none  (all necessary info is in wimp message hdr).



  Message number:  TaskWindow_NewTask (0x808c5)

  Purpose:         Broadcast by external task which requires an 
                   application (eg Edit) to start up a task window.  
                   If the receiving application wishes to deal with this 
                   request, it should first acknowledge the Wimp message,
                   then issue a SWI Wimp_StartTask with R1+20... as the 
                   command.

  Data:            R1+20 ...    the command to run.



  Message number:  TaskWindow_Suspend (0x808c6)

  Purpose:         Sent by Parent to suspend a Child.

  Data:            none  (all necessary info is in wimp message hdr).



  Message number:  TaskWindow_Resume (0x808c7)

  Purpose:         Sent by Parent to resume a suspended Child.

  Data:            none  (all necessary info is in wimp message hdr).




Two examples of using the TaskWindow module
-------------------------------------------

  There are (currently) two examples within Acorn of use of the TaskWindow
module.  One is Edit and the other is the FrontEnd module.


  FrontEnd
  --------

  When the FrontEnd module runs a non-desktop program, it first issues a 
  SWI Wimp_StartTask with a *TaskWindow command, something like:

     *TaskWindow -quit -wimpslot <n>K -name "<progname-and-parameters>" 
                 -task &<frontend's-task-id> -txt &<unique-frontend-handle>

  The use of -quit indicates to the TaskWindow module to run the given 
  task, and then exit immediately, rather than running a CLI.  This means
  we get a TaskWindow_Morite message when the given command exits.

  The task-id passed via -task is used by the TaskWindow module to send you 
  Wimp messages, and to check that you are the legitimate Parent of the 
  Child (!)  The -txt parameter allows you to identify which child is 
  being referred to, even before it has a Wimp task-id.  Note: normally on
  receipt of a *TaskWindow command the TaskWindow module will broadcast a 
  TaskWindow_NewTask message (since the requesting task may be different 
  to the task who will do the display!);  however if -task and -txt are 
  used, the TaskWindow module assumes the requesting and displaying tasks 
  are the same (which is the case for the FrontEnd module), and immediately
  starts up the given task, sending any output messages to the task whose id
  was given in the -task parameter.

  In the case of the FrontEnd module, the value passed via -txt is a pointer 
  to a per-task data structure. 

  The FrontEnd module creates a Wimp window associated with the newly created 
  task, and then all is driven by Wimp events:

     - on receipt of a TaskWindow_Ego message, store the child task's id.
       The handle in this message points to our per-task data structure,
       where we store the id.

     - on receipt of a TaskWindow_Output message, the contents of the message
       are appended to a buffer, and displayed in the task's window.

     - on receipt of a TaskWindow_Morio message, set the title bar of the 
       task's window to "Completed".

     - if user clicks on Pause, send a TaskWindow_Suspend to the Child.

     - if user clicks on Continue, send a TaskWindow_Resume to the Child.

     - if user aborts the task send a TaskWindow_Morite to the Child.



   Edit
   ----

      Edit's use of the TaskWindow module is similar to that of FrontEnd's,
except that it must respond to external requests for taskwindows, and it 
must handle keyboard input to the Child task. 

      When the user clicks on "Create=>Task window", Edit issues a:
         *ShellCLI_Task &<Edit's-task-id> &<unique-Edit-handle>
      This command is identical to *TaskWindow -txt &<unique-Edit-handle>
      -task &<Edit's-task-id>.  New applications should NOT use
      ShellCLI_Task since its functionality has been replaced and enlarged
      by *TaskWindow.

      When the TaskWindow module receives a *TaskWindow command without 
valid -txt and -task parameters, it broadcasts a TaskWindow_NewTask message.  
Edit responds to such a message by merely SWI Wimp_StartTask'ing the command 
which arrives in the message, having first acknowledged the broadcast.

      Input typed by the user is sent via TaskWindow_Input messages, ie each
key press in the Edit task window is passed immediately to the Child.  Input 
from a selection is sent via the RAM transfer method described above.


