XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
NAME
XmScrolledWindow-The ScrolledWindow widget class
SYNOPSIS
#include <Xm/ScrolledW.h>
DESCRIPTION
The ScrolledWindow widget combines one or two ScrollBar
widgets and a viewing area to implement a visible window
onto some other (usually larger) data display. The visible
part of the window can be scrolled through the larger
display by the use of ScrollBars.
To use ScrolledWindow, an application first creates a
ScrolledWindow widget, any needed ScrollBar widgets, and a
widget capable of displaying any desired data as the work
area of ScrolledWindow. ScrolledWindow positions the work
area widget and displays the ScrollBars if so requested.
When the user performs some action on the ScrollBar, the
application is notified through the normal ScrollBar
callback interface.
ScrolledWindow can be configured to operate automatically so
that it performs all scrolling and display actions with no
need for application program involvement. It can also be
configured to provide a minimal support framework in which
the application is responsible for processing all user input
and making all visual changes to the displayed data in
response to that input.
When ScrolledWindow is performing automatic scrolling it
creates a clipping window and automatically creates the
scroll bars. Conceptually, this window becomes the viewport
through which the user examines the larger underlying data
area. The application simply creates the desired data, then
makes that data the work area of the ScrolledWindow. When
the user moves the slider to change the displayed data, the
workspace is moved under the viewing area so that a new
portion of the data becomes visible.
Sometimes it is impractical for an application to create a
large data space and simply display it through a small
clipping window. For example, in a text editor, creating a
single data area that consisted of a large file would
involve an undesirable amount of overhead. The application
needs to use a ScrolledWindow (a small viewport onto some
larger data), but needs to be notified when the user
scrolled the viewport so it could bring in more data from
storage and update the display area. For these cases the
ScrolledWindow can be configured so that it provides only
visual layout support. No clipping window is created, and
1 (printed 6/8/92)
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
the application must maintain the data displayed in the work
area, as well as respond to user input on the ScrollBars.
The user can specify resources in a resource file for the
automatically created widgets that contain the horizontal
and vertical scrollbars of the ScrolledWindow widget. The
names of these widgets are "HorScrollBar" and
"VertScrollBar", and remain consistent whether created by
XmCreateScrolledList, XmCreateScrolledText or
XmCreateScrolledWindow.
Classes
ScrolledWindow inherits behavior and resources from Core,
Composite, Constraint, and XmManager Classes.
The class pointer is xmScrolledWindowWidgetClass.
The class name is XmScrolledWindow.
New Resources
The following table defines a set of widget resources used
by the programmer to specify data. The programmer can also
set the resource values for the inherited classes to set
attributes for this widget. To reference a resource by name
or by class in a .Xdefaults file, remove the XmN or XmC
prefix and use the remaining letters. To specify one of the
defined values for a resource in a .Xdefaults file, remove
the Xm prefix and use the remaining letters (in either
lowercase or uppercase, but include any underscores between
words). The codes in the access column indicate if the
given resource can be set at creation time (C), set by using
XtSetValues (S), retrieved by using XtGetValues (G), or is
not applicable (N/A).
XmScrolledWindow Resource Set
Name Class Type Default Access
_______________________________________________________________________________________________________________
XmNclipWindow XmCClipWindow Widget dynamic G
XmNhorizontalScrollBar XmCHorizontalScrollBar Widget dynamic CSG
XmNscrollBarDisplayPolicy XmCScrollBarDisplayPolicy unsigned char dynamic CSG
XmNscrollBarPlacement XmCScrollBarPlacement unsigned char XmBOTTOM_RIGHT CSG
XmNscrolledWindowMarginHeight XmCScrolledWindowMarginHeight Dimension 0 CSG
XmNscrolledWindowMarginWidth XmCScrolledWindowMarginWidth Dimension 0 CSG
XmNscrollingPolicy XmCScrollingPolicy unsigned char XmAPPLICATION_DEFINED CG
XmNspacing XmCSpacing Dimension 4 CSG
XmNtraverseObscuredCallback XmCCallback XtCallbackList NULL CSG
XmNverticalScrollBar XmCVerticalScrollBar Widget dynamic CSG
XmNvisualPolicy XmCVisualPolicy unsigned char dynamic G
2 (printed 6/8/92)
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
XmNworkWindow XmCWorkWindow Widget NULL CSG
XmNclipWindow
Specifies the widget ID of the clipping area.
This is automatically created by ScrolledWindow
when the XmNvisualPolicy resource is set to
XmCONSTANT and can only be read by the
application. Any attempt to set this resource to
a new value causes a warning message to be printed
by the scrolled window. If the XmNvisualPolicy
resource is set to XmVARIABLE, this resource is
set to NULL, and no clipping window is created.
XmNhorizontalScrollBar
Specifies the widget ID of the horizontal
ScrollBar. This is automatically created by
ScrolledWindow when the XmNscrollingPolicy is
initialized to XmAUTOMATIC; otherwise, the default
is NULL.
XmNscrollBarDisplayPolicy
Controls the automatic placement of the
ScrollBars. If it is set to XmASNEEDED and if
XmNscrollingPolicy is set to XmAUTOMATIC,
ScrollBars are displayed only if the workspace
exceeds the clip area in one or both dimensions.
A resource value of XmSTATIC causes the
ScrolledWindow to display the ScrollBars whenever
they are managed, regardless of the relationship
between the clip window and the work area. This
resource must be XmSTATIC when XmNscrollingPolicy
is XmAPPLICATIONDEFINED. The default is
XmASNEEDED when XmNscrollingPolicy is
XmAUTOMATIC, and XmSTATIC otherwise.
XmNscrollBarPlacement
Specifies the positioning of the ScrollBars in
relation to the work window. The following are
the values:
⊕ XmTOPLEFT-The horizontal ScrollBar is placed
above the work window; the vertical ScrollBar
to the left.
⊕ XmBOTTOMLEFT-The horizontal ScrollBar is
placed below the work window; the vertical
ScrollBar to the left.
⊕ XmTOPRIGHT-The horizontal ScrollBar is
placed above the work window; the vertical
3 (printed 6/8/92)
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
ScrollBar to the right.
⊕ XmBOTTOMRIGHT-The horizontal ScrollBar is
placed below the work window; the vertical
ScrollBar to the right.
The default value may depend on the value of the
XmNstringDirection resource.
XmNscrolledWindowMarginHeight
Specifies the margin height on the top and bottom
of the ScrolledWindow.
XmNscrolledWindowMarginWidth
Specifies the margin width on the right and left
sides of the ScrolledWindow.
XmNscrollingPolicy
Performs automatic scrolling of the work area with
no application interaction. If the value of this
resource is XmAUTOMATIC, ScrolledWindow
automatically creates the ScrollBars; attaches
callbacks to the ScrollBars; sets the visual
policy to XmCONSTANT; and automatically moves the
work area through the clip window in response to
any user interaction with the ScrollBars. An
application can also add its own callbacks to the
ScrollBars. This allows the application to be
notified of a scroll event without having to
perform any layout procedures.
NOTE: Since the ScrolledWindow adds callbacks to
the ScrollBars, an application should not perform
an XtRemoveAllCallbacks on any of the ScrollBar
widgets.
When XmNscrollingPolicy is set to
XmAPPLICATIONDEFINED, the application is
responsible for all aspects of scrolling. The
ScrollBars must be created by the application, and
it is responsible for performing any visual
changes in the work area in response to user
input.
This resource must be set to the desired policy at
the time the ScrolledWindow is created. It cannot
be changed through SetValues.
XmNspacing
Specifies the distance that separates the
ScrollBars from the work window.
4 (printed 6/8/92)
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
XmNtraverseObscuredCallback
Specifies a list of callbacks that is called when
traversing to a widget or gadget that is obscured
due to its position in the work area relative to
the location of the ScrolledWindow viewport. This
resource is valid only when XmNscrollingPolicy is
XmAUTOMATIC. If this resource is NULL, an
obscured widget cannot be traversed to. The
callback reason is XmCROBSCUREDTRAVERSAL.
XmNverticalScrollBar
Specifies the widget ID of the vertical ScrollBar.
This is automatically created by ScrolledWindow
when the XmNscrollingPolicy is initialized to
XmAUTOMATIC; otherwise, the default is NULL.
XmNvisualPolicy
Grows the ScrolledWindow to match the size of the
work area, or it can be used as a static viewport
onto a larger data space. If the visual policy is
XmVARIABLE, the ScrolledWindow forces the
ScrollBar display policy to XmSTATIC and allow the
work area to grow or shrink at any time and
adjusts its layout to accommodate the new size.
When the policy is XmCONSTANT, the work area grows
or shrinks as requested, but a clipping window
forces the size of the visible portion to remain
constant. The only time the viewing area can grow
is in response to a resize from the
ScrolledWindow's parent. The default is
XmCONSTANT when XmNscrollingPolicy is XmAUTOMATIC,
and XmVARIABLE otherwise.
NOTE: This resource must be set to the desired
policy at the time the ScrolledWindow is created.
It cannot be changed through SetValues.
XmNworkWindow
Specifies the widget ID of the viewing area.
Inherited Resources
ScrolledWindow inherits behavior and resources from the
following superclasses. For a complete description of each
resource, refer to the man page for that superclass.
5 (printed 6/8/92)
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
XmManager Resource Set
Name Class Type Default Access
_________________________________________________________________________________________________
XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCHighlightColor Pixel dynamic CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNinitialFocus XmCInitialFocus Widget NULL CSG
XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG
XmNshadowThickness XmCShadowThickness Dimension dynamic CSG
XmNstringDirection XmCStringDirection XmStringDirection dynamic CG
XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG
XmNtraversalOn XmCTraversalOn Boolean True CSG
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData XtPointer NULL CSG
Composite Resource Set
Name Class Type Default Access
______________________________________________________________________
XmNchildren XmCReadOnly WidgetList NULL G
XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG
XmNnumChildren XmCReadOnly Cardinal 0 G
Core Resource Set
Name Class Type Default Access
______________________________________________________________________________________________________________
XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG
XmNancestorSensitive XmCSensitive Boolean dynamic G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap dynamic CG
XmNdepth XmCDepth int dynamic CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension dynamic CSG
XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Screen * dynamic CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations dynamic CSG
XmNwidth XmCWidth Dimension dynamic CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Callback Information
The application must use the ScrollBar callbacks to be
notified of user input.
6 (printed 6/8/92)
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
ScrolledWindow defines a callback structure for use with
XmNtraverseObscuredCallback callbacks. The
XmNtraverseObscuredCallback resource provides a mechanism
for traversal to obscured widgets (or gadgets) due to their
position in the work area of a ScrolledWindow. The
XmNtraverseObscuredCallback routine has responsibility for
adjusting the position of the work area such that the
specified traversal destination widget is positioned within
the viewport of the ScrolledWindow. A NULL
XmNtraverseObscuredCallback resource causes obscured widgets
within the ScrolledWindow to be non-traversable.
Traversal to an obscured widget or gadget requires these
conditions to be met: the widget or gadget can be obscured
only due to its position in the work area of a
ScrolledWindow relative to the viewport; the viewport of the
associated ScrolledWindow is fully visible, or can be made
so by virtue of ancestral XmNtraverseObscuredCallback
routines; and the XmNtraverseObscuredCallback resource must
be non-NULL.
When ScrolledWindow widgets are nested, the
XmNtraverseObscuredCallback routine for each ScrolledWindow
that obscures the traversal destination is called in
ascending order within the given hierarchy.
A pointer to the following structure is passed to callbacks
for XmNtraverseObscuredCallback.
typedef struct
{
int reason;
XEvent *event:
Widget traversal_destination;
XmTraversalDirectiondirection;
} XmTraverseObscuredCallbackStruct;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
traversal_destination
Specifies the widget or gadget to traverse to, which
will be a descendant of the work window.
direction
Specifies the direction of traversal. See the
description of the direction parameter in the
XmProcessTraversal man page for an explanation of the
valid values.
7 (printed 6/8/92)
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
Translations
XmScrolledWindow includes the translations from XmManager.
Additional Behavior
This widget has the additional behavior described below:
KPageUp: If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window up the height of the viewport. The
distance scrolled may be reduced to provide some
overlap. The actual distance scrolled depends on
the XmNpageIncrement resource of the vertical
ScrollBar.
KPageDown:
If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window down the height of the viewport. The
distance scrolled may be reduced to provide some
overlap. The actual distance scrolled depends on
the XmNpageIncrement resource of the vertical
ScrollBar.
KPageLeft:
If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window left the width of the viewport. The
distance scrolled may be reduced to provide some
overlap. The actual distance scrolled depends on
the XmNpageIncrement resource of the horizontal
ScrollBar.
KPageRight:
If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window right the width of the viewport. The
distance scrolled may be reduced to provide some
overlap. The actual distance scrolled depends on
the XmNpageIncrement resource of the horizontal
ScrollBar.
KBeginLine:
If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window horizontally to the edge corresponding to
the horizontal ScrollBar's minimum value.
KEndLine: If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window horizontally to the edge corresponding to
the horizontal ScrollBar's maximum value.
8 (printed 6/8/92)
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
KBeginData:
If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window vertically to the edge corresponding to the
vertical ScrollBar's minimum value.
KEndData: If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window vertically to the edge corresponding to the
vertical ScrollBar's maximum value.
Certain applications will want to replace the page bindings
with ones that are specific to the content of the scrolled
area.
Virtual Bindings
The bindings for virtual keys are vendor specific. For
information about bindings for virtual buttons and keys, see
VirtualBindings(3X).
RELATED INFORMATION
Composite(3X), Constraint(3X), Core(3X),
XmCreateScrolledWindow(3X), XmManager(3X),
XmProcessTraversal(3X), XmScrollBar(3X),
XmScrollVisible(3X), and XmScrolledWindowSetAreas(3X).
9 (printed 6/8/92)