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