ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
NAME
ScrolledWindow - used as the basis for implementing a scrollable pane
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <ScrolledWi.h>
static Widget scrolledwindow, controlarea1, controlarea2, w;
Arg args[2];
scrolledwindow = XtCreateWidget(name, scrolledWindowWidgetClass, ...);
/*Use the following instructions to add two buttons to the
scrolling window. */
XtSetArg(args[0], XtNhMenuPane, &controlarea1);
XtSetArg(args[1], XtNvMenuPane, &controlarea2);
XtGetValues(scrolledwindow, args, 2);
w = XtCreateWidget(name, widget-class, controlarea1, ...);
w = XtCreateWidget(name, widget-class, controlarea2, ...);
DESCRIPTION
No Text or Graphics Semantics
The ScrolledWindow can be used as the basis for implementing an OPEN LOOK
scrollable text or graphics pane. However, it has no innate text or
graphics semantics. "Window" does not refer to an OPEN LOOK pop-up
window or base window; it is a general term used because the
ScrolledWindow widget provides a "window" onto a larger widget.
ScrolledWindow 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
10/89 Page 1
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
Figure 1. Scrolled Window
View Border
The View Border is a 1-point outline around the View of the Content.
View onto Larger Data Display
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 ScrollWindow, 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.
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 is never made 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.
ScrolledWindow Coloration
Figure 2 illustrates which resources affect the coloration of the
ScrolledWindow widget.
Figure 2. Scrolled Window Coloration
Page 2 10/89
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
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 layout 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 False. 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 Vertical Scrollbar) |
|________________|________________________________|
| Activation Type| 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
10/89 Page 3
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
_____________________________________________________
| Scrolled Window Activation Types |
| (if it has a Horizontal Scrollbar) |
|___________________|________________________________|
| Activation Type | Expected Results |
|||
OL_PAGELEFT Scrolls left one view
OL_PAGERIGHT Scrolls right one view
OL_SCROLLRIGHT Scrolls right one Unit
OL_SCROLLLEFT Scrolls left one Unit
Page 4 10/89
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
_____________________________________________________
| Scrolled Window Activation Types |
| (if it has a Horizontal Scrollbar) |
|___________________|________________________________|
| Activation Type | Expected Results |
|||
| OL_SCROLLRIGHTEDGE| Scrolls to right edge of pane |
| OL_SCROLLLEFTEDGE | Scrolls to left edge of pane |
|___________________|________________________________|
SUBSTRUCTURE
Vertical Scrollbar and Horizontal Scrollbar components
Names: HScrollbar, VScrollbar
Class: Scrollbar
See the regular resource list for alternate names used for some key
Scrollbar resources.
RESOURCES
_________________________________________________________________________________________
| ScrolledWindow Resource Set |
|______________________|______________________|_________________|_______________|________|
| Name | Class | Type | Default | Access|
|______________________|______________________|_________________|_______________|________|
_________________________________________________________________________________________
XtNalignHorizontal XtCAlignHorizontal int 5 SGI
_________________________________________________________________________________________
XtNalignVertical XtCAlignVertical int 58 SGI
_________________________________________________________________________________________
XtNancestorSensitive XtCSenstitive Boolean TRUE G*
_________________________________________________________________________________________
XtNborderColor XtCBorderColor Pixel Black SGI
_________________________________________________________________________________________
XtNborderPixmap XtCPixmap Pixmap (none) SGI
_________________________________________________________________________________________
XtNcomputeGeometries XtCComputeGeometries Function Null Function SGI
_________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SG
_________________________________________________________________________________________
XtNcurrentPage XtCCurrentPage int 1 SGI
_________________________________________________________________________________________
XtNdepth XtCDepth int (parent's) GI
_________________________________________________________________________________________
XtNdestroyCallback XtCCallback XtCallbackList NULL SI
_________________________________________________________________________________________
XtNforceHorizontalSB XtCForceHorizontalSB Boolean FALSE SGI
_________________________________________________________________________________________
XtNforceVerticalSB XtCForceVerticalSB Boolean FALSE SGI
_________________________________________________________________________________________
XtNforeground XtCForeground Pixel Black SGI
_________________________________________________________________________________________
XtNhAutoScroll XtCHAutoScroll Boolean TRUE SGI
10/89 Page 5
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
_________________________________________________________________________________________
| ScrolledWindow Resource Set |
|______________________|______________________|_________________|_______________|________|
| Name | Class | Type | Default | Access|
|______________________|______________________|_________________|_______________|________|
_________________________________________________________________________________________
XtNhInitialDelay XtCHInitialDelay int 500 SGI
_________________________________________________________________________________________
XtNhMenuPane XtCHMenuPane Widget (none) G
_________________________________________________________________________________________
XtNhRepeatRate XtCHRepeatRate int 100 SGI
_________________________________________________________________________________________
XtNhScrollbar XtCHScrollbar Widget (none) G
_________________________________________________________________________________________
XtNhSliderMoved XtCHSliderMoved XtCallbackList NULL SI
_________________________________________________________________________________________
XtNhStepSize XtCHStepSize int 1 SGI
_________________________________________________________________________________________
XtNheight XtCHeight Dimension (calculated) SGI
_________________________________________________________________________________________
XtNinitialX XtCInitialX Position 0 GI
_________________________________________________________________________________________
XtNinitialY XtCInitialY Position 0 GI
_________________________________________________________________________________________
XtNinputFocusColor XtCInputFocusColor Pixel Black SGI
_________________________________________________________________________________________
XtNmappedWhenManaged XtCMappedWhenManaged Boolean TRUE SGI
_________________________________________________________________________________________
XtNrecomputeHeight XtCRecomputeHeight Boolean TRUE SGI
_________________________________________________________________________________________
XtNrecomputeWidth XtCRecomputeWidth Boolean TRUE SGI
_________________________________________________________________________________________
XtNreferenceName XtCReferenceName String NULL GI
_________________________________________________________________________________________
XtNreferenceWidget XtCReferenceWidget Widget NULL GI
_________________________________________________________________________________________
XtNsensitive XtCSensitive Boolean TRUE GI*
_________________________________________________________________________________________
XtNshowPage XtCShowPage OlDefine OL_NONE SGI
_________________________________________________________________________________________
XtNtraversalOn XtCTraversalOn Boolean TRUE SGI
_________________________________________________________________________________________
XtNuserData XtCUserData XtPointer NULL SGI
_________________________________________________________________________________________
XtNviewHeight XtCViewHeight Dimension (n/a) SGI
_________________________________________________________________________________________
XtNviewWidth XtCViewWidth Dimension (n/a) SGI
_________________________________________________________________________________________
XtNvAutoScroll XtCVAutoScroll Boolean TRUE SGI
_________________________________________________________________________________________
XtNvInitialDelay XtCVInitialDelay int 500 SGI
_________________________________________________________________________________________
Page 6 10/89
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
_________________________________________________________________________________________
| ScrolledWindow Resource Set |
|______________________|______________________|_________________|_______________|________|
| Name | Class | Type | Default | Access|
|______________________|______________________|_________________|_______________|________|
| XtNvMenuPane | XtCVMenuPane | Widget | (none) | G |
|______________________|______________________|_________________|_______________|________|
| XtNvRepeatRate | XtCVRepeatRate | int | 100 | SGI |
|______________________|______________________|_________________|_______________|________|
| XtNvScrollbar | XtCVScrollbar | Widget | (none) | G |
|______________________|______________________|_________________|_______________|________|
| XtNvSliderMoved | XtCVSliderMoved | XtCallbackList | NULL | SI |
|______________________|______________________|_________________|_______________|________|
| XtNvStepSize | XtCVStepSize | int | 1 | SGI |
|______________________|______________________|_________________|_______________|________|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|______________________|______________________|_________________|_______________|________|
| XtNx | XtCPosition | Position | 0 | SGI |
|______________________|______________________|_________________|_______________|________|
| XtNy | XtCPosition | Position | 0 | SGI |
|______________________|______________________|_________________|_______________|________|
XtNalignHorizontal
Range of values:
OL_BOTTOM/"bottom"
OL_TOP/"top"
This resource is used to specify whether the horizontal scrollbar should
be placed at the top or bottom of the ScrolledWindow. The default
placement is at the bottom.
XtNalignVertical
Range of values:
OL_RIGHT/"right"
OL_LEFT/"left"
This resource is used to specify whether the vertical scrollbar should be
placed at the left or right of the ScrolledWindow. The default placement
is at the right.
XtNcomputeGeometries
This resource is used to allow intelligent cooperation during the layout
stage between the ScrolledWindow and its content widget. The content
widget sets this resource to a pointer to a function which is to be
called whenever the ScrolledWindow needs to layout its children. The
function is called as:
typedef struct OlSWGeometries {
Widget sw;
Widget vsb;
Widget hsb;
Dimension bbborderwidth;
10/89 Page 7
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
Dimension vsbwidth;
Dimension vsbminheight;
Dimension hsbheight;
Dimension hsbminwidth;
Dimension swviewwidth;
Dimension swviewheight;
Dimension bbcwidth;
Dimension bbcheight;
Dimension bbcrealwidth;
Dimension bbcrealheight;
Boolean forcehsb;
Boolean forcevsb;
} OlSWGeometries;
(*function)(content widget id, geometries)
Widget content widget id;
OlSWGeometries * geometries;
The ScrolledWindow widget populates the values in this structure prior to
the call and examines them after the call to perform the layout
operation.
The callback function is responsible for populating the bbcwidth,
bbcheight elements of this structure with the desired size of its
window; the bbcrealwidth, bbcrealheight elements with the logical
size of the data, and forcehsb, forcevsb flags to indicate which
scrollbars the ScrolledWindow should include in the layout.
XtNcurrentPage
The value of this resource is passed through to the vertical scrollbar of
the ScrolledWindow. See a SCROLLBAR WIDGET(3W) for more details.
XtNshowPage
These resources are directed to the vertical scrollbar in the
ScrolledWindow widget. See ScrollBar (3W) for more detail.
XtNforceHorizontalSB
XtNforceVerticalSB
Range of Values:
TRUE
FALSE
When the child widget is created and positioned within the
ScrolledWindow, its width and height are examined. If the entire child
widget will fit within the width (length) of the ScrolledWindow, the
horizontal (vertical) scrollbar will not be created, since there is no
need to scroll in that direction. Setting these resources to TRUE
disables this checking and will force a horizontal (vertical) scrollbar
to be attached to the window regardless of the dimension of the child
widget. If a scrollbar is forced but not needed because the Content fits
within the View, the scrollbar is made insensitive.
Page 8 10/89
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
XtNhAutoScroll
XtNvAutoScroll
This resource is used to set the scrolling mode in the horizontal
(vertical) direction. When set to TRUE, the ScrolledWindow widget is
responsible for all interaction with the scrollbar and the positioning of
the content window within the view. When set to FALSE, the application
is responsible for all scrollbar interaction and scrolling of the data
within the content window.
XtNhInitialDelay
XtNvInitialDelay
These resources are used to specify the time in milliseconds of the
initial repeat delay to be used when the scrolling arrows of the
horizontal (vertical) scrollbar component of the ScrolledWindow are
pressed.
XtNhMenuPane
XtNvMenuPane
These resources mimic the XtNmenuPane resources for the horizontal and
vertical scrollbars, respectively. See ScrollBar(3W) for more details.
XtNhRepeatRate
XtNvRepeatRate
These resources are used to specify the time in milliseconds of the
repeat delay to be used when the scrolling arrows of the horizontal
(vertical) scrollbar component of the ScrolledWindow are pressed.
XtNhScrollbar
XtNvScrollbar
These resources provide the widget id's of the horizontal and vertical
scrollbars. An application can use these values to set scrollbars'
characteristics, such as coloration.
XtNhSliderMoved
XtNvSliderMoved
An application may track the position of the child within the
ScrolledWindow by linking into these callbacks. They mimic the
XtNsliderMoved resources of the horizontal and vertical scrollbars,
respectively.
The calldata parameter for these callbacks 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.
10/89 Page 9
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
XtNhStepSize
XtNvStepSize
Range of Values:
0 < XtNhStepSize
0 < XtNStepSize
These resources are related to the XtNgranularity resource for the
horizontal and vertical scrollbars, respectively, but have an important
distinction: their values are 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, these values would be 1. Or,
to allow the end user to scroll a character at a time horizontally and a
line at a time vertically, these values would be the width of a character
and the height of a line, respectively. (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
XtNinitialY
Range of Values:
XtNinitialX < 0
XtNinitialY < 0
The child widget is initially positioned at the upper left corner (x,y
coordinates 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 these resources should be zero or negative to assure
proper operation of the scrolled window.
XtNrecomputeHeight
XtNrecomputeWidth
Range of Values:
TRUE
FALSE
These resources control how the ScrolledWindow widget should respond to
requests to resize itself. Where one of these resources is TRUE, the
ScrolledWindow shrinks the View of the Content in the corresponding
direction to absorb the change in the ScrolledWindow widget's size.
Where one of these resources is FALSE, the ScrolledWindow does not shrink
the View in that direction.
Page 10 10/89
ScrolledWindow(3W) UNIX System V ScrolledWindow(3W)
These resources, together with the XtNviewWidth and XtNviewHeight
resources, are typically used to set a preferred dimension in a direction
that should not be scrolled.
XtNviewHeight
XtNviewWidth
Range of Values:
0 < XtNviewHeight
0 < XtNviewWidth
These resources define the preferred size of the View of the Content in
pixels. For each, if a nonzero value is given, the corresponding
XtNheight or XtNwidth resource is computed by adding the thickness of any
scrollbar that appears. Any value in the XtNheight or XtNwidth resource
is overwritten. If a zero value is given in the XtNviewHeight or
XtNviewWidth resource, the corresponding XtNheight or XtNwidth resource
is used instead.
Regardless of which resources identify the preferred height or width, the
height or width of the View is never smaller than any scrollbar next to
it.
These resources also represent the maximum size of the View. While the
ScrolledWindow may resize the View smaller than indicated in these
resources (cf. XtNrecomputeViewHeight and XtNrecomputeViewWidth), it
will never resize the View larger than indicated.
10/89 Page 11