ScrolledWindow(3W)
NAME
ScrolledWindow − scrolled window widget
SYNOPSIS
#include <Xol/OpenLook.h>
#include <Xol/ScrolledWi.h>
. . .
ANCESTRY
Core-Composite-Constraint-Manager-ScrolledWindow
DESCRIPTION
The ScrolledWindow has no native text or graphic capabilities, but provides the basis for implementing the OPEN LOOK scrollable text or graphics pane.
Note that the word “Window” in this widget’s name, does not refer to an OPEN LOOK window or an X window. The metaphor here is of a view through a window onto a “content”, which is a textual or graphic object. The content, i.e. the text or graphics pane can be larger than the window.
Components
The ScrolledWindow widget has the following components:
• vertical scrollbar (typically)
• horizontal scrollbar (typically)
• content (not all visible)
• view of the content (visible part of content)
• view border
Figure 1 Scrolled Window
Subwidgets
ScrolledWindow contains four subwidgets, two Scrollbars, horizontal and vertical, along with their associated menus, provided automatically, and accessible through the following resources:
XtNhScrollbar
XtNvScrollbar
XtNhMenupane
XtNvMenupane.
Figure 2 ScrolledWindow Subwidgets
PopupWindowShell
|
_____________________________________________________
| | | |
vert. Scrollbar vert MenuShell hor. Scrollbar hor MenuShell
(XtNvScrollBar) (XtNvMenupane) (XtNhScrollBar) (XtNhMenupane)
View Border
The view border is a 1-point outline around the view of the content.
View of Content
The ScrolledWindow widget incorporates the features of the ScrollBar class of widgets to implement a visible window (the view of the content) onto another, typically larger, data display (the content). The view of the content can be scrolled through the content using the scroll bars.
Child Widget as Content
To use the scrolled window, the application creates a widget capable of displaying the entire content as a child of the ScrolledWindow widget. The ScrolledWindow widget positions the child widget "within" the view of the content, and creates scroll bars for the horizontal and/or vertical dimensions, as needed. When the end user performs some action on the scroll bars, the child widget will be repositioned accordingly within the view of the content. A larger child widget positioned within a smaller view by the ScrolledWindow widget, is forced to display only the viewed part of itself. This is all handled through normal widget geometry management.
The word "within" is used strictly in the widget sense: the larger child widget is positioned within the smaller view of the content part of the ScrolledWindow widget, which necessarily forces the child widget to display only the visible part of itself. The protocol for this is through normal widget geometry interactions.
Upper Left Corner Fixed on Resize
If the ScrolledWindow widget is resized, the upper left corner of the view stays fixed over the same spot in the content, unless this would cause the view to extend past the right or bottom edge of the content. If necessary, the upper left corner will shift left or up only enough to keep the view from extending past the right or bottom edge.
View Never Larger than Content
The view of the content never becomes larger than needed to show the content. Unless forced to appear, a scrollbar is removed from the side where it is no longer needed. Remaining scrollbars stay a fixed distance from the view.
Scrolling Sensitivity
The scrollbars are configured to scroll integer values, in pixels, through the width and length of the content. This allows the finest degree of control of the positioning of the view of the content. However, the application can set the step rate through these values to avoid a large number of view updates as the end user scrolls through the content.
Coloration
of the ScrolledWindow widget.
Figure 3 Scrolled Window Coloration
Application Controlled Scrolling
The ScrolledWindow widget also provides support for the application to control the scrolling of the content data within the view. In this mode of operation, the application creates a content window no larger than the view window. The application monitors user interaction with the Scrollbars and displays the appropriate data in the content window.
This mode of operation supports the scrolling of large amounts of data such as text.
The application specifies this mode of operation by setting the XtNvAutoScroll and/or XtNhAutoScroll resources to FALSE. Normally, these settings are combined with the setting of the XtNvSliderMoved and/or XtNhSliderMoved callbacks. Also, the application will specify an XtNcomputeGeometries callback which is used to lay out the ScrolledWindow.
To programmatically manipulate the scrollbars on a ScrolledWindow, you must set the XtNuseSetValCallback resource of the Scrollbar widget to TRUE.
Keyboard Traversal
The ScrolledWindow controls the keyboard traversal between the content, the horizontal ScrollBar, and the vertical ScrollBar. The scrollbars that are created by the ScrolledWindow have the XtNtraversalOn resource set to
A content widget added to the ScrolledWindow with traversal enabled will be added to the traversalable widgets in the window with the scrollbars so that the user can move between them with the NEXT_FIELD (or MOVEUP or MOVELEFT) and PREV_FIELD (or MOVEDOWN or MOVERIGHT) keys.
Scrolled Window Activation Types
(if it has a Horizontal Scrollbar)
Table 1 ScrolledWindow Activation Types
Activation Typeand Expected Results
OL_VSBMENU Popup the vertical scrollbar menu
OL_PAGEUP Scrolls up one view
OL_PAGEDOWN Scrolls down one view
OL_SCROLLUP Scrolls up one Unit
OL_SCROLLDOWN Scrolls down one Unit
OL_SCROLLTOP Scrolls to top edge of pane
OL_SCROLLBOTTOM Scrolls to bottom edge of pane
Scrolled Window Activation Types
(if it has a Horizontal Scrollbar)
Activation Type Expected Results
OL_HSBMENU Popup the horizontal scrollbar menu
OL_PAGELEFT Scrolls left one view
OL_PAGERIGHT Scrolls right one view
OL_SCROLLRIGHT Scrolls right one Unit
OL_SCROLLLEFT Scrolls left one Unit
OL_SCROLLRIGHTEDGE Scrolls to right edge of pane
OL_SCROLLLEFTEDGE Scrolls to left edge of pane
RESOURCES
Names: verticalscrollbar, horizontalscrollbar
Class: Scrollbar
See the regular resource list for other names for some key Scrollbar resources.
Table 2 ScrolledWindow Resource Set
Name Type Default Access
XtNalignHorizontal int OL_BOTTOM SGI
XtNalignVertical int OL_RIGHT SGI
XtNancestorSensitive- Boolean TRUE GO
XtNborderColor- Pixel XtDefaultForeground SGI
XtNborderPixmap- Pixmap (none) SGI
XtNcomputeGeometries Function Null Function SGI
XtNconsumeEvent- XtCallbackList NULL SG
XtNcurrentPage int 1 SGI
XtNdepth- int (parent’s) GI
XtNdestroyCallback- XtCallbackList NULL SI
XtNforceHorizontalSB Boolean FALSE SGI
XtNforceVerticalSB Boolean FALSE SGI
XtNforeground- Pixel XtDefaultForeground SGI
XtNhAutoScroll Boolean TRUE SGI
XtNheight- Dimension (calculated) SGI
XtNhInitialDelay int 500 SGI
XtNhMenuPane Widget (none) G
XtNhRepeatRate int 100 SGI
XtNhScrollbar Widget (none) G
XtNhSliderMoved XtCallbackList NULL SI
XtNhStepSize int 1 SGI
XtNinitialX Position 0 GI
XtNinitialY Position 0 GI
XtNinputFocusColor- Pixel Red SGI
XtNmappedWhenManaged- Boolean TRUE SGI
XtNrecomputeHeight Boolean TRUE SGI
XtNrecomputeWidth Boolean TRUE SGI
XtNreferenceName- String NULL GI
XtNreferenceWidget- Widget NULL GI
XtNsensitive- Boolean TRUE GIO
XtNshowPage OlDefine OL_NONE SGI
XtNtraversalOn- Boolean TRUE SGI
XtNuserData- XtPointer NULL SGI
XtNvAutoScroll Boolean TRUE SGI
XtNviewHeight Dimension 0 SGI
XtNviewWidth Dimension 0 SGI
XtNvInitialDelay int 500 SGI
XtNvMenuPane Widget (none) G
XtNvRepeatRate int 100 SGI
XtNvScrollbar Widget (none) G
XtNvSliderMoved XtCallbackList NULL SI
XtNvStepSize int 1 SGI
XtNwidth- Dimension (calculated) SGI
XtNx- Position 0 SGI
XtNy- Position 0 SGI
Access: S = XtSetValues G = XtGetValues
I = init time O = other access
† see resources(3W)
XtNalignHorizontal
class:XtCAlignHorizontaltype:intdefault:OL_BOTTOMOL_BOTTOM’u’access:SGISGI’u’
Action: specifies where the horizontal scrollbar should be placed.
Values: OL_BOTTOM/"bottom" OL_TOP/"top"
The default placement is at the bottom.
XtNalignVertical
class:XtNalignVerticaltype:intdefault:OL_RIGHTOL_RIGHT’u’access:SGISGI’u’
Action: specifies where the vertical scrollbar should be placed.
Values: OL_RIGHT/"right" OL_LEFT/"left"
The default placement is at the right.
XtNcomputeGeometries
class:XtCComputeGeometriestype:Functiondefault:Null FunctionNull Function’u’access:SGISGI’u’
Action: allows cooperation during layout between the ScrolledWindow and its content widget.
The content widget sets this resource to a pointer to a function which is called whenever the ScrolledWindow needs to lay out its children. The function is called as:
typedef struct _OlSWGeometries {
Widget sw;
Widget vsb;
Widget hsb;
Dimension bb_border_width;
Dimension vsb_width;
Dimension vsb_min_height;
Dimension hsb_height;
Dimension hsb_min_width;
Dimension sw_view_width;
Dimension sw_view_height;
Dimension bbc_width;
Dimension bbc_height;
Dimension bbc_real_width;
Dimension bbc_real_height;
Dimension force_hsb;
Dimension force_vsb;
} OlSWGeometries;
void (∗compute_geometries)(OlSWGeometries∗ geometries,
Widget content_widget);
The ScrolledWindow widget populates the values in this structure before the call and examines them after the call to perform the layout operation.
The call function is responsible for populating the bbc_width, bbc_height elements of this structure with the desired size of it window; the bbc_real_width, bbc_real_height elements with the logical size of the data; and force_hsb, force_vsb flags to indicate which scrollbars the ScrolledWindow should include in the layout.
XtNcurrentPage
class:XtCCurrentPagetype:intdefault:11’u’access:SGISGI’u’
Action: passes value to vertical scrollbar of the ScrolledWindow.
See Scrollbar(3W) for more details.
XtNforceHorizontalSB
class:XtCForceHorizontalSBtype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’
Action: force attachment of scrollbar.
Values: TRUE – disables size checking and forces scrollbar to be attached to the window regardless of the size of the child widget. FALSE – performs size checking and does not force attachment.
When the child widget is created and positioned within the scrolled window, its width and height are examined. If the entire child widget will fit within the width of the scrolled window, the horizontal scrollbar will not be created, since there is no need to scroll in that direction.
If a scrollbar is forced but not needed because the content fits within the view, the scrollbar is made insensitive.
XtNforceVerticalSB
class:XtCForceVerticalSBtype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’
Action: force attachment of scrollbar.
Values: TRUE – disables size checking and forces scrollbar to be attached to the window regardless of the size of the child widget. FALSE – performs size checking and does not force attachment.
When the child widget is created and positioned within the scrolled window, its width and height are examined. If the entire child widget will fit within the height of the scrolled window, the vertical scrollbar will not be created, since there is no need to scroll in that direction.
If a scrollbar is forced but not needed because the content fits within the view, the scrollbar is made insensitive.
XtNhAutoScroll
class:XtCHAutoScrolltype:Booleandefault:TRUETRUE’u’access:SGISGI’u’
Action: sets the scrolling mode in the horizontal direction.
Values: TRUE – the ScrolledWindow widget is responsible for all interaction with the scrollbar and the positioning of the content window within the view. FALSE – the application is responsible for all scrollbar interaction and scrolling of the data within the content window.
XtNhInitialDelay
class:XtCHInitialDelaytype:intdefault:500500’u’access:SGISGI’u’
Action: specifies the time in milliseconds of the initial repeat delay to be used when the scrolling arrows of the horizontal scrollbar component of the ScrolledWindow are pressed.
XtNhMenuPane
class:XtCHMenuPanetype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: mimic the XtNmenuPane resources for the horizontal scrollbar.
This resource provides for the retrieval of a handle to the menu which may be popuped up over a scroll bar. This is useful for customizing the menu. For example, the application may add the concept of a page or chapter. The menu could then have items for scrolling forward and backword by those units.
See Scrollbar(3W) for more details.
XtNhRepeatRate
class:XtCHRepeatRatetype:intdefault:100100’u’access:SGISGI’u’
Action: specifies the time in milliseconds of the repeat delay to be used when the scrolling arrows of the horizontal scrollbar component of the ScrolledWindow are pressed.
XtNhScrollbar
class:XtCScrollbartype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: give the widget ID’s of the horizontal scrollbar.
An application uses these values to set scrollbar characteristics, such as coloration.
XtNhSliderMoved
class:XtCCallBacktype:XtCallbackListdefault:NULLNULL’u’access:SISI’u’
Action: give callbacks for tracking child position.
This resource mimics the XtNsliderMoved resource of the horizontal scrollbar. The call_data parameter for this callback is a pointer to an OlScrollBarVerify structure, as in the Scrollbar widget. The application can validate a scroll attempt before the ScrolledWindow widget will reposition the view of the content, and can update the page number and adjust the scrollbar elevator position. See Scrollbar(3W) for more details.
XtNhStepSize
class:XtCHStepSizetype:intdefault:11’u’access:SGISGI’u’
Action: specify minimum unit of scrolling.
Values: 0 < XtNhStepSize
The value is the size in pixels of the minimum scrollable unit in the content.
For instance, to allow the end user to scroll a single pixel in either direction, the value would be 1. Or, to allow the end user to scroll a character at a time horizontally, the value would be the width of a character. Scrolling a character at a time requires a constant width font, of course.
The ScrolledWindow widget uses these values to calibrate the minimum scrolling step, XtNgranularity, of the scrollbars.
XtNinitialX
class:XtCInitialXtype:Positiondefault:00’u’access:GIGI’u’
Action: specify initial position of child widget.
Values: XtNinitialX ≤ 0
The child widget is initially positioned at the upper left corner, (x,y) coordinates of (0,0). This positioning can be changed by specifying a new x,y location. The scrollbars are adjusted to give a visual indication of the offset specified in these resources. Note that the content is positioned within the view of the content, so as the view of the content moves progressively further through the content, the coordinates of the position become more negative. Thus the initial coordinate given in this resource should be zero or negative to assure proper operation of the scrolled window.
XtNinitialY
class:XtCInitialYtype:Positiondefault:00’u’access:GIGI’u’
Action: specify initial position of child widget.
Values: XtNinitialY ≤ 0
The child widget is initially positioned at the upper left corner, (x,y) coordinates of (0,0). This positioning can be changed by specifying a new x,y location. The scrollbars are adjusted to give a visual indication of the offset specified in these resources. Note that the content is positioned within the view of the content, so as the view of the content moves progressively further through the content, the coordinates of the position become more negative.
Thus the initial coordinates given in this resource should be zero or negative to assure proper operation of the scrolled window.
XtNrecomputeHeight
class:XtCRecomputeHeighttype:Booleandefault:TRUETRUE’u’access:SGISGI’u’
Action: control how the ScrolledWindow widget resizes itself.
Values: TRUE – the ScrolledWindow shrinks the view of the content in the corresponding direction to absorb the change in the ScrolledWindow widget’s size. FALSE – the ScrolledWindow does not shrink the view in that direction.
This resource, together with the XtNrecomputeWidth, XtNviewWidth, and XtNviewHeight resources, is typically used to set a preferred dimension in a direction that should not be scrolled.
XtNrecomputeWidth
class:XtCRecomputeWidthtype:Booleandefault:TRUETRUE’u’access:SGISGI’u’
Action: control how the ScrolledWindow widget resizes itself.
Values: TRUE – the ScrolledWindow shrinks the view of the content in the corresponding direction to absorb the change in the ScrolledWindow widget’s size. FALSE – the ScrolledWindow does not shrink the view in that direction.
This resource, together with the XtNrecomputeHeight, XtNviewWidth, and XtNviewHeight resources, is typically used to set a preferred dimension in a direction that should not be scrolled.
XtNshowPage
class:XtCShowPagetype:OlDefinedefault:OL_NONEOL_NONE’u’access:SGISGI’u’
Action: directed to the vertical scrollbar in the ScrolledWindow widget.
See Scrollbar(3W) for more details.
XtNvAutoScroll
class:XtCVAutoScrolltype:Booleandefault:TRUETRUE’u’access:SGISGI’u’
Action: sets the scrolling mode in the vertical direction.
Values: TRUE – the ScrolledWindow widget is responsible for all interaction with the scrollbar and the positioning of the content window within the view. FALSE – the application is responsible for all scrollbar interaction and scrolling of the data within the content window.
XtNviewHeight
class:XtCViewHeighttype:Dimensiondefault:00’u’access:SGISGI’u’
Action: define the preferred size of the view of the content, in pixels.
Values: 0 ≤ XtNviewHeight
If a nonzero value is given, the XtNheight resource is computed by adding the thickness of any scrollbar that appears. Any value in the XtNheight resource is overwritten.
If a zero value is given in the XtNviewHeight resource, the XtNheight resource is used instead. Regardless of which resource identifies the preferred height, the height of the view is never smaller than any scrollbar next to it. This resource also represents the maximum size of the view. While the ScrolledWindow may resize the view smaller than indicated in this resource (see XtNrecomputeHeight), it will never resize the view larger than indicated.
XtNviewWidth
class:XtCViewWidthtype:Dimensiondefault:00’u’access:SGISGI’u’
Action: define the preferred size of the view of the content, in pixels.
Values: 0 ≤ XtNviewWidth
If a nonzero value is given, the XtNwidth resource is computed by adding the thickness of any scrollbar that appears. Any value in the XtNwidth resource is overwritten.
If a zero value is given in the XtNviewWidth resource, the corresponding XtNwidth resource is used instead. Regardless of which resource identifies the preferred width, the width of the view is never smaller than any scrollbar next to it. This resource also represents the maximum size of the view. While the ScrolledWindow may resize the view smaller than indicated in this resource (see XtNrecomputeWidth), it will never resize the view larger than indicated.
XtNvInitialDelay
class:XtCVInitialDelaytype:intdefault:500500’u’access:SGISGI’u’
Action: specifies the time in milliseconds of the initial repeat delay to be used when the scrolling arrows of the vertical scrollbar component of the ScrolledWindow are pressed.
XtNvMenuPane
class:XtCVMenuPanetype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: mimic the XtNmenuPane resources for the vertical scrollbar.
See Scrollbar(3W) for more details.
XtNvRepeatRate
class:XtCVRepeatRatetype:intdefault:100100’u’access:SGISGI’u’
Action: specifies the time in milliseconds of the repeat delay to be used when the scrolling arrows of the vertical scrollbar component of the ScrolledWindow are pressed.
XtNvScrollbar
class:XtCScrollbartype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: give the widget ID’s of the vertical scrollbar.
An application uses these values to set scrollbar characteristics, such as coloration.
XtNvSliderMoved
class:XtCCallBacktype:Pointerdefault:NULLNULL’u’access:SISI’u’
Action: give callbacks for tracking child position.
This resource mimics the XtNsliderMoved resource of the vertical scrollbar. The call_data parameter for this callback is a pointer to an OlScrollBarVerify structure, as in the Scrollbar widget. The application can validate a scroll attempt before the ScrolledWindow widget will reposition the view of the content, and can update the page number and adjust the scrollbar elevator position. See Scrollbar(3W) for more details.
XtNvStepSize
class:XtCVStepSizetype:intdefault:11’u’access:SGISGI’u’
Action: specify minimum unit of scrolling.
Values: 0 < XtNvStepSize
The value is the size in pixels of the minimum scrollable unit in the content.
For instance, to allow the end user to scroll a single pixel in either direction, this value would be 1. Or, to allow the end user to scroll a line at a time vertically, the value would be the height of a line.
The ScrolledWindow widget uses these values to calibrate the minimum scrolling step, XtNgranularity, of the scrollbars.
SEE ALSO
Version 3.0.1 — Last change: June 92