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 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
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 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.  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

the diagram Scrolled Window Coloration illustrates which resources affect the coloration of the ScrolledWindow widget. 

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

ScrolledWindow Resource Set
                Name            Type       Default  Access XtNancestorSensitive         Boolean          TRUE      G∗
      XtNborderColor           Pixel         Black     SGI
     XtNborderPixmap          Pixmap        (none)     SGI
      XtNcurrentPage             int             1     SGI
            XtNdepth             int    (parent’s)      GI
  XtNdestroyCallback  XtCallbackList          NULL      SI XtNforceHorizontalSB         Boolean         FALSE     SGI
  XtNforceVerticalSB         Boolean         FALSE     SGI
        XtNhMenuPane          Widget        (none)       G
       XtNhScrollbar          Widget        (none)       G
     XtNhSliderMoved  XtCallbackList          NULL      SI
        XtNhStepSize             int             1     SGI
           XtNheight       Dimension  (calculated)     SGI
         XtNinitialX        Position             0      GI
         XtNinitialY        Position             0      GI XtNmappedWhenManaged         Boolean          TRUE     SGI
  XtNrecomputeHeight         Boolean          TRUE     SGI
   XtNrecomputeWidth         Boolean          TRUE     SGI
        XtNsensitive         Boolean          TRUE     GI∗
         XtNuserData       XtPointer          NULL     SGI
       XtNviewHeight       Dimension         (n/a)     SGI
        XtNviewWidth       Dimension         (n/a)     SGI
        XtNvMenuPane          Widget        (none)       G
       XtNvScrollbar          Widget        (none)       G
     XtNvSliderMoved         Pointer          NULL      SI
        XtNvStepSize             int             1     SGI
            XtNwidth       Dimension  (calculated)     SGI
                XtNx        Position             0     SGI
                XtNy        Position             0     SGI 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 callbacks.  They mimic the XtNsliderMoved resources of the horizontal 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 Content, and can update the page number and adjust the scrollbar elevator position.  See SCROLLBAR (WIDGET(3W) for more details.  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. 

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. 

Sun Release 4.0  —  Last change: 1/8/90