home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / documentation / documents / a252task < prev    next >
Internet Message Format  |  1999-04-27  |  7KB
  1. From: IJohnson@acorn.co.uk
  2. Subject: Re: taskwindow
  3. Date: 18 Sep 91 14:27:04 GMT
  4.  
  5.  
  6.    The following is the Wimp message protocol as used by the Task Window
  7. module (0.29) supplied with Desktop C, and Desktop Assembler.  Note that 
  8. the module only provides pre-emptive scheduling for tasks running under 
  9. its control; a Wimp application (like Edit) is required to display output 
  10. produced by such a task (ie despite the name of the module, it 
  11. doesn't give you a Wimp window!).
  12.  
  13. Terminology:     Parent == a task which has created a child using
  14.                            the *TaskWindow or *ShellCLI_Task command.
  15.  
  16.                  Child == a task created by a *TaskWindow or *ShellCLI_Task
  17.                           command, and hence being pre-emptively scheduled by 
  18.                           the task window module.
  19.  
  20.                  Edit == the RISC OS text editors (both !Edit and !SrcEdit).
  21.  
  22.                  FrontEnd == the FrontEnd module supplied with Desktop C and 
  23.                              Desktop Assembler.
  24.  
  25.  
  26.  
  27.  
  28.   Message number:  TaskWindow_Input  (0x808c0)
  29.  
  30.   Purpose:         Used to send input data from Parent to Child.
  31.  
  32.   Data:            R1+20     size of input data
  33.                    R1+24     pointer to input data 
  34.  
  35.                    Note:  input can also be sent via a normal RAM
  36.                    transfer protocol, ie send a Wimp_MDATASAVE, and
  37.                    then wait for wimp_MRAMFETCH's and send back 
  38.                    wimp_MRAMTRANSMIT's when you get them (see PRM).
  39.  
  40.  
  41.  
  42.   Message number:  TaskWindow_Output (0x808c1)
  43.  
  44.   Purpose:         Sent to the Parent when one of its children has produced
  45.                    output.
  46.  
  47.   Data:            R1+20     size of output data
  48.                    R1+24 ... output data 
  49.  
  50.  
  51.  
  52.   Message number:  TaskWindow_Ego (0x808c2)
  53.  
  54.   Purpose:         Sent to Parent, to inform him of the Child's task-id.
  55.  
  56.   Data:            R1+4      Child's task-id (as filled in by Wimp)
  57.                    R1+20     Parent's txt-handle (as passed to *TaskWindow
  58.                              or *ShellCLI_Task). 
  59.  
  60.                              Note: this is the only time the txt-handle is 
  61.                              used.  It allows the Parent to identify which 
  62.                              Child is announcing its task-id.
  63.                              
  64.  
  65.  
  66.   Message number:  TaskWindow_Morio (0x808c3)
  67.  
  68.   Purpose:         Sent to Parent when Child exits.
  69.  
  70.   Data:            none  (all necessary info is in wimp message hdr).
  71.  
  72.  
  73.  
  74.   Message number:  TaskWindow_Morite (0x808c4)
  75.  
  76.   Purpose:         Sent by Parent to kill Child.
  77.  
  78.   Data:            none  (all necessary info is in wimp message hdr).
  79.  
  80.  
  81.  
  82.   Message number:  TaskWindow_NewTask (0x808c5)
  83.  
  84.   Purpose:         Broadcast by external task which requires an 
  85.                    application (eg Edit) to start up a task window.  
  86.                    If the receiving application wishes to deal with this 
  87.                    request, it should first acknowledge the Wimp message,
  88.                    then issue a SWI Wimp_StartTask with R1+20... as the 
  89.                    command.
  90.  
  91.   Data:            R1+20 ...    the command to run.
  92.  
  93.  
  94.  
  95.   Message number:  TaskWindow_Suspend (0x808c6)
  96.  
  97.   Purpose:         Sent by Parent to suspend a Child.
  98.  
  99.   Data:            none  (all necessary info is in wimp message hdr).
  100.  
  101.  
  102.  
  103.   Message number:  TaskWindow_Resume (0x808c7)
  104.  
  105.   Purpose:         Sent by Parent to resume a suspended Child.
  106.  
  107.   Data:            none  (all necessary info is in wimp message hdr).
  108.  
  109.  
  110.  
  111.  
  112. Two examples of using the TaskWindow module
  113. -------------------------------------------
  114.  
  115.   There are (currently) two examples within Acorn of use of the TaskWindow
  116. module.  One is Edit and the other is the FrontEnd module.
  117.  
  118.  
  119.   FrontEnd
  120.   --------
  121.  
  122.   When the FrontEnd module runs a non-desktop program, it first issues a 
  123.   SWI Wimp_StartTask with a *TaskWindow command, something like:
  124.  
  125.      *TaskWindow -quit -wimpslot <n>K -name "<progname-and-parameters>" 
  126.                  -task &<frontend's-task-id> -txt &<unique-frontend-handle>
  127.  
  128.   The use of -quit indicates to the TaskWindow module to run the given 
  129.   task, and then exit immediately, rather than running a CLI.  This means
  130.   we get a TaskWindow_Morite message when the given command exits.
  131.  
  132.   The task-id passed via -task is used by the TaskWindow module to send you 
  133.   Wimp messages, and to check that you are the legitimate Parent of the 
  134.   Child (!)  The -txt parameter allows you to identify which child is 
  135.   being referred to, even before it has a Wimp task-id.  Note: normally on
  136.   receipt of a *TaskWindow command the TaskWindow module will broadcast a 
  137.   TaskWindow_NewTask message (since the requesting task may be different 
  138.   to the task who will do the display!);  however if -task and -txt are 
  139.   used, the TaskWindow module assumes the requesting and displaying tasks 
  140.   are the same (which is the case for the FrontEnd module), and immediately
  141.   starts up the given task, sending any output messages to the task whose id
  142.   was given in the -task parameter.
  143.  
  144.   In the case of the FrontEnd module, the value passed via -txt is a pointer 
  145.   to a per-task data structure. 
  146.  
  147.   The FrontEnd module creates a Wimp window associated with the newly created 
  148.   task, and then all is driven by Wimp events:
  149.  
  150.      - on receipt of a TaskWindow_Ego message, store the child task's id.
  151.        The handle in this message points to our per-task data structure,
  152.        where we store the id.
  153.  
  154.      - on receipt of a TaskWindow_Output message, the contents of the message
  155.        are appended to a buffer, and displayed in the task's window.
  156.  
  157.      - on receipt of a TaskWindow_Morio message, set the title bar of the 
  158.        task's window to "Completed".
  159.  
  160.      - if user clicks on Pause, send a TaskWindow_Suspend to the Child.
  161.  
  162.      - if user clicks on Continue, send a TaskWindow_Resume to the Child.
  163.  
  164.      - if user aborts the task send a TaskWindow_Morite to the Child.
  165.  
  166.  
  167.  
  168.    Edit
  169.    ----
  170.  
  171.       Edit's use of the TaskWindow module is similar to that of FrontEnd's,
  172. except that it must respond to external requests for taskwindows, and it 
  173. must handle keyboard input to the Child task. 
  174.  
  175.       When the user clicks on "Create=>Task window", Edit issues a:
  176.          *ShellCLI_Task &<Edit's-task-id> &<unique-Edit-handle>
  177.       This command is identical to *TaskWindow -txt &<unique-Edit-handle>
  178.       -task &<Edit's-task-id>.  New applications should NOT use
  179.       ShellCLI_Task since its functionality has been replaced and enlarged
  180.       by *TaskWindow.
  181.  
  182.       When the TaskWindow module receives a *TaskWindow command without 
  183. valid -txt and -task parameters, it broadcasts a TaskWindow_NewTask message.  
  184. Edit responds to such a message by merely SWI Wimp_StartTask'ing the command 
  185. which arrives in the message, having first acknowledged the broadcast.
  186.  
  187.       Input typed by the user is sent via TaskWindow_Input messages, ie each
  188. key press in the Edit task window is passed immediately to the Child.  Input 
  189. from a selection is sent via the RAM transfer method described above.
  190.  
  191.  
  192.