XmScrolledWindow(3X) OSF/Motif XmScrolledWindow(3X)NAMEXmScrolledWindow - 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 display‐
ing any desired data as the work area of ScrolledWindow. ScrolledWin‐
dow 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 inter‐
face.
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 process‐
ing 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. Conceptu‐
ally, 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 exam‐
ple, in a text editor, creating a single data area that consisted of a
large file would involve an undesirable amount of overhead. The appli‐
cation 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 pro‐
vides only visual layout support. No clipping window is created, and
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 "HorScroll‐
Bar" 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 pro‐
grammer to specify data. The programmer can also set the resource val‐
ues 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 Default Access
Class Type
─────────────────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────────────────
XmNclipWindow dynamic G
XmCClipWindow Widget
─────────────────────────────────────────────────────────────────────
XmNhorizontalScrollBar dynamic CSG
XmCHorizontalScrollBar Widget
─────────────────────────────────────────────────────────────────────
XmNscrollBarDisplayPolicy dynamic CSG
XmCScrollBarDisplayPolicy unsigned char
─────────────────────────────────────────────────────────────────────
XmNscrollBarPlacement XmBOTTOM_RIGHT CSG
XmCScrollBarPlacement unsigned char
─────────────────────────────────────────────────────────────────────
XmNscrolledWindowMarginHeight 0 CSG
XmCScrolledWindowMarginHeight Dimension
─────────────────────────────────────────────────────────────────────
XmNscrolledWindowMarginWidth 0 CSG
XmCScrolledWindowMarginWidth Dimension
─────────────────────────────────────────────────────────────────────
XmNscrollingPolicy XmAPPLICATION_DEFINED CG
XmCScrollingPolicy unsigned char
─────────────────────────────────────────────────────────────────────
XmNspacing 4 CSG
XmCSpacing Dimension
─────────────────────────────────────────────────────────────────────
XmNtraverseObscuredCallback NULL CSG
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────────
XmNverticalScrollBar dynamic CSG
XmCVerticalScrollBar Widget
─────────────────────────────────────────────────────────────────────
XmNvisualPolicy dynamic G
XmCVisualPolicy unsigned char
─────────────────────────────────────────────────────────────────────
XmNworkWindow NULL CSG
XmCWorkWindow Widget
─────────────────────────────────────────────────────────────────────
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 XmVARI‐
ABLE, this resource is set to NULL, and no clipping window is created.
Specifies the widget ID of the horizontal ScrollBar. This is automati‐
cally created by ScrolledWindow when the XmNscrollingPolicy is initial‐
ized to XmAUTOMATIC; otherwise, the default is NULL. Controls the
automatic placement of the ScrollBars. If it is set to XmAS_NEEDED 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 XmAPPLICATION_DEFINED. The default
is XmAS_NEEDED when XmNscrollingPolicy is XmAUTOMATIC, and XmSTATIC
otherwise. Specifies the positioning of the ScrollBars in relation to
the work window. The following are the values: XmTOP_LEFT—The horizon‐
tal ScrollBar is placed above the work window; the vertical ScrollBar
to the left. XmBOTTOM_LEFT—The horizontal ScrollBar is placed below
the work window; the vertical ScrollBar to the left. XmTOP_RIGHT—The
horizontal ScrollBar is placed above the work window; the vertical
ScrollBar to the right. XmBOTTOM_RIGHT—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. Specifies the margin height on the top and bottom of the
ScrolledWindow. Specifies the margin width on the right and left sides
of the ScrolledWindow. 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 XmCON‐
STANT; 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 XmAPPLICATION_DEFINED, the applica‐
tion 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.
Specifies the distance that separates the ScrollBars from the work win‐
dow. 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 rea‐
son is XmCR_OBSCURED_TRAVERSAL. Specifies the widget ID of the verti‐
cal ScrollBar. This is automatically created by ScrolledWindow when
the XmNscrollingPolicy is initialized to XmAUTOMATIC; otherwise, the
default is NULL. 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 vis‐
ible 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.
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.
XmManager Resource Set
────────────────────────────────────────────────────────────────
Name Default Access
Class Type
────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────
XmNbottomShadowColor dynamic CSG
XmCBottomShadowColor Pixel
────────────────────────────────────────────────────────────────
XmNbottomShadowPixmap XmUNSPECIFIED_PIXMAP CSG
XmCBottomShadowPixmap Pixmap
────────────────────────────────────────────────────────────────
XmNforeground dynamic CSG
XmCForeground Pixel
────────────────────────────────────────────────────────────────
XmNhelpCallback NULL C
XmCCallback XtCallbackList
────────────────────────────────────────────────────────────────
XmNhighlightColor dynamic CSG
XmCHighlightColor Pixel
────────────────────────────────────────────────────────────────
XmNhighlightPixmap dynamic CSG
XmCHighlightPixmap Pixmap
────────────────────────────────────────────────────────────────
XmNinitialFocus NULL CSG
XmCInitialFocus Widget
────────────────────────────────────────────────────────────────
XmNnavigationType XmTAB_GROUP CSG
XmCNavigationType XmNavigationType
────────────────────────────────────────────────────────────────
XmNshadowThickness dynamic CSG
XmCShadowThickness Dimension
────────────────────────────────────────────────────────────────
XmNstringDirection dynamic CG
XmCStringDirection XmStringDirection
────────────────────────────────────────────────────────────────
XmNtopShadowColor dynamic CSG
XmCTopShadowColor Pixel
────────────────────────────────────────────────────────────────
XmNtopShadowPixmap dynamic CSG
XmCTopShadowPixmap Pixmap
────────────────────────────────────────────────────────────────
XmNtraversalOn True CSG
XmCTraversalOn Boolean
────────────────────────────────────────────────────────────────
XmNunitType dynamic CSG
XmCUnitType unsigned char
────────────────────────────────────────────────────────────────
XmNuserData NULL CSG
XmCUserData XtPointer
────────────────────────────────────────────────────────────────
Composite Resource Set
──────────────────────────────────────────────────────
Name Default Access
Class Type
──────────────────────────────────────────────────────
──────────────────────────────────────────────────────
XmNchildren NULL G
XmCReadOnly WidgetList
──────────────────────────────────────────────────────
XmNinsertPosition NULL CSG
XmCInsertPosition XtOrderProc
──────────────────────────────────────────────────────
XmNnumChildren 0 G
XmCReadOnly Cardinal
──────────────────────────────────────────────────────
Core Resource Set
─────────────────────────────────────────────────────────────────────
Name Default Access
Class Type
─────────────────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────────────────
XmNaccelerators dynamic CSG
XmCAccelerators XtAccelerators
─────────────────────────────────────────────────────────────────────
XmNancestorSensitive dynamic G
XmCSensitive Boolean
─────────────────────────────────────────────────────────────────────
XmNbackground dynamic CSG
XmCBackground Pixel
─────────────────────────────────────────────────────────────────────
XmNbackgroundPixmap XmUNSPECIFIED_PIXMAP CSG
XmCPixmap Pixmap
─────────────────────────────────────────────────────────────────────
XmNborderColor XtDefaultForeground CSG
XmCBorderColor Pixel
─────────────────────────────────────────────────────────────────────
XmNborderPixmap XmUNSPECIFIED_PIXMAP CSG
XmCPixmap Pixmap
─────────────────────────────────────────────────────────────────────
XmNborderWidth 0 CSG
XmCBorderWidth Dimension
─────────────────────────────────────────────────────────────────────
XmNcolormap dynamic CG
XmCColormap Colormap
─────────────────────────────────────────────────────────────────────
XmNdepth dynamic CG
XmCDepth int
─────────────────────────────────────────────────────────────────────
XmNdestroyCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────────
XmNheight dynamic CSG
XmCHeight Dimension
─────────────────────────────────────────────────────────────────────
XmNinitialResourcesPersistent True C
XmCInitialResourcesPersistent Boolean
─────────────────────────────────────────────────────────────────────
XmNmappedWhenManaged True CSG
XmCMappedWhenManaged Boolean
─────────────────────────────────────────────────────────────────────
XmNscreen dynamic CG
XmCScreen Screen *
─────────────────────────────────────────────────────────────────────
XmNsensitive True CSG
XmCSensitive Boolean
─────────────────────────────────────────────────────────────────────
XmNtranslations dynamic CSG
XmCTranslations XtTranslations
─────────────────────────────────────────────────────────────────────
XmNwidth dynamic CSG
XmCWidth Dimension
─────────────────────────────────────────────────────────────────────
XmNx 0 CSG
XmCPosition Position
─────────────────────────────────────────────────────────────────────
XmNy 0 CSG
XmCPosition Position
─────────────────────────────────────────────────────────────────────
Callback Information
The application must use the ScrollBar callbacks to be notified of user
input.
ScrolledWindow defines a callback structure for use with XmNtraverseOb‐
scuredCallback callbacks. The XmNtraverseObscuredCallback resource pro‐
vides a mechanism for traversal to obscured widgets (or gadgets) due to
their position in the work area of a ScrolledWindow. The XmNtra‐
verseObscuredCallback 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 XmNtra‐
verseObscuredCallback. typedef struct { int reason;
XEvent *event:
Widget traversal_destination;
XmTraversalDirectiondirection; } XmTraverseObscuredCallback‐
Struct; Indicates why the callback was invoked. Points to the XEvent
that triggered the callback. Specifies the widget or gadget to tra‐
verse to, which will be a descendant of the work window. Specifies the
direction of traversal. See the description of the direction parameter
in the XmProcessTraversal man page for an explanation of the valid val‐
ues.
Translations
XmScrolledWindow includes the translations from XmManager.
Additional Behavior
This widget has the additional behavior described below: If XmN‐
scrollingPolicy is XmAUTOMATIC, scrolls the window up the height of the
viewport. The distance scrolled may be reduced to provide some over‐
lap. The actual distance scrolled depends on the XmNpageIncrement
resource of the vertical ScrollBar. If XmNscrollingPolicy is XmAUTO‐
MATIC, scrolls the window down the height of the viewport. The dis‐
tance scrolled may be reduced to provide some overlap. The actual dis‐
tance scrolled depends on the XmNpageIncrement resource of the vertical
ScrollBar. 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. If XmN‐
scrollingPolicy 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. If XmNscrollingPolicy is XmAUTO‐
MATIC, scrolls the window horizontally to the edge corresponding to the
horizontal ScrollBar's minimum value. If XmNscrollingPolicy is XmAUTO‐
MATIC, scrolls the window horizontally to the edge corresponding to the
horizontal ScrollBar's maximum value.
If XmNscrollingPolicy is XmAUTOMATIC, scrolls the window vertically to
the edge corresponding to the vertical ScrollBar's minimum value. 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.
Geometry Management
ScrolledWindow makes extensive use of the XtQueryGeometry functionality
to facilitate geometry communication between application levels. In
the XmAPPLICATION_DEFINED scrolling policy, the WorkWindow's query pro‐
cedure is called by the ScrolledWindow whenever the ScrolledWindow is
going to change its size. The widget calculates the largest possible
workspace area and passes this size to the WorkWindow widget's query
procedure. The query procedure can then examine this new size and
determine if any changes, such as managing or unmanaging a ScrollBar,
are necessary. The query procedure performs whatever actions it needs
and then returns to the ScrolledWindow. The ScrolledWindow then exam‐
ines the ScrollBars to see which (if any) are managed, allocates a por‐
tion of the visible space for them, and resizes the WorkWindow to fit
in the rest of the space.
When the scrolling policy is XmCONSTANT, the ScrolledWindow can be
queried to return the optimal size for a given dimension. The optimal
size is defined to be the size that just encloses the WorkWindow. By
using this mechanism, an application can size the ScrolledWindow so
that it needs to display a ScrollBar only for one dimension. When the
ScrolledWindow's query procedure is called via XtQueryGeometry, the
request is examined to see if the width or height has been specified.
If so, the routine uses the given dimension as the basis for its calcu‐
lations. It determines the minimum value for the other dimension that
just encloses the WorkWindow, fills in the appropriate elements in the
reply structure, and returns to the calling program. Occasionally,
using the specified width or height and the other minimum dimension
results in neither ScrollBar appearing. When this happens, the query
procedure sets both the width and height fields, indicating that in
this situation the ideal size causes a change in both dimensions. If
the calling application sets both the width and height fields, the
ScrolledWindow determines the minimum size for both dimensions and
return those values in the reply structure.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information
about bindings for virtual buttons and keys, see VirtualBindings(3X).
RELATED INFORMATIONComposite(3X), Constraint(3X), Core(3X), XmCreateScrolledWindow(3X),
XmManager(3X), XmProcessTraversal(3X), XmScrollBar(3X), XmScrollVisi‐
ble(3X), and XmScrolledWindowSetAreas(3X).
XmScrolledWindow(3X)
