'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olScrollWin @(#)olScrollWin	40.3 of 1/8/90
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ig
Modified 10/18/89 by lmh
Modified 10/20/89 by lmh
Modified 10/27/89 by lmh
..
.ds cW SCROLLEDWINDOW
.ds rW ScrolledWindow
.ds nW ScrolledWi
.ds wW scrolledWindow
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""SCROLLED WINDOW WIDGET" 3W "\&"
.if \nX=1 .ds x} ""SCROLLED WINDOW WIDGET" 3W
.if \nX=2 .ds x} ""SCROLLED WINDOW "" "\&"
.if \nX=3 .ds x} ""SCROLLED "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <\*(nW.h>\f1\s+1\f1
.fi
.P
.nf
\s-1\f4static Widget scrolledwindow, controlarea1, controlarea2, w;
.P
\s-1\f4Arg args[2];
.P
\s-1\f4scrolledwindow = XtCreateWidget(\f2name\f4, \*(wWWidgetClass, ...);
.P
	\s-1\f4/*Use the following instructions to add two buttons to the scrolling window. */
.P
\s-1\f4XtSetArg(args[0], XtNhMenuPane, &controlarea1);
XtSetArg(args[1], XtNvMenuPane, &controlarea2);
XtGetValues(scrolledwindow, args, 2);
w = XtCreateWidget(\f2name\f4, \f2widget-class\f4, controlarea1, ...);
w = XtCreateWidget(\f2name\f4, \f2widget-class\f4, controlarea2, ...);\f1\s+1
.fi
.SH "DESCRIPTION"
.sp
\f3No Text or Graphics Semantics\f1
.P
The \*(bW 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 \*(bW widget provides a
"window" onto a larger widget.
.sp
\f3\*(rW Components\f1
.P
The \*(bW widget has the following components:
.IP \(em 1.5P
.LI
Vertical Scrollbar (typically)
.IP \(em 1.5P
Horizontal Scrollbar (typically)
.IP \(em 1.5P
Content (not all visible)
.IP \(em 1.5P
View of the Content (visible part of Content)
.IP \(em 1.5P
View Border
.br
.ne 3.5i
.BP PSART/ps.scrolled1
.P
.ce
\f3Figure 1.\f1  Scrolled Window
.sp
.ig
\f3Left or Right Vertical Scrollbar\f1
.P
The end user can have the Vertical Scrollbar
placed to the left or the right of the View of the Content.
.sp
..
\f3View Border\f1
.P
The View Border is a 1-point outline around the View of the
Content.
.sp
\f3View onto Larger Data Display\f1
.P
The \*(bW widget incorporates the features of the
\f3ScrollBar\f1
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.
.sp
\f3Child Widget as Content\f1
.P
To use the scrolled window,
the application creates a widget capable of displaying the
entire Content as a child of the \*(bW widget.
The \*(bW 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.
.P
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 \*(bW 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.
.bp
\f3Upper Left Corner Fixed on Resize\f1
.P
If the \*(bW 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.
.sp
\f3View Never Larger than Content\f1
.P
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.
.sp
\f3Scrolling Sensitivity\f1
.P
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.
.sp
\f3\*(rW Coloration\f1
.P
Figure 2 illustrates which resources affect the coloration
of the \*(bW widget.
.br
.ne 3i
.BP PSART/ps.scrolled2
.ce
\f3Figure 2.\f1  Scrolled Window Coloration
.P
.SH "SUBSTRUCTURE"
.P
\f3Vertical Scrollbar and Horizontal Scrollbar components\f1
.P
.nf
Names: verticalscrollbar, horizontalscrollbar
Class: Scrollbar
.fi
.sp .5
See the regular resource list for alternate names used for some
key
\f3Scrollbar\f1
resources.
.SH "RESOURCES"
.TS
expand, allbox;
cB s s s s.
\*(bW Resource Set
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.T&
lp-2 lp-2 lp-2 lp-2 lp-2.
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
.TE
.bp
\f3XtNcurrentPage\f1
.br
.br
\f3XtNshowPage\f1
.P
These resources are directed to the vertical scrollbar in the
\*(bW widget.
See \f3SCROLLBAR WIDGET(3W)\f1
for more detail.
.sp
\f3XtNforceHorizontalSB\f1
.br
.br
\f3XtNforceVerticalSB\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
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
\f4TRUE\f1
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. 
.sp
\f3XtNhMenuPane\f1
.br
.br
\f3XtNvMenuPane\f1
.P
These resources mimic the
\f4XtNmenuPane\f1
resources for the horizontal and vertical scrollbars,
respectively.
See \f3SCROLLBAR WIDGET(3W)\f1
for more details.
.sp
\f3XtNhScrollbar
.br
\f3XtNvScrollbar\f1
.P
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.
.sp
\f3XtNhSliderMoved\f1
.br
.br
\f3XtNvSliderMoved\f1
.P
An application may track the position of the child within the
scrolled window by linking into these callbacks.
They mimic the
\f4XtNsliderMoved\f1
resources of the horizontal and vertical scrollbars,
respectively.
.P
The
\f4call_data\f1
parameter for these callbacks is a pointer to an
\f4OlScrollBarVerify\f1
structure, as in the
\f3Scrollbar\f1
widget.
The application can validate a scroll attempt before the \*(bW
widget will reposition the View of the Content,
and can update the page number and adjust the scrollbar
elevator position.
See \f3SCROLLBAR (WIDGET(3W)\f1
for more details.
.bp
\f3XtNhStepSize\f1
.br
.br
\f3XtNvStepSize\f1
.PP
Range of Values:
.br
.in +5
.nf
\f40 < XtNhStepSize
0 < XtNStepSize\f1
.in -5
.fi
.PP
These resources are related to the
\f4XtNgranularity\f1
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 \*(bW widget uses these values to calibrate the minimum
scrolling step,
\f4XtNgranularity\f1,
of the scrollbars.
.sp
\f3XtNinitialX\f1
.br
.br
\f3XtNinitialY\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4XtNinitialX \(<= 0
XtNinitialY \(<= 0\f1
.in -5
.fi
.PP
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.
.P
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
\f2negative\f1.
Thus the initial coordinates given in these resources should be
zero or negative to assure proper operation of the scrolled
window.
.sp
\f3XtNrecomputeHeight\f1
.br
.br
\f3XtNrecomputeWidth\f1
.P
Range of Values:
.br
.nf
.in +5
\f4TRUE
FALSE\f1
.in -5
.fi
.P
These resources control how the \*(bW widget should respond to
requests to resize itself.  Where one of these resources is
\f4TRUE\f1, the \*(bW shrinks the View of the Content in the
corresponding direction to absorb the change in the \*(bW
widget's size.  Where one of these resources is \f4FALSE\f1,
the \*(bW does not shrink the View in that direction.
.P
These resources, together with the \f4XtNviewWidth\f1 and
\f4XtNviewHeight\f1 resources, are typically used to set a
preferred dimension in a direction that should not be scrolled.
.bp
\f3XtNviewHeight\f1
.br
.br
\f3XtNviewWidth\f1
.PP
Range of Values:
.br
.in +5
.nf
\f40 \(<= XtNviewHeight
0 \(<= XtNviewWidth\f1
.in -5
.fi
.PP
These resources define the preferred size of the View of the
Content in pixels.
For each,
if a nonzero value is given, the corresponding
\f4XtNheight\f1
or
\f4XtNwidth\f1
resource is computed by adding the thickness of any scrollbar
that appears.
Any value in the
\f4XtNheight\f1
or
\f4XtNwidth\f1
resource is overwritten.
If a zero value is given in the
\f4XtNviewHeight\f1
or
\f4XtNviewWidth\f1
resource,
the corresponding
\f4XtNheight\f1
or
\f4XtNwidth\f1
resource is used instead.
.P
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.
.P
These resources also represent the maximum size of the View. 
While the \*(bW may resize the View smaller than indicated in
these resources
(cf.
\f4XtNrecomputeViewHeight\f1
and
\f4XtNrecomputeViewWidth\f1),
it will never resize the View larger than indicated.
