WindowScroll module
------------------

The WindowScroll module provides scrolling facilities for applications
within the desktop using the alternate positioning device ('scroll wheel').
The module runs as a desktop task in order to request changes in the
positioning of windows of other tasks.

The module provides one *Command to configure the behaviour of the window
scrolling feature.

*WimpScroll [-Type Pointer | Focus | FocusOrPointer | FavourHigher]
            [-LineScroll] [-Speed <speed>]


'Pointer' type behaviour
------------------------
When the WindowScroll module is configured for use 'Pointer', the window
under the pointer will always be selected.


'Focus' type behaviour
----------------------
When the WindowScroll module is configured for use 'Focus', the window with
the input focus will always be selected. If no window has the focus, no
scroll operations will be performed.


'Focus or pointer' type behaviour
---------------------------------
When the WindowScroll module is configured to use 'Caret or pointer', the
window with the input focus will be selected. If no window has the focus,
the window beneath the pointer will be scrolled.


'Favour higher' type behaviour
------------------------------
When the WindowScroll module is configured to 'favour higher windows', the
window which is highest in the window stack out of the window with the focus
and the window which the pointer is over will be selected.

Where child windows are in use, a common window stack is determined and the
front-most of the windows in either stack is treated as the position of the
window. Should the window with focus be a child of the window over which
the pointer is positioned (or vice-versa), the caret window will be selected
for scrolling.

Where the windows with common parents live in different stacks (having
different 'back' and 'front' bits set), the front-most of these will be
selected.


'Line scroll' option
--------------------
The 'Line Scroll' configuration option is independant of the scroll type
operations described above. The option affects windows which request
scroll events for scrolling windows by a line (or column) at a time when the
scroll buttons are pressed. When enabled, the line (or column) scrolling
event will be used, rather than scrolling by an arbitrary amount. Certain
document editors use this feature.


Pane windows
------------
In any of the behaviours described above, the windows being considered are
first examined to see whether they are scrollable through the use of panes.
If the caret or pointer is positioned in a window marked as a pane and does
not have scroll bars (or the new scroll request bit set), the window behind
the pane is considered instead. If it too is marked as a pane (or the new
scroll request bit is set), the process is repeated until the window being
considered is not a pane.


Programmers interface
---------------------
In order to take advantage of the new scroll features, new applications may
request that events be delivered when the scroll wheel is triggered, rather
than merely being scrolled.

If the window being scrolled has bit 1 of the extended window flags byte
set, it will be notified of scroll events using a new ScrollRequest. The
new definition of the extended window flags byte (window information block
offset 39) is thus :

    bit 0 : True colour validation provided
    bit 1 : Extended ScrollRequest events requested
    bit 2 : 3D disable
    bit 3 : 3D enable
  bit 4-7 : Reserved, must be 0

Reason_ScrollRequest (10)
  +0 to +31 as previously
  +32  scroll x direction
  +36  scroll y direction
  +40  icon being scrolled, or -1 if no icon is scrolled
       (only applicable for the extended scroll requests; non-extended
       scroll requests will not contain this element)

Scroll direction values are defined such that multiples of 4 signify the
extended scroll requests :

  -8 Two extended scroll operations left or down
  -4 One extended scroll operation left or down
  -3 AutoScroll request for left or down
  -2 Page left or down
  -1 Line/column left or down
   0 No operation
  +1 Line/column right or up
  +2 Line/column right or up
  +3 AutoScroll request for right or up
  +4 One extended scroll operation right or up
  +8 Two extended scroll operations right or up

Further multiples of 4 indicate linearly increasing numbers of scroll
operations. Applications are strongly encouraged to check for bits 0 and 1
before applying a shift of two right to obtain the number of scroll
operations to apply. This should allow for future expansion.

Filters operating on applications to modify the action of scroll events
are strongly encouraged to check only for values that they understand.
In earlier documentation only values -2, -1, 0, +1 and +2 were defined.
Values for -3 and +3 were added for RISC OS 4. Filters which operate only on
these values will be unaffected by the new behaviour of ScrollRequest.
Filters which operate on +ve or -ve values may experience undefined but
acceptable behaviour with the new operation. Filters which perform
operations based on the original values without checks for bounds may
experience undefined and fatal behaviour. It is not expected that there be
any filters in the latter category.

In addition to windows requesting Extended ScrollRequest events, icons may
request such events be delivered if the pointer is over them and their
window is selected for scrolling. Such icons can be used by filter tasks
and by applications wishing to employ the standard scroll methods for all
but selected regions of a window. In order to request extended scroll events,
an icon should include a new validation command.

The 'Y' validation command is defined to be used for boolean flags. Such
flags are 'enabled' if a specific character is present following the
command. The characters within the flag command may - as with validation
commands - use upper or lower case letters 'A'-'Z' and 'a'-'z'. The only
defined flag is :
  'S' - this icon wishes to receive scroll requests

When such an icon is 'scrolled', the ScrollRequest message above will be
delivered with the icon handle filled in.

For completeness, the currently defined validation commands are :

   'A'   Allow following chars
   'B'   Border type used by 'Interface' module
   'C'   24 bit colour selection
   'D'   Display char following for password
   'F'   Select font foreground/background hex colours
   'K'   Allow wimp key processing
   'L'   Set line spacing in OS units
   'M'   Reserved
   'N'   Used by various template editors for naming icons
   'P'   Set pointer from sprite name and active position
   'R'   Border type
   'S'   Sprite name
   'T'   Tinting sprites
   'U'   Reserved
   'X'   Wimp does not resize iconbar icons
   'Y'   Flag operation
   'Z'   RISC OS 3.00 border (replaced by 'R')


Pseudo-code for handling scroll requests :

do_scroll_request
{
  if ((yscroll & 3) == 0 && (xscroll & 3) == 0)
  {
    /* Extended scroll request */
    xscroll = xscroll / 4;
    yscroll = yscroll / 4;
    
    if (icon == -1)
    {
      /* Scroll request sent due to the extended scroll request bit being
         set in the window */
    }
    else
    {
      /* Scroll request sent due to the icon the pointer is over using
         the YS validation */
    }
  }
  else
  {
    /* Non-extended scroll request */
  }
}


Legacy application support
--------------------------
Legacy Applications (ie applications unaware of the scroll wheel) should
respond correctly to the scroll requests from the WindowScroll module.
Such applications which use the 'Line scroll' method of scrolling their
windows will see a number of scroll requests in rapid succession. These
should not affect such applications as the scroll positions provided
take account of changes performed by the application.

Applications which handle window scrolling through mechanisms other than
the window scroll bars may not behave as expected. The most common behaviour
for such applications is that the window will be unaffected by the scroll
wheel. The most prominent application which displays this behaviour is
'Eureka'. This application renders all its window furniture within its own
redraw loop, and as such has no Wimp-visible furniture. This, and similar
applications, are not handled by the WindowScroll module.
