Window stacks
=============

Overview
--------
When RISC OS 4 came out, the concept of 'foreground windows' was introduced.
These windows allow a separate stack of windows to be displayed which are
always in front of the 'normal' windows. These windows are similar in
principle to the 'furniture' windows provided by the Nested WindowManager
releases. With RISC OS 4, furniture windows become a particular case of
foreground windows when used within a nested window.

At the same time, the 'backwindow' bit was updated to allow windows to
appear behind 'normal' windows in a similar manner. Select 3 completes this
background window work by creating a backwindow stack to complement the
foreground window stack.

Window flags
------------
The type of window stack within which the window is placed is determined by
the window flags:

  Bit 11  Bit 23
  (back)  (fore)
  
    0       0      Normal window
    0       1      Foreground or furniture window
    1       0      Background window
    1       1      Undefined, should not be used


Moving windows
--------------
Windows will move when dragged by the user or when positioned explicitly by
program code. There are four classes of position which the window may be
placed at - front, back, hidden, arbitrary position - indicated by the
'behind' value (window block + 24) value.
 
 Front
 -----
Placing a window at the front is achieved by using the 'behind' value of -1.
This will move the window to be the foremost of the window stack it is
declared in, obscuring all other windows in the stack. This operation is
performed when the user drags the title or resize icons of a window with
Select pressed.

 Back
 ----
Placing a window at the back is achieved by using the 'behind' value of -2.
This will move the window to be the rearmost of the window stack it is
declared in, behind all other windows in the stack. This operation is
performed when the user presses the 'back' icon of a window.

 Hidden
 ------
'Hiding' a window is achieved by using the 'behind' value of -3. This
ensures that the window will not be visible to the user, or through
enumeration of the window stack. Hidden windows are used during the
iconisation process. Windows from all stacks may be iconised, but child
windows may not. On being reopened, the window will return to the stack it
is declared in unless otherwise specified by the OpenWindow parameters.

 Arbitrary positions
 -------------------
Windows may be placed at arbitrary positions within the window stack by
using a window handle in the 'behind' value. This is the most commonly
used operation when creating panes. It can be performed by the user by
dragging the title or resize icons oc a window with Adjust pressed.

Moving windows outside their respective stacks (for example, opening a
'background' window behind a window with the 'foreground' type) will cause
undefined behaviour. In normal use, this should not occur, but developers
should be aware that this operation may cause windows to become unsequenced
and certain operations may not function as desired.


Differences from earlier versions
---------------------------------
It is partly because of problems with the earlier implementation of
background windows that this rationalisation of the window flags has taken
place. The core difference between the Select 3 version of the WindowManager
and earlier versions in this regard is that opening a background window at
the front (-1 as the 'behind' value) will now open it at the front of the
background window stack. Previous versions would open this window at the
front of the normal stack. This could cause significant problems and the
behaviour has been rationalised by the creation of a distinct window stack.

Clients wishing to achieve the same effect as previous versions of the
WindowManager with backwindows (without the problematic sideeffects) should
move the windows between the stacks by modifying the window flags. This can
be achieved through the use of the extended form of Wimp_OpenWindow to
modify the window flags.


Uses of background windows
--------------------------
Background windows are intended to provide either a defined visible image
for the user behind all active windows, or to provide an accelerator
mechanism. The Pinboard supplied with RISC OS provides both these functions.
Through the background window stack, applications may now open windows which
will be shown together with the main background and will not obscure normal
or foreground windows. This facility may be used for additional accelerators
or to provide transient background notifications.


Window stack ordering
---------------------
The window stack ordering is more rational than under previous versions of
the WindowManager. Operations moving windows to other parts of the stack
will occur as expected. The following diagram describes the positioning of
windows within the window stack. The windows 'behind' the 'Back most window'
are part of the WindowManager implementation rather than a particular
feature of the interface; they should not be relied on and are provided for
information purposes only.
  
    [Physical back of stack]
  
       Hidden windows (-3)
       Wimp-handled 'background' window (grey 2 window behind all windows)

    [Back most window (most obscured)]
       
       Background window -2     \
       Background window stack   >- Background window stack
       Background window -1     /
    
       Normal window -2         \
       Normal window stack       >- Normal window stack
       Normal window -1         /

       Foreground window -2     \
       Foreground window stack   >- Foreground window stack
       Foreground window -1     /

    [Fore most window (most visible)]
           
