User:Erik G/Sandbox 1
The Taskwindow module is intended to allow programs which do not call SWI Wimp_Poll to be pre-emptively scheduled in the RISC OS desktop. -- PRM TaskWindow: Introduction and Overview
Most RISC OS users will know this from the interactive window they use to type CLI commands in. It also has a mode where a user task can directly process all output of the target program, and send input to it if required.
Terminology
For the purpose of this article, the following definitions are used:
- Child
- The task created by the TaskWindow module which runs the target program and sends the output of the target to the Parent using messages.
- Parent
- The task which communicates with the Child through messages and processes and/or displays the output of the Child.
- Server
- An application which can act as a Parent on behalf of the Source.
- Source
- The task that issues a TaskWindow command. In Direct mode this is the same as the Parent.
- Target
- The program which does not call Wimp_Poll. Running this is the whole purpose of the TaskWindow system. The Target is specified in the <command> parameter of the TaskWindow command.
Server mode
In this mode the source task issuing the TaskWindow command lets a server application (usually the default text editor) act as the Parent. This takes all of the hard work (handling messages, opening and redrawing a window with text, etc.) out of the hands of the Source task, making it easy for a user application to start a Target program and show its results.
This server will display the output of the target and accept the keyboard input and send it to the target.
/-------------\ Wimp_StartTask
| SOURCE | TaskWindow "target" ...
| User |----------------------\
| Application | |
\-------------/ |
|
|
TaskWindow_NewTask |
(broadcast) | run
__________________ | _____________
/ \ | / \
v | v | v
/------------------\ /-------------\ /-------------\
| | | | | |
| PARENT | messages | CHILD | stdin | TARGET |
| TaskWindow Server|<==========>| TaskWindow |----------->| cli-program |
| (usualy editor) | | module task | stdout | |
| | | |<-----------| |
\------------------/ \-------------/ \-------------/
/\
||
\/
+-------------++
+-------------++
| ||
| Text ||
| window ||
| ||
| ||
| ||
| ||
+-------------++
Though the internal handling of this mode is more complicated than Direct mode, it is very much simpler from the point of view of the Source task. After issuing the TaskWindow command it does not have to do anything.
Internal handling
what happens when TaskWindow command is issued
- User task issues command.
- TW module handles command.
- Module broadcasts a TaskWindow_NewTask message
- Editor that wants to act as a server acknowledges the broadcast, thus intercepting it
- If no server acks the broadcast, TaskWindow$Server is examined. If exists is used to start server (probably complete with parameter to make server issue TW command).
- Server issues a new TaskWindow command, adding -task and -txt options
- Henceforth, Server operates as Parent in Direct mode.
- Only way for the Source to find out if Target is still going is by listening for Message_TaskCloseDown broadcast with task handle equal to return value of the original Wimp_StartTask call.
Direct mode
In this mode the source task issuing the TaskWindow command (which could be a user application) acts as the Parent and should handle messages from and to the Child itself.
Wimp_StartTask
TaskWindow "target" -task ... run
__________________ _____________
/ \ / \
| v | v
/------------------\ /-------------\ /-------------\
| | | | | |
| PARENT | messages | CHILD | stdin | TARGET |
| User application |<==========>| TaskWindow |----------->| cli-program |
| | | module task | stdout | |
| | | |<-----------| |
\------------------/ \-------------/ \-------------/
Direct mode is entered by issuing the TaskWindow command with the -task option:
TaskWindow <command> [<other options>] -task &xxxxxxxx [-txt &yyyyyyyy]
Parameters
Detailed description of the TaskWindow command parameters
Syntax:
TaskWindow [command] [[-wimpslot] nK] [[-name] taskname] [-ctrl]
[-display] [-quit] [-task &xxxxxxxx] [-txt &xxxxxxxx]
- Can only be issued from a Task. Must use Wimp_StartTask SWI to issue the command.
- Fields which have spaces must be enclosed in double quotes
Command
Wimpslot
Name
Ctrl
Display
Quit
Task
Txt
Messages
Detailed description of the TaskWindow messages and when and how they are used
Using Direct mode
How to set up your application as a direct mode parent
- Allow User Messages 17. Types 18 and 19 can be ignored, unless RAM Transfer protocol is used.
- Have handlers available for TW_Ego, TW_Output, TW_Morio
- Install TW_Ego handler
- Invent -txt parameter
- Construct and issue TaskWindow command
- When TW_Ego message comes, check -txt value. If known note task handle of child and install TW_Output and TW_Morio handlers
- Handle TW_Output: Fill buffer with the data (or process immediately). If room left in buffer is less than (256-24) bytes, then send TW_Suspend.
- Handle TW_Morio: Child has terminated. If no output data left, clean up. If some output data left, process data and remember to clean up after all data processed.
- When enough data is processed so there is room in output buffer again, sent TW_Resume.
- On user action, or based on output, child can be terminated by sending TW_Morite. This will cause a TW_Morio, which should be used to clean up in the normal way.
- User action can also be reason for TW_Suspend/TW_Resume
- Sending input only makes sense if client expects it. Usually after prompt. Parent must recognise prompt and compose input data. Send with TW_Input. (Mention RAM transfer protocol.)
Your editor as a server
What to do to make the editor you are building operate as a TaskWindow server
