Acorn Nested Window Manager
|Title:||Acorn Nested Window Manager Functional Specification|
|Author(s):||Various for original document, including:|
|Later revisions for first formal specification:|
|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|
|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
in body text capitalised. Added References section. Used
|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.|
Version 3.97 and 3.98 of the Wimp are beta versions, incorporating extensions required by numerous projects. The main features are:
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
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.
This behaviour is in fact also available with top-level windows, but its usefulness is expected to be limited to child windows.
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.
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.
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.
Most conventional programs which rely upon the old behaviour continue to function as before, due to the special-case exemptions in Wimp_CreateWindow.
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.
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.
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).
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.
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.
The meanings of certain parts of the window block are altered and extended as follows:
|R1 + 28 =
meaning if set
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:
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:
|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).
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.
||Mid green foreground, orange background|
||Magenta foreground, background as specified in flags word||F|
||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'.
This call is the key to the nested window system. Changes are as follows:
|R1||Pointer to block, or NULL (0 or -1) to flush all pending opens to the screen.|
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)|
|bit||meaning if set|
|0||Use extended OpenWindow block in R1 (R1 + 32 = window 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:
These flag pairs have the following meanings (as high bit, low bit):
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.
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.
The returned window block's extended meanings are as for Wimp_CreateWindow.
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:
|R0||Window handle (as before)|
This signals that the extended version of Wimp_ForceRedraw is being used, and R2-R4 are as stated below.
Redraw title bar.
Other values are reserved.
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.
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:
|R1 = reason code:||Code||Meaning|
|4||Register / deregister post-rectangle filter|
|5||Register / deregister post-icon filter|
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:
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
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.
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.
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.
All bounding boxes (R6-R9 values on entry) are in screen coordinates.
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).
|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.|
The value of R1 depends on the reason code and R1 value supplied on entry:
Note also that pane windows are not skipped by any of the above calls.
Last updated 16 Februari 2006
© Acorn Computers Limited, 1997