Redraw Manager Module API Specification

Rendering into Windows

In some instances it is necessary to have a complex graphic in a window which cannot be represented as text or a sprite and so requires an external source to redraw it. This is achieved via the Wimp’s Post-Rectangle Filters. The Filter Manager (version 0.13 and above) makes these filters available to other modules so that they can draw directly into a Wimp window. Filter Manager 0.15, in conjunction with version 3.86 of the Wimp also provides Post-Icon Filters.

Post-Rectangle filters are available in Window Manager modules 3.86 or later. On versions 3.16–3.85 of the Wimp, the Filter Manager will simulate the post-rectangle filter using the rectangle filter. (The original rectangle filter itself is not useful for this application because it is called for the window tools as well as window contents, and is also called before the Window Manager draws the window background).

Post-Icon filters are only are only available in Window Manager modules 3.86 or later; they are not simulated on older Window Managers.

Post-Rectangle and Post-Icon filters are quite low level and there are a number of complications when using them directly, so a new module, the Redraw Manager has been written. This enables a module to ‘register interest’ in a region of a wimp window and then be called back whenever this region has been invalidated. Note that Rectangle filters work even if the window is ‘auto-redraw’ and so the client does not need to know that the Gadget is being provided in this way.

When the callback is made, the module is told which part of the window is being updated and how this intersects with the region that was registered for. A data pointer is also passed back so that the module can access the required information for redrawing the region. As a result the call will be made separately for each region that is currently invalid that the module has registered an interest in.

The callback is made during a redraw loop (so Wimp_PlotIcon takes work area coordinates). Do not call Wimp_GetRectangle or Wimp_UpdateWindow in your callback routine. The order of actions for each rectangle being redrawn is:

1. The Filter Manager calls rectangle filters.
2. The Window Manager draws the window tools and the window background.
3. The Filter Manager calls post-rectangle filters, including the Redraw Manager.
4. The Redraw Manager calls ‘early’ callback routines for the areas of interest intersecting the rectangle being drawn.
5. The Window Manager sets the graphics foreground and background colours according to the window definition.
6. The application owning the window draws any contents in its redraw loop.
7. The Window Manager draws the icons.
8. The Filter Manager calls post-icon filters, including the Redraw Manager.
9. The Redraw Manager calls ‘late’ callback routines for the areas of interest intersecting the rectangle being drawn.

Thus anything your callback routine redraws will appear behind the rest of the window contents, unless you ask for a ‘late’ callback (bit 3 of R0 set in Redraw_AddCallBack), in which case what you draw will appear in front of the rest of the window contents. It is generally recommended that you do not use ‘late’ callbacks unless your application/gadget will only ever run on version 3.86 or later of the Wimp.

Notes:
Wimps prior to 3.86 have a bug which means that rectangle filters (and hence the simulated post-rectangle filters) are erroneously called when the caret moves. This can result in strange effects if, for example, a writable icon is placed in front of a graphic drawn via the Redraw Manager. This shouldn’t normally affect gadget authors, as gadgets shouldn’t normally overlap. A fix for this may be implemented in future releases of the Filter Manager.

When post-rectangle filters are being simulated on Wimps prior to 3.86, the Window Manager will set up graphics colours between stages 2 and 3 above as well as in step 5. This does not happen with Wimp 3.86 or later, so do not rely on this behaviour.

The RedrawManager has an API as follows:-

Service_RedrawManagerInstalled (Service Call &A5)

Entry:
   R0 =   Redraw Manager version * 100
   R1 =   &A5 (reason code)

Exit:   All registers preserved

This service call is issued when the Redraw Manager starts up. You may then register areas of interest using Redraw_AddCallBack.

Service_RedrawManagerDying (Service Call &A6)

Entry:
   R1 =   &A6 (reason code)

Exit:   All registers preserved

This service call is issued as a broadcast to inform Redraw Manager clients that they have been deregistered and that the Redraw Manager is about to die.

Redraw_AddCallBack (SWI &82C80)

Entry:
   R0 =   flags:
         bit 0 reserved
         bit 1 set -> set up graphics rectangle before making SWI
         bit 2 set -> return co-ordinates to callback in screen co-ordinates
         bit 3 set -> call after plotting icons, else before user contents
         bits 4–31 reserved
   R1 =   Wimp window handle
   R2 =   SWI to call out to
   R3 ->   bounding box of region (in work area coordinates)
   R4 =   data to associate with region

Exit:   All regs preserved

This SWI registers 'an interest' in a region of a window so that the module will be called whenever the region is updated. Setting bit 1 will ensure that a suitable graphics window will have been set up before the module is called (restricting output to within both the redraw rectangle and the area of interest). If bit 1 isn’t set the graphics window will be the whole redraw rectangle.

Setting bit 3 means that you will be called after the Wimp has plotted any icons in the window, so what you draw will appear on top of anything else. This behaviour is only available with version 3.86 or later of the Window Manager.

Redraw_RemoveCallBack (SWI &82C81)

Entry:   R0 =   flags (must match flags passed to Redraw_AddCallBack)
   R1 =   wimp window handle
   R2 =   SWI
   R3 ->   bounding box of region (in work area coordinates)
   R4 =   data to associate with region

Exit:   All regs preserved

This SWI deregisters 'an interest' in a region of a window. In order to deregister successfully, all the parameters must match in the way that the region was registered.

Callback handler

Entry:
   R0 =   flags:
         bit 0 set -> your region is entirely inside the area being updated
         bits 1–31 reserved
   R1 ->   bounding box of region being updated (in work area coordinates or screen
      coordinates depending on bit 2 of flags in call to Redraw_AddCallBack)
   R2 ->   'state' for this window (block as returned from Wimp_GetWindowState)
   R3 ->   bounding box of registered region (in work area coordinates)
   R4 =   data associated with region

Exit:   All registers preserved

The Redraw Manager calls a module when a region requires redrawing with the above registers set up.