|
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 'Focus 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 independent 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
bits 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 (i.e. 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.
|
![[Select]](../imgs/seldoc.png)
