ScrolledWindow(3w) — OLIT Widget Set
NAME
ScrolledWindow − scrolled window widget
SYNOPSIS
#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/ScrolledWi.h>
. . .
Widget my_scrolledwindow, my_parent;
String my_name;
ArgList args;
Cardinal num_args;
my_scrolledwindow = XtCreate( my_name, scrolledWindowWidgetClass,
my_parent, args, num_args);
. . .
Widget h_controlarea, v_controlarea;
XtSetArg( args[0], XtNhMenuPane, (XtArgVal) &h_controlarea);
XtSetArg( args[1], XtNvMenuPane, (XtArgVal) &v_controlarea);
XtGetValues( my_scrolledwindow, args, 1);
Widget h_area_item, h_area_parent, v_area_item, v_area_parent
WidgetClass h_item_class, v_item_class;
String h_item_name, v_item_name;
h_area_item = XtCreate( h_item_name, h_item_class, h_parent, args, num_args);
v_area_item = XtCreate( v_item_name, v_item_class, v_parent, args, num_args);
DESCRIPTION
The ScrolledWindow has no native text or graphic capabilities, but is used as 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,
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
child widget content ScrolledWindow child widget content ScrolledWindow
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.
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
_
Activation Type Expected Results
=
OL_VSBMENU
Popup the vertical scrollbar
OL_PAGEUP Scrolls up one
OL_PAGEDOWN Scrolls down one
OL_SCROLLUP Scrolls up one
OL_SCROLLDOWN Scrolls down one
OL_SCROLLTOP
Scrolls to top edge
OL_SCROLLBOTTOM
Scrolls to bottom edge
Scrolled Window Activation Types
(if it has a
_
Activation Type Expected Results
=
OL_HSBMENU
Popup the horizontal scrollbar
OL_PAGELEFT Scrolls left one
OL_PAGERIGHT Scrolls right one
OL_SCROLLRIGHT Scrolls right one
OL_SCROLLLEFT Scrolls left one
OL_SCROLLRIGHTEDGE
Scrolls to right edge
OL_SCROLLLEFTEDGE
Scrolls to left edge
RESOURCES
SUBSTRUCTURE
Names: verticalscrollbar, horizontalscrollbar
Class: Scrollbar
See the regular resource list for other names for some key Scrollbar resources.
Table 1 ScrolledWindow Resource Set
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
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
ScrolledWindow Resource Set (
Name Type Default Access
=
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 timeO = other access
† see resources(3W)
XtNalignHorizontal
class:XtCAlignHorizontal type:int default:OL_BOTTOMaccess:SGI
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:XtNalignVertical type:int default:OL_RIGHTaccess:SGI
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:XtCComputeGeometries type:Function default:Null Functionaccess:SGI
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;
(∗function) (content widget id, geometries)
Widget content widget id;
OlSWGeometries ∗ geometries;
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:XtCCurrentPage type:int default:1access:SGI
Action: passes value to vertical scrollbar of the ScrolledWindow.
See Scrollbar Widget(3W) for more details.
XtNforceHorizontalSB
class:XtCForceHorizontalSB type:Boolean default:FALSEaccess:SGI
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:XtCForceVerticalSB type:Boolean default:FALSEaccess:SGI
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:XtCHAutoScroll type:Boolean default:TRUEaccess:SGI
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:XtCHInitialDelay type:int default:500access:SGI
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:XtCHMenuPane type:Widget default:(none)access:G
Action: mimic the XtNmenuPane resources for the horizontal scrollbar.
See Scrollbar(3W) for more details.
XtNhRepeatRate
class:XtCHRepeatRate type:int default:100access:SGI
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:XtCScrollbar type:Widget default:(none)access:G
Action: give the widget ID’s of the horizontal scrollbar.
An application uses these values to set scrollbar characteristics, such as coloration.
XtNhSliderMoved
class:XtCCallBack type:XtCallbackList default:NULLaccess:SI
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:XtCHStepSize type:int default:1access:SGI
Action: specify minimum unit of scrolling.
Values: 0 < XtNhStepSize
This resource is related to the XtNgranularity resource for the horizontal scrollbar, with an important distinction: 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:XtCInitialX type:Position default:0access:GI
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:XtCInitialY type:Position default:0access:GI
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:XtCRecomputeHeight type:Boolean default:TRUEaccess:SGI
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:XtCRecomputeWidth type:Boolean default:TRUEaccess:SGI
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:XtCShowPage type:OlDefine default:OL_NONEaccess:SGI
Action: directed to the vertical scrollbar in the ScrolledWindow widget.
See Scrollbar(3W) for more details.
XtNvAutoScroll
class:XtCVAutoScroll type:Boolean default:TRUEaccess:SGI
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:XtCViewHeight type:Dimension default:0access:SGI
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 XtNrecomputeViewHeight), it will never resize the view larger than indicated.
XtNviewWidth
class:XtCViewWidth type:Dimension default:0access:SGI
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 XtNrecomputeViewWidth), it will never resize the view larger than indicated.
XtNvInitialDelay
class:XtCVInitialDelay type:int default:500access:SGI
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:XtCVMenuPane type:Widget default:(none)access:G
Action: mimic the XtNmenuPane resources for the vertical scrollbar.
See Scrollbar(3W) for more details.
XtNvRepeatRate
class:XtCVRepeatRate type:int default:100access:SGI
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:XtCScrollbar type:Widget default:(none)access:G
Action: give the widget ID’s of the vertical scrollbar.
An application uses these values to set scrollbar characteristics, such as coloration.
XtNvSliderMoved
class:XtCCallBack type:Pointer default:NULLaccess:SI
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:XtCVStepSize type:int default:1access:SGI
Action: specify minimum unit of scrolling.
Values: 0 < XtNvStepSize
This resource is related to the XtNgranularity resource for the vertical scrollbar, with an important distinction: 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 — Last change: 19 July 91 — Last change: 19 July 91