XmScrolledWindow(3X)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
Class: XmCClipWindow
Default: dynamic
Type: Widget
Access: G
Class: XmCHorizontalScrollBar
Default: dynamic
Type: Widget
Access: CSG
Class: XmCScrollBarDisplayPolicy
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCScrollBarPlacement
Default: XmBOTTOM_RIGHT
Type: unsigned char
Access: CSG
Class: XmCScrolledWindowMarginHeight
Default: 0
Type: Dimension
Access: CSG
Class: XmCScrolledWindowMarginWidth
Default: 0
Type: Dimension
Access: CSG
Class: XmCScrollingPolicy
Default: XmAPPLICATION_DEFINED
Type: unsigned char
Access: CG
Class: XmCSpacing
Default: 4
Type: Dimension
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: CSG
Class: XmCVerticalScrollBar
Default: dynamic
Type: Widget
Access: CSG
Class: XmCVisualPolicy
Default: dynamic
Type: unsigned char
Access: G
Class: XmCWorkWindow
Default: NULL
Type: Widget
Access: CSG
Specifies the widget ID of the clipping area. This is automati‐
cally created by ScrolledWindow when the XmNvisualPolicy
resource is set to XmCONSTANT and can only be read by the appli‐
cation. 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. Specifies the
widget ID of the horizontal ScrollBar. This is automatically
created by ScrolledWindow when the XmNscrollingPolicy is ini‐
tialized to XmAUTOMATIC; otherwise, the default is NULL. Con‐
trols 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 rela‐
tion to the work window. The following are the values:
XmTOP_LEFT--The horizontal 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 verti‐
cal ScrollBar to the left. XmTOP_RIGHT--The horizontal Scroll‐
Bar 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 XmNstringDirec‐
tion resource. Specifies the margin height on the top and bot‐
tom 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 auto‐
matically creates the ScrollBars; attaches callbacks to the
ScrollBars; sets the visual policy to XmCONSTANT; and automati‐
cally 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
application is responsible for all aspects of scrolling. The
ScrollBars must be created by the application, and it is respon‐
sible 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 SetVal‐
ues. Specifies the distance that separates the ScrollBars from
the work window. 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 XmN‐
scrollingPolicy is XmAUTOMATIC. If this resource is NULL, an
obscured widget cannot be traversed to. The callback reason 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; oth‐
erwise, the default is NULL. Grows the ScrolledWindow to match
the size of the work area, or it can be used as a static view‐
port onto a larger data space. If the visual policy is XmVARI‐
ABLE, 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 par‐
ent. The default is XmCONSTANT when XmNscrollingPolicy is XmAU‐
TOMATIC, 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 SetVal‐
ues. 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
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCInitialFocus
Default: NULL
Type: Widget
Access: CSG
Class: XmCNavigationType
Default: XmTAB_GROUP
Type: XmNavigationType
Access: CSG
Class: XmCShadowThickness
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCStringDirection
Default: dynamic
Type: XmStringDirection
Access: CG
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCTraversalOn
Default: True
Type: Boolean
Access: CSG
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Composite Resource Set
Class: XmCReadOnly
Default: NULL
Type: WidgetList
Access: G
Class: XmCInsertPosition
Default: NULL
Type: XtOrderProc
Access: CSG
Class: XmCReadOnly
Default: 0
Type: Cardinal
Access: G
Core Resource Set
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: CSG
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
Class: XmCScreen
Default: dynamic
Type: Screen *
Access: CG
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
Access: CSG
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
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;
XmTraversalDirection direction; } XmTraverseObscuredCallbackStruct;
Indicates why the callback was invoked. Points to the XEvent that
triggered the callback. Specifies the widget or gadget to traverse 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(3X) man page for an explanation of the valid values.
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 overlap.
The actual distance scrolled depends on the XmNpageIncrement resource
of the vertical ScrollBar. 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. 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 XmN‐
pageIncrement resource of the horizontal ScrollBar. If XmNscrolling‐
Policy is XmAUTOMATIC, scrolls the window right the width of the view‐
port. 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 XmAUTOMATIC,
scrolls the window horizontally to the edge corresponding to the hori‐
zontal 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 XmAUTO‐
MATIC, scrolls the window vertically to the edge corresponding to the
vertical ScrollBar's minimum value. If XmNscrollingPolicy is XmAUTO‐
MATIC, 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).
SEE ALSOComposite(3X), Constraint(3X), Core(3X), XmCreateScrolledWindow(3X),
XmManager(3X), XmProcessTraversal(3X), XmScrollBar(3X), XmScrollVisi‐
ble(3X), XmScrolledWindowSetAreas(3X)XmScrolledWindow(3X)
