SCROLLED WINDOW WIDG
ME
IS
T(
C.
3W)
REFERENCE MANUA
SC
LRO
PA
LG
LED
S WINDOW WIDGET(3W)
WIDGET CLASS NAME
ScrolledWindow
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 graph-
ics 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
Amiga Unix Last change: 1
SCROLLED WINDOW WIDG
ME
IS
T(
C.
3W)
REFERENCE MANUA
SC
LRO
PA
LG
LED
S WINDOW WIDGET(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 widg-
ets to implement a visible window (the View of the Con-
tent) 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. 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.
Amiga Unix Last change: 2
SCROLLED WINDOW WIDG
ME
IS
T(
C.
3W)
REFERENCE MANUA
SC
LRO
PA
LG
LED
S WINDOW WIDGET(3W)
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 extend-
ing 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
SUBSTRUCTURE
Vertical Scrollbar and Horizontal Scrollbar components
Names: verticalscrollbar, horizontalscrollbar
Class: Scrollbar
See the regular resource list for alternate names used for
some key Scrollbar resources.
RESOURCES
Amiga Unix Last change: 3
SCROLLED WINDOW WIDG
ME
IS
T(
C.
3W)
REFERENCE MANUA
SC
LRO
PA
LG
LED
S WINDOW WIDGET(3W)
______________________________________________________________________________________
|_____________________________ScrolledWindow_Resource_Set_____________________________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|________________|______________|________|
| XtNancestorSensitive| XtCSenstitive | Boolean | TRUE | G* |
|_____________________|______________________|________________|______________|________|
|_XtNborderColor______|__XtCBorderColor______|__Pixel_________|__Black_______|__SGI___|
| XtNborderPixmap | XtCPixmap | Pixmap | (none) | SGI |
|_____________________|______________________|________________|______________|________|
|_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___|
| XtNhMenuPane | XtCHMenuPane | Widget | (none) | G |
|_____________________|______________________|________________|______________|________|
|_XtNhScrollbar_______|__XtCScrollbar________|__Widget________|__(none)______|__G_____|
| XtNhSliderMoved | XtCCallBack | XtCallbackList| NULL | SI |
|_____________________|______________________|________________|______________|________|
|_XtNhStepSize________|__XtCHStepSize________|__int___________|__1___________|__SGI___|
| XtNheight | XtCHeight | Dimension | (calculated)| SGI |
|_____________________|______________________|________________|______________|________|
|_XtNinitialX_________|__XtCInitialX_________|__Position______|__0___________|__GI____|
| XtNinitialY | XtCInitialY | Position | 0 | GI |
|_____________________|______________________|________________|______________|________|
|_XtNmappedWhenManaged|__XtCMappedWhenManaged|__Boolean_______|__TRUE________|__SGI___|
| XtNrecomputeHeight | XtCRecomputeHeight | Boolean | TRUE | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNrecomputeWidth___|__XtCRecomputeWidth___|__Boolean_______|__TRUE________|__SGI___|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_____________________|______________________|________________|______________|________|
|_XtNshowPage_________|__XtCShowPage_________|__OlDefine______|__OL_NONE_____|__SGI___|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNviewHeight_______|__XtCViewHeight_______|__Dimension_____|__(n/a)_______|__SGI___|
| XtNviewWidth | XtCViewWidth | Dimension | (n/a) | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNvMenuPane________|__XtCVMenuPane________|__Widget________|__(none)______|__G_____|
| XtNvScrollbar | XtCScrollbar | Widget | (none) | G |
|_____________________|______________________|________________|______________|________|
|_XtNvSliderMoved_____|__XtCCallBack_________|__Pointer_______|__NULL________|__SI____|
| XtNvStepSize | XtCVStepSize | int | 1 | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNwidth____________|__XtCWidth____________|__Dimension_____|__(calculated)|__SGI___|
| XtNx | XtCPosition | Position | 0 | SGI |
|_____________________|______________________|________________|______________|________|
|_XtNy________________|__XtCPosition_________|__Position______|__0___________|__SGI___|
Amiga Unix Last change: 4
SCROLLED WINDOW WIDG
ME
IS
T(
C.
3W)
REFERENCE MANUA
SC
LRO
PA
LG
LED
S WINDOW WIDGET(3W)
XtNcurrentPage
XtNshowPage These resources are directed to the vertical
scrollbar in the ScrolledWindow widget. See SCROLLBAR
WIDGET(3W) for more detail.
XtNforceHorizontalSB
XtNforceVerticalSB
Range of Values:
TRUE
FALSE
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 (length) of
the scrolled window, 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.
XtNhMenuPane
XtNvMenuPane These resources mimic the XtNmenuPane resources
for the horizontal and vertical scrollbars, respectively.
See SCROLLBAR WIDGET(3W) for more details.
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 scrolled window by linking into these call-
backs. They mimic the XtNsliderMoved resources of the hor-
izontal and vertical scrollbars, respectively. The
call_data 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 Con-
tent, and can update the page number and adjust the
scrollbar elevator position. See SCROLLBAR (WIDGET(3W) for
more details.
Amiga Unix Last change: 5
SCROLLED WINDOW WIDG
ME
IS
T(
C.
3W)
REFERENCE MANUA
SC
LRO
PA
LG
LED
S WINDOW WIDGET(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 Con-
tent. For instance, to allow the end user to scroll a sin-
gle pixel in either direction, these values would be 1. Or,
to allow the end user to scroll a character at a time hor-
izontally 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. These resources, together with
the XtNviewWidth and XtNviewHeight resources, are typically
Amiga Unix Last change: 6
SCROLLED WINDOW WIDG
ME
IS
T(
C.
3W)
REFERENCE MANUA
SC
LRO
PA
LG
LED
S WINDOW WIDGET(3W)
used to set a preferred dimension in a direction that should
not be scrolled.
Amiga Unix Last change: 7
SCROLLED WINDOW WIDG
ME
IS
T(
C.
3W)
REFERENCE MANUA
SC
LRO
PA
LG
LED
S WINDOW WIDGET(3W)
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. XtNrecompu-
teViewHeight and XtNrecomputeViewWidth), it will never
resize the View larger than indicated.
Amiga Unix Last change: 8