> Wimp.Guidelines

Compatibility

Reserved fields must be set to 0
ie. reserved words must be 0, and all reserved bits unset.
All Wimp calls corrupt R0, whether or not R0 is to contain a result Other registers are preserved unless used to return results Flags are preserved unless V is set on exit
Unknown Wimp_Poll reason codes, messages etc. MUST BE IGNORED
Applications should check Wimp version number, and either adapt themselves if the Wimp is too old, or report an error to the current error handler (use OS_GenerateError)
Beware of giving errors if window handles are unrecognised
- they may belong to another task
- it is sometimes legal for their window handles to be returned to you (eg. Wimp_GetPointerInfo)
Wimp tasks which are modules must obey certain rules (see Wimp.Desktop for details)
New Wimp tasks that can receive Key_Pressed events MUST pass on all unrecognised keys to Wimp_ProcessKey (see Wimp.Text). Failure to do so will result in the 'hot key' facilities not working.

New Wimp checking

SWI calls in wrong context:
new Wimp disallows certain SWIs outside the context of Wimp_Initialise ... Wimp_CloseDown
"Bad pointer passed to Wimp in R1"
- this error is returned if R1 < &8000 when passed to one of a range of Wimp SWIs which expect R1 to point to a data block
The following SWIs can only operate on windows owned by the calling task, and will report the error 'Access to window denied' if an attempt is made to access another task's window:

                Wimp_CreateIcon     ; (except in icon bar)
                Wimp_DeleteWindow
                Wimp_DeleteIcon     ; (except in icon bar)
                Wimp_OpenWindow     ; send OpenWindowRequest instead
                Wimp_CloseWindow    ; send CloseWindowRequest instead
                Wimp_RedrawWindow
                Wimp_UpdateWindow
                Wimp_GetRectangle
                Wimp_SetExtent
                Wimp_BlockCopy

        Note that this also means that a task cannot access its own windows
        unless it is a 'foreground' process, ie. it has not gained control by
        means of an interrupt routine, or is inside its module Die entry, and
        is only active when the Wimp returns to it from Wimp_Poll.

Wimp_Initialise / Wimp_CloseDown

In order to maintain compatibility with the old single-tasking window system, new Wimp programs wishing to make use of the multi-tasking features of the window system must identify themselves to the window manager as follows:

        SWI Wimp_Initialise
        Entry:  R0 = latest known version of Wimp (200 = version 2.00)
                R1 = "TASK"
                R2 --> description of program (eg. 'Form Editor')
        Exit:   R0 = actual version number of Wimp (*100)
                R1 = task handle allocated to task

Note that R1 does not point at a string containing the word "TASK" - rather the four bytes of the register are the letters T, A, S, K (low-byte first).

When closing down, the application should pass in its task handle, in case the task is being closed down from within another task (eg. if the task is a module, it should call Wimp_CloseDown in its Die routine). It should do this as follows:

        SWI Wimp_CloseDown
        Entry:  R0 = task handle (R1 on exit from Wimp_Initialise)
                R1 = "TASK"

Setting R1 to "TASK" tells the Wimp that the task knows about the new features of the window system, and that it is prepared to be well-behaved, as described below. The version number passed in R0 to Wimp_Initialise is not currently used, but it will allow for future versions of the Wimp to get round any incompatibility issues that might occur.

The following is a summary of what the Wimp actually does when initialising a task:

Wimp 1.20 and earlier:

Wimp_Initialise

        Set up soft characters (&80..&8F)
        Set up *FX 4,2; *FX 219,&8A; *FX 221..228,2
        *Pointer

Wimp_CloseDown

        Reset *FX 4,2; *FX 219,&8A; *FX 221..228,2

Wimp 2.00 and later:

Wimp_Initialise:

        If first task:
          Set up soft characters (&80..&85,&8B..&8E)
          Set up *FX 4,2; *FX 219,&8A; *FX 221..228,2; *FX 229,1
          If R1 = "TASK" on entry: SWI Wimp_SetMode to most recent wimp mode
                                   (defaults to configured WimpMode)
          *Pointer
          If R1 = "TASK" on entry: return R1 = task handle on exit

Wimp_CloseDown

        If last task:
          Reset *FX 4,2; *FX 219,&8A; *FX 221..228,2; *FX 229,1
          MODE <configured mode>
          restore screen memory to configured amount

OS_Exit (or Wimp_Poll after Wimp_CloseDown)

        If R1<>"TASK" when Wimp_Init called,
          and not last task:
            MODE <configured mode>
            restore screen memory to configured amount
            Set up soft characters (&80..&85,&8B..&8E)
            Set up *FX 4,2; *FX 219,&8A; *FX 221..228,2; *FX 229,1

#### this last bit is not strictly true !!! ####

The last set of calls ensure that an old-style (or non-Wimp) task exitting does not mess up the state of the machine for the remaining tasks. In contrast, when a multi-tasking application quits, it is relied on by the Wimp not to have changed mode etc.

################################################

Compatibility:

Wimp ensures that the new Wimp_Poll reason codes are not returned to old tasks Any windows currently open are made invisible

a large window with bg colour 15 is opened to cover up the other windows
it has the 'backwindow' bit (bit 11) set, so windows can't get under it Menu clicks on the background are returned to the task
the window handle is returned as -1
when multi-tasking, menu clicks on the background are ignored None of the other tasks is called while the old-style task is running

When a new task is started, the Wimp enables escape condition generation using *FX 229,0. If/when the task subsequently calls Wimp_Initialise with R1

"TASK" (ie. it becomes a new-style task), escape condition generation will be disabled using *FX 229,1 (the escape key returns ascii code &1B instead). Thus old-style tasks will run with escape initially enabled by the Wimp (although they can change it themselves if they want), and so compatibility is maintained.

Note that multi-tasking programs must not call Wimp_Poll while they have escape condition generation enabled. If the task calls *FX 229,0 to enable escape conditions, it must call *FX 229,1 and *FX 124 (in that order) before calling Wimp_Poll again (*FX 124 acknowledges any pending escape condition).

When the task exits, and there are other tasks to run, the screen is reset to its original mode and any running tasks are restored.

Guidelines for new-style (multi-tasking) Wimp programs

Do not set mode/palette unless absolutely necessary

if you do, then use Wimp_SetMode and Wimp_SetPalette Try to survive in any mode (using icons should make this easy)

If possible, rely on the user having at least one 'application window' open for your task to get input through. When all application windows have been closed, the task should exit (& unload itself).

'Resident' programs, such as utilities, should get themselves an icon on the icon bar, using Wimp_CreateIcon with window handle -1. They should respond to MENU_click on the icon by bringing up a small menu with the following options available:

        About <util-name> =>            ; information window
        Quit                            ; kills the program

Any other options should go between these two. SELECT on the icon should cause an application window to be opened (or whatever is appropriate).

Do not open any immoveable windows! These can obscure other tasks' immoveable windows, or even the icon bar, and so are very undesirable. In general, pane windows or moveable 'option' windows are better.

Escape handling in the new system is handled by detecting the ascii 27 code being returned from read-character; escape condition generation has been disabled by using *FX 229,1. Thus an application can normally only detect escape if it owns the caret. If an applications wishes to perform some long operation without calling Wimp_Poll, then it can re-enable escape condition generation in order to be able to abort the operation, but it must be careful to restore escape condition state before calling Wimp_Poll again (it should also cancel any current escape condition, just to be on the safe side):

        SYS "OS_Byte",229,0,0 TO ,oldstate%     ; re-enable esc conditions
        ...
        <perform long-winded operation>
        ...
        SYS "OS_Byte",229,oldstate%,0           ; restore old state
        SYS "OS_Byte",124                       ; clear escape condition
        <return to Wimp_Poll>

Note that it is VERY IMPORTANT that the escape condition generation is disabled before calling Wimp_Poll, since the other Wimp tasks will not be expecting escape conditions to arise.