Acorn Nested Window Manager
Functional Specification

Document Status

Distribution:   General Release
Title:   Acorn Nested Window Manager Functional Specification
Drawing Number:   1215,401/FS
Issue:   2a
Author(s):   Various for original document, including:
  Piers Wombwell
  Kevin Bracey
  Later revisions for first formal specification:
  Ben Avison
  Andrew Hodgkinson
  Erik Groenhuis
Date:   08/02/2006
Change Number:   1
Last Issue:   2

Contents

  1. Document Status
  2. Issue History

  3. Overview
  4. Technical Background
  5. User Interface
    1. Child and Nested Windows
      1. Child Windows Without a Work Area
      2. Furniture Windows
    2. Windows in General
      1. Invalid Rectangle Handling
      2. Standard Window Furniture
      3. Minimum Sizes
      4. Shift-Toggle-Sized Windows
      5. Error Report Dialogue Boxes
    3. Icons
    4. Menus
    5. Icon Bar
    6. Panic Redraws
  6. Programmer's Interface
    1. Wimp_Initialise (&400C0)
    2. Wimp_CreateWindow (&400C1)
    3. Wimp_CreateIcon (&400C2)
    4. Wimp_OpenWindow (&400C5)
    5. Wimp_GetWindowState (&400CB)
    6. Wimp_GetWindowInfo (&400CC)
    7. Wimp_ForceRedraw (&400D1)
    8. Wimp_GetWindowOutline (&400E0)
    9. Wimp_RegisterFilter (&400F5)
      1. Rectangle Copy filter
      2. Get Rectangle filter
      3. Post Rectangle filter
      4. Post Icon filter
    10. Wimp_Extend (&400FB)
  7. References
Originally appearing as 1116,011/FS up to issue 3, this specification now has a document number of 1215,401/FS.

1116,011/FS (Developers and, by issue 2, general release)
1 06/02/98 Original Version (not released)
2 10/02/98 HTML version completed for publishing on the Web
3 16/02/98 Fixed up the HTML a bit, and in Wimp_CreateWindow the title foreground colour defaults to 7, not to 2
  23/02/98 Various HTML tweaks; no content change

1215,401/FS

(General release)
1 02/03/98 Document number now 1215,401/FS. Updated history, and navigation links in the page footer now include the specifications section; no other content changes
2 08/04/98 Added Wimp_RegisterFilter details. Some missing spaces added. Alphabetic components of the hex SWI numbers in body text capitalised. Added References section. Used <acronym> tag for acronyms.
2a 08/02/06 EG: Corrected description of R4 entry contents for Wimp_OpenWindow. The previous version suggested that the linkage flags should be put in R1+32, where they realy should be in R4.

Overview

Version 3.97 and 3.98 of the Wimp are beta versions, incorporating extensions required by numerous projects. The main features are:

Technical Background

This document documents changes to the Wimp over the version present in RISC OS 3.71, as determined from the PRM volumes 3 and 5a and the old Wimp itself.

The Wimp has been written so that any given version can be built to soft-load on any OS version back to 3.10. Builds of version 3.97 and version 3.98 suitable for RISC OS 3.1x, 3.5x, 3.6x and 3.7x have been released with beta status for external testing, because a nested Wimp is a prerequisite of the browser and Java. The main differences from the RISC OS 3.7x build in those for earlier operating systems are as follows:

In RISC OS 3.6x and earlier, the Wimp

In RISC OS 3.5x and earlier, the Wimp

In RISC OS 3.1x, the Wimp

User Interface


3.1 Child and Nested Windows

The single biggest enhancement to the Wimp is support for child windows: windows that are linked to and are only displayed within their parent. Each edge, and both scroll offsets of every child window are independently linked to the work area or one edge of the parent window, in whatever way suits the task. Thus, when a parent window is moved, scrolled or resized, any related changes to child windows are dealt with automatically by the Wimp.

Any window may have any number of children, and within each window there is a stack of child windows, whose relative depth can change in the same manner as the top-level window stack. Child windows may change their parent at any time, jumping between stacks. Child windows may themselves have nested children within them, which may in turn have their own children, and so on. Child windows are considered to lie above any icons in their parent window, and above the parent window's caret.

It should be noted that with all this added flexibility comes a potential for badly designed, non-intuitive application front-ends, so care must be taken when designing a user interface which uses the window nesting facilities.

3.1.1 Child Windows Without a Work Area
In the past, it has not been possible to display windows without a work area, for example to implement a scroll bar in a non-standard place. This was due not only to a hard-coded minimum size visible area (see Minimum Sizes) but also due to the ever-present single-pixel border drawn by the Wimp along any edge of a window that lacks window furniture. In fact, it has previously been possible to remove the single-pixel border, but at the expense of the removal of all the window furniture at the same time, leaving an isolated work area. These restrictions have been lifted.

This behaviour is in fact also available with top-level windows, but its usefulness is expected to be limited to child windows.

3.1.2 Furniture Windows
Normally, child windows are clipped according to the visible area of the parent window. However, there are occasions where it is desirable for the child windows to be clipped by the window outline - that is, allowing them to overlap the window furniture. This might, for example, be used to display status information within the scrollbars, or add window furniture buttons. An additional window flag has been introduced, allowing a child window to overlap the window furniture of its parent in this way.

Further, it is realised that to place such a furniture window at, for example, the bottom left of a window, would obscure the parent's scroll arrow icon. In order to compensate for this, scrollbars are allowed to move to accommodate any child window found to be touching both the outside edge of the scrollbar, and the end of the scrollbar. A window is deemed to be touching the end of the scrollbar if its end outline coordinate is within 1 pixel of the end of the scrollbar, i.e. there must be no gap between the child window outline and the final pixel of the scrollbar. The end of the scrollbar is adjusted so that it just underlaps the other end of the child window outline. The child window should normally be wide enough to cover all the area where the scroll bar would have been, as only a blank area of colour will be drawn there otherwise.

Notice that these constraints allow for four furniture windows within the scrollbars of the parent. If, for example, the developer wanted two child windows in the bottom left, one window would have to be made a child of the other. Under current Wimp behaviour, if two sibling child windows are placed side by side in this manner, the scrollbar will move to accommodate both of them, but only if they are in a certain stacking order; this behaviour is not guaranteed in future versions of the Wimp, and must not be relied upon.

Again, the flexibility offered by these child windows must not be abused: developers must, for example, take steps to ensure that the parent's minimum visible area is large enough for the furniture window never to overlap the parent's adjust size button.

Furniture windows which are independently moveable and/or resizable are beyond the scope of the Nested Window Manager, and any attempt to give them such abilities will result in unpredictable behaviour. Such designs are thus strongly discouraged.

3.2 Windows in General


3.2.1 Invalid Rectangle Handling
The way in which the Wimp calculates the invalid and block-copy rectangle lists is optimised over old Wimps, in order to increase the proportion of block-copy operations, which are usually much faster than redraws. This is done by compiling a list of changes between each call to Wimp_Poll, and only then calculating which rectangles are genuinely invalid, and which can be displayed using a quick block-copy operation. The block-copies themselves are re-ordered so that wherever possible, one copy does not invalidate screen area needed as source for another copy operation; in the rare cases where this is not possible, the least damaging alternative is chosen - that is, the one requiring the smallest invalid area to be redrawn.

The upshot of this is that wherever touching or overlapping windows move together - external and internal panes, and of course, nested windows - the shuffling effect present in earlier Window Managers, where an area is alternately covered by the top window, and exposed and redrawn, is eliminated. There is also some speed gain from combining block-copy operations. In the unusual event that the window opening queue needs to be flushed before the Wimp_Poll, an extension to Wimp_OpenWindow is provided.

3.2.2 Standard Window Furniture
All window furniture buttons slab in, including close and toggle size.

The bug regarding slabbing-in of the other furniture buttons, which could be unreliable following a Service_InvalidateCache, is fixed.

Single-pixel borders can be removed from windows without removing all the other window furniture at the same time.

For large work area windows, when the scroll sliders start being dragged, they jump less than in previous Wimps, and are displayed more accurately when they reach the end of the document.

A plain-colour background is no longer drawn underneath the solid toolsprites, thereby reducing flicker.

3.2.3 Minimum Sizes
All windows are optionally shrinkable to zero size visible area (subject to the continued visibility of any back, close, toggle size and adjust size buttons). In order to achieve this, scroll bars no longer have a minimum length (except in special cases). After the scroll slider region has been shrunk to zero length, the scroll arrows start to be plotted scaled down until the entire bar shrinks to nothing.

Most conventional programs which rely upon the old behaviour continue to function as before, due to the special-case exemptions in Wimp_CreateWindow.

3.2.4 Shift-Toggle-Sized Windows
Windows which have been toggle-sized with Shift held down (i.e. made to fill all the screen except the icon bar) are now internally marked as being full size, and the toggle-size button indicates this by switching to the "fulled" sprite. A further click on the toggle size button will then reduce the window's size to its original size, as opposed to the previous, unhelpful behaviour, which was to enlarge the window to full screen, including covering the icon bar!
3.2.5. Error Report Dialogue Boxes
Since each error button in a Wimp error box can contain user-defined text, it is possible for the text to be wider than the fixed width action buttons used in previous Wimps' error boxes. The Wimp now enlarges each action button if the width of its text (plus 36 OS units to allow for borders) is greater than that of its standard action button.

3.3 Icons

A number of long-standing bugs relating to "3-D" icons are fixed: clicking on an action button that uses an antialiased font doesn't reset the Wimp font to the old bitmap system font; multiple selection of action buttons via dragging off one button and Adjust-clicking on another is no longer possible; menu clicks on action buttons no longer cause a flicker; and the 3-D plinths are drawn correctly in EX0 and/or EY0 screen modes and/or when not pixel-aligned. Icon foregrounds and backgrounds can be drawn using any 24-bit specified colour, not just one one of the Wimp colours.

Any 2-, 4-, 16- or 256-colour sprites with palettes within icons are now plotted using the palette directly, rather than via a translation table. The effect of this is better colour reproduction of such sprites in 32 thousand colour and 16 million colour modes.

Line spacing for multi-line text icons, first specified for RISC OS 3.10, via the parameters to the "L" command of an icon's validation string, has finally been implemented.

3.4 Menus

Submenus and dialogue boxes opened from "reversed menus" are opened at the correct horizontal position again. However, the automatically-opened position still does not perfectly mirror normal menus for cases where the pointer is held over the "tick" space opposite the arrow.

3.5 Icon Bar

The icon bar scrolls at a rate independent of processor speed or loading - the position is determined according to the time elapsed since scrolling started, irrespective of how many screen updates have been possible since.

Also, the speed of scrolling increases linearly over time; it accelerates. This eases navigation of very wide icon bars.

If the pointer is left over the bottom pixel row of the screen for 0.5 seconds, the icon bar now pops to the top of the window stack, much as it would if you had used the Shift-F12 hotkey. The icon bar remains at the top of the stack (and therefore accessible) while the pointer stays over the icon bar and/or there is an icon bar menu open. When this condition is no longer true, the icon bar returns to its original position in the window stack (note that this differs from Shift-F12 behaviour, where the icon bar always becomes a "back" object again).

3.6 Panic Redraws

When a panic redraw occurs due to there being too many invalid rectangles for the Wimp to handle, the first thing drawn is a plain background. In a feature dating back to Arthur, this was hard-coded to Wimp colour 15 (now light blue) - hardly appropriate. This is changed to a mid-grey colour.

Also, anticipating the increased number of invalid rectangles made likely by the nested windows system, the number of invalid rectangles allowed before a panic redraw is triggered is raised from 128 to 256.

Programmer's interface

Wimp_Initialise (&400C0)

Wimp_Initialise recognises a new version number, in addition to the established 200, 300 and 310 versions. 380 will, at a sufficiently advanced version of the Wimp, be necessary in order to activate most of the features described in this specification. As of Wimp version 3.97, only the window foreground colour byte of the window block is affected by the version passed to Wimp_Initialise, but this must not be relied upon for future releases of the Wimp; other Nested-Wimp features may in future become reliant upon having passed 380.

Wimp_CreateWindow (&400C1)

The meanings of certain parts of the window block are altered and extended as follows:

On entry

R1 + 28 =
window
flags:


bit


meaning if set
  22  This bit is overwritten by the Wimp, and may be read using Wimp_GetWindowState. When set, it indicates that the window is, or will be, toggled to full size without covering the icon bar. Note that this behaviour is different to bit 18, which is set if the window is, or has been, toggled to full size including the icon bar.

Toggling behaviour can only be properly resolved after Wimp_Poll returns an Open_Window_Request reason code and before the subsequent call to Wimp_OpenWindow. Flags bit 19 is set, by definition; applications may distinguish between different types of toggle-size clicks using the following truth table:

OperationBit 22Bit 21Bit 18
To full size010
From full size001
To semi-full size110
From semi-full size000

These are the only values that can be returned in combination with bit 19 being set.

  23  If this is a child window, make it a furniture window. (This has no meaning for top-level windows, so the bit should always be cleared in such cases to allow for future expansion).
R1 + 32 = Title foreground and window frame colour:
  &FF Window has no 1-pixel border components, but furniture can still be present (as controlled by the usual flag bits). Title foreground colour defaults to Style Guide standard colour (Wimp colour 7).
R1 + 68 = Minium width of window (16 bits).

This used to be the minimum visible width in OS units, unless a greater width was required by either of the following:

  1. The top edge furniture - any combination of the back, close, title and (as a special case when the vertical scrollbar is absent) the toggle-size icons. The width required by the title icon was defined as 8 OS units, except when 0 was used here, indicating that the full width of the title text or sprite will apply;

  2. The bottom edge furniture - the minimum (unsquashed) size horizontal scrollbar (if present), plus any adjust-size button (in the special case when the vertical scrollbar is absent).
The 0 special case retains exactly the same behaviour as before (horizontal scroll bars, if present, cannot be squashed below a certain minimum width). Any other values activate the new behaviour: a horizontal scrollbar can be squashed down to zero width, and the title bar can be squashed down to zero width as long as the back and close buttons are both absent (otherwise, 8 OS units remains the minimum title icon width). A new special case, 1, is introduced, activating the new behaviour, but with an actual minimum window width of 0 rather than 1 (although it is obviously still subject to any non-squashable furniture width requirements as discussed).
R1 + 70 = Minium height of window (16 bits).

This used to be the minimum visible height in OS units, unless a greater height was required by a minimum (unsquashed) size vertical scrollbar, plus any toggle-size and adjust-size buttons (in the special cases where there is no title or horizontal scrollbar, respectively). It was also subject to a restraint that the minimum height could not be less than 2 pixels high when the vertical scrollbar was absent.

The value 0 becomes a special case, and retains exactly the same behaviour as before. That is, the vertical scroll bar, if present, cannot be squashed down below a certain size. All other values activate the new behaviour: any vertical scrollbar may be squashed down to zero height, and the 2-pixel hard-minimum no longer applies. A special case, 1, is introduced, activating the new behaviour but with a minimum window height of zero rather than of 1 (subject to constraints imposed by window furniture as described).

On exit
Unchanged
Interrupts
Unchanged
Re-entrancy
Unchanged

Wimp_CreateIcon (&400C2)

The (C)olour validation string command is introduced to allow icon colours to be set from a 24-bit palette. It is typically followed by two hexadecimal numbers (BBGGRR) separated by a /, but either one may be omitted, and the relevant colour from the icon flags (or the F command) will then be used instead. It is suggested that the old-style colours should be specified to something sensible, in case the program gets run on a Window Manager that doesn't support the command.

Examples:

Validation Colours produced
C008000/0080FF Mid green foreground, orange background    
CFF00FF Magenta foreground, background as specified in flags word   F
C/00FFFF Foreground as specified in the flags word, yellow background F  

Note also that the line spacing specified after the (L)ine spacing command is now acted upon.

Bit 20 of the icon flags has not been part of the ESG number since at least RISC OS 3.10, and should be considered 'reserved'.

Wimp_OpenWindow (&400C5)

This call is the key to the nested window system. Changes are as follows:

On entry

R1 Pointer to block, or NULL (0 or -1) to flush all pending opens to the screen.
R2 "TASK" (&4B534154)

This is a 'magic word' to tell Wimp that the extended version of this SWI call is being made.

In the extended call, R3 and R4 are as described below. Otherwise, the previous parent and flags (if any) are reused. The parent defaults to -1 and the flags default to 0, i.e. traditional Wimp behaviour is still the default.

It is important to ensure that R2 does not accidentally get left with this value from a previous call in code which mixes old and new style calls. This is mostly an issue for C SWI veneers.

R3 Handle of window to make parent (or -1 to make a top-level window)
R4 = flags
  bit meaning if set
  0 Use extended OpenWindow block in R1 (R1 + 32 = window flags).
  1-15 Reserved (0)
  16-27 Linkage flags.

If R3 is -1, bits 16-27 must all be clear. Otherwise, they specify how certain aspects of the child are aligned with the parent window:

Bit pairInfluences
bits 16, 17 left edge of child
bits 18, 19 bottom edge of child
bits 20, 21 right edge of child
bits 22, 23 top edge of child
bits 24, 25 x-scroll of child
bits 26, 27 y-scroll of child

These flag pairs have the following meanings (as high bit, low bit):

SettingAction
00 linked to work area of parent
01 linked to left / bottom of visible area of parent
10 linked to right / top of visible area of parent
11 reserved

  28-31 Reserved (0)
On exit
Values at R1+4 - R1+24 are updated to represent the actual parameters of the opened window after valid ranges have been taken into account, and the window has been forced on-screen (if applicable).
Interrupts
Unchanged
Re-entrancy
Unchanged
Use / other notes
If R4 bit 0 is set, then R1 + 32 holds the new window flags to use. This can be used, for example, to add or remove window furniture without having to delete and re-create the window.

Not all window flags can be altered in this way. In particular, bits 16-22 can only be set or cleared by the Wimp, in order to reflect the window status. The Wimp will also modify the bits relating to the window furniture as follows: if bit 31 is unset (indicating the old-style bits are to be used) then bits 24-30 are updated to reflect the status indicated by bits 0, 2, 3 and 7 (but note that bit 31 itself is left unchanged). If bit 31 is set, however, bits 0, 2, 3 and 7 are cleared. All other bits are preserved (and acted upon) by the Wimp.

Under previous Wimps, the window handle at R1+0 had to be owned by the task calling Wimp_OpenWindow. Because a child window need not belong to the same task as its parent, this restriction has now been lifted; this is the case even for the non-extended form (R2 not equal to the magic word "TASK").

Since RISC OS 2 (and possibly even earlier), Wimp_OpenWindow has had undocumented return conditions: values at R1+4 - R1+24 are updated to represent the actual parameters of the opened window after valid ranges have been taken into account, and the window has been forced on-screen (if applicable). Rather than continue to have programs waste time following a Wimp_OpenWindow with a Wimp_GetWindowState (except in cases where the new window flags are required), the exit conditions can now be considered official.

Wimp_GetWindowState (&400Cb)

This call mirrors Wimp_OpenWindow. If R2 = "TASK" on entry, then on exit R3 and R4 are as described above. Note however that Wimp_GetWindowState has always returned the window flags in R1+32, but despite this, R4 bit 0 will always be returned cleared.

Wimp_GetWindowInfo (&400CC)

The returned window block's extended meanings are as for Wimp_CreateWindow.

Wimp_ForceRedraw (&400D1)

Wimp_ForceRedraw is changed so that it can be applied to windows owned by other tasks, because a child window may belong to another task.

In the past, redrawing the title bar of a window has been accomplished either by working out where the window's title bar is on the screen and calling Wimp_ForceRedraw with R0=-1 to invalidate that area, or alternatively by toggling the input focus in and out of the window to force its borders to be redrawn.

Neither of these methods is particularly satisfactory: the first could cause other windows on top of the one in question to be redrawn unnecessarily, and the second redraws the rest of the borders as well, and in the case of child windows, would also cause a redraw of the parent's title bar.

So Wimp_ForceRedraw is extended as follows:

On entry

R0 Window handle (as before)
R1 "TASK" (&4B534154)

This signals that the extended version of Wimp_ForceRedraw is being used, and R2-R4 are as stated below.

R2 +3

Redraw title bar.

Other values are reserved.

R3, R4 Ignored.
On exit
Unchanged
Interrupts
Unchanged
Re-entrancy
Unchanged
Notes
Since the value &4B534154 ("TASK") is far too big to be an minimum x coordinate, it is safe to use as described above.

Wimp_GetWindowOutline (&400E0)

Previously, a window had to be open and visible on screen for this call to work. It will now work on windows which are closed or not yet visible.

Wimp_RegisterFilter (&400F5)

Each type of filter may only be registered once using this call, and so it remains for the use of the Filter Manager only (which will normally be responsible for delegating filter calls for specific tasks) unless you want to replace the whole filter system. The SWI is thus, in effect, only really for internal use but since it is documented in the PRMs the extended version is included here for completion.

As far as the Filter Manager is concerned, note that certain filter types require a newer Filter Manager than present in the RISC OS 3.60 / RISC OS 3.71 ROMs.

There are two new reason codes that may be passed to Wimp_RegisterFilter:

On entry

R1 = reason code: Code Meaning
  Register / deregister post-rectangle filter
  Register / deregister post-icon filter
On exit
Unchanged
Interrupts
Unchanged
Re-entrancy
Unchanged
Notes
There is an undocumented entry condition for any registered pre-filter: R3 points to the poll word if R0 bit 22 was set on entry to Wimp_Poll. On exit, R1 and R3-R10 must be preserved. The PRMs have also forgotten to mention that on entry to the post-filter, R12 holds the value given in R2 when the routine was registered. On exit, R1 and R3-R10 must be preserved. Future documentation will include this information.

The Wimp now calls the post-filter, with a null reason code, whenever Wimp_StartTask returns, even if the child task didn't call Wimp_Poll. In either case, any attempt to claim the null event will now be ignored.

The entry and exit conditions for reason code 2 and 3 filters have not previously been documented, and those for reason codes 4 and 5 are new in Wimp version 3.86, so here they are in numerical order by reason code:

Filter type Details
Rectangle Copy The rectangle copy filter is called when the Wimp is about to copy a rectangle across the screen, not exclusively due to Wimp_BlockCopy. The current and previous graphics cursor positions are describing the area to be copied, ready for the VDU block copy operation, but the actual operation has not yet been performed.
On entry

R2-R5  Destination bounding box
(min x, min y, max x, max y)
R6-R9  Source bounding box
(min x, min y, max x, max y)
R10  Window handle, minus one
(only in Nested Wimp variants from v3.90 onwards)
R12  Value of R2 when registered

SVC mode, interrupts enabled.

On exit
R0, R1 and R3-R10 must be preserved.
Get Rectangle The get rectangle filter is called just before the redrawing of a rectangle begins, before the window background has been filled (if appropriate), and even before the VDU graphics window has been set up. This filter is no longer called when it is only the caret which is being redrawn; the new rectangle filters below never have been.
On entry

R2 Task handle
R6-R9 Rectangle to be redrawn
(min x, min y, max x, max y)
R12 Value of R2 when registered

SVC mode, interrupts enabled. Note that R10 is undefined (this may change to match the other rectangle filters, but don't rely on it).

On exit
R0, R1 and R3-R10 must be preserved.
Post-rectangle The post-rectangle filter is called after the window background is filled as part of a rectangle redraw, i.e. shortly before Wimp_GetRectangle or Wimp_RedrawWindow (or their internal equivalents) reset the VDU state and return, unless the call is returning with "no more to do" status. The filter is linked to the filling-in of the window background; redraw loops initiated by Wimp_UpdateWindow never cause this filter to be called, because they do not cause the window background to be redrawn. However, the filter is called after a "transparent" window background would have been filled.
On entry

R2 Task handle
R6-R9 Rectangle to be redrawn
(min x, min y, max x, max y)
R10 Window handle, minus one
R12 Value of R2 when registered

SVC mode, interrupts enabled.

On exit
R0, R1 and R3-R10 must be preserved.
Post-icon In the past, the rectangle redraw cycle has consisted of the Wimp filling the background and returning control to the application, which then draws whatever it wants and calls Wimp_GetRectangle. The Wimp subsequently draws the icons before moving on to the next rectangle and filling its background, and so on. This did mean that applications never got a chance to draw on top of the icons; the post-icon filter now allows them to.
On entry

R2 Task handle
R6-R9 Rectangle to be redrawn
(min x, min y, max x, max y)
R10 Window handle, minus one
R12 Value of R2 when registered

SVC mode, interrupts enabled.

On exit
R0, R1 and R3-R10 must be preserved.

All bounding boxes (R6-R9 values on entry) are in screen coordinates.

Wimp_Extend (&400FB)

It is possible to enumerate window stacks using only Wimp_GetWindowState, but it requires that you open a "special" window of your own at the back of each stack to be enumerated, and you can only enumerate the stack from back to front. It may also return rather more information that you actually need, and so may be a little bit slower than it might be.

Consequently, five new index values are added to Wimp_Extend. For each of the following, R1 holds the window handle being queried, or a value of -1 to enquire about the top-level stack (for index values 7 and 8 only).

On entry

R0 Reason code (see exit conditions for R1)
R1 Window handle, or for reason codes in R0 of 7 and 8, a value of -1 to enquire about the top-level stack.
On exit

R1 The value of R1 depends on the reason code and R1 value supplied on entry:

Reason code in R0 Meaning of R1 on exit
0 - 5 Internal use only
6 Parent window
7 Frontmost child window
8 Backmost child window
9 Sibling immediately behind
10 Sibling immediately in front

Interrupts
Undefined
Re-entrancy
Undefined
Use
Any of the above calls can return R1 = -1 for "no window", indicating that the end of the stack was reached, or the window had no parent or child, or R1 was -1 on entry and R0 was not 7 or 8.

Note also that pane windows are not skipped by any of the above calls.

References

The following references may be of interest:
The Filter Manager
PRM Volume 3, section 56, pp. 303-312 and erratum, Volume 5a, page 668.
The Window Manager: Wimp_RegisterFilter
PRM Volume 3, section 53, pp. 224-225
Acorn Filter Manager v0.18: Functional Specification
Document reference 1215,102/FS.
Last updated 16 Februari 2006
© Acorn Computers Limited, 1997
Valid HTML 4.0 Transitional