XmScrolledWindow(3X) SDK X11 R4.11MU05 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 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 |
+------------------------------+-------------------------------+----------------+-----------------------+--------+
|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 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.
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.
+--------------------------------------------------------------------------------------------------+
| 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.
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 traversaldestination;
XmTraversalDirectiondirection;
} XmTraverseObscuredCallbackStruct;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
traversaldestination
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.
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.
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).
Licensed material--property of copyright holder(s)