XmScrolledWindow - The ScrolledWindow widget class
#include <Xm/ScrolledW.h>
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.
ScrolledWindow inherits behavior and resources from Core, Composite, Constraint, and XmManager Classes.
The class pointer is xmScrolledWindowWidgetClass.
The class name is XmScrolledWindow.
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).
| 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 |
The default value may depend on the value of the XmNstringDirection resource.
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 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.
NOTE: This resource must be set to the desired policy at the time the ScrolledWindow is created. It cannot be changed through SetValues.
ScrolledWindow inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass.
| 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 |
| Name | Class | Type | Default | Access |
|---|---|---|---|---|
| XmNchildren | XmCReadOnly | WidgetList | NULL | G |
| XmNinsertPosition | XmCInsertPosition | XtOrderProc | NULL | CSG |
| XmNnumChildren | XmCReadOnly | Cardinal | 0 | G |
| 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 |
| 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 |
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 traversal_destination;
XmTraversalDirection direction;
} XmTraverseObscuredCallbackStruct;
XmScrolledWindow includes the translations from XmManager.
This widget has the additional behavior described below:
Certain applications will want to replace the page bindings with ones that are specific to the content of the scrolled area.
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 procedure 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 examines the ScrollBars to see which (if any) are managed, allocates a portion 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 calculations. 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.
The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3X).
Composite(3X), Constraint(3X), Core(3X), XmCreateScrolledWindow(3X), XmManager(3X), XmProcessTraversal(3X), XmScrollBar(3X), XmScrollVisible(3X), and XmScrolledWindowSetAreas(3X).