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.

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.

Source

The task that issues a TaskWindow command. In Direct mode this is the same as the Parent.

Server

An application which can act as a Parent on behalf of the Source.

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

Messages

Detailed description of the TaskWindow messages and when and how they are used

Your editor as a server

What to program to make the editor you are building operate as a TaskWindow server