NAME

XmScrolledWindow — the ScrolledWindow widget class. 

SYNOPSIS

#include <Xm/ScrolledW.h>

DESCRIPTION

The ScrolledWindow widget combines one or more 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 will position the work area widget and display the ScrollBars if so requested.  When the user performs some action on the ScrollBar, the application will be notified through the normal ScrollBar callback interface. 

ScrolledWindow can be configured to operate in an automatic manner 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 will create a clipping window.  Conceptually, this window becomes the view port 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. 

There are instances where it is impractical for an application to create a large data space and simply display it through a small clipping window.  An example of this is a text editor — there would be an undesirable amount of overhead involved with creating a single data area that consisted of a large file.  The application would want to use the concept of a ScrolledWindow (a small viewport onto some larger data), but would want 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. 

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 lower case or upper case, 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). 

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 will cause 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.

XmNscrollBarDisplayPolicy
Controls the automatic placement of the ScrollBars.  If it is set to XmAS_NEEDED and if XmNscrollingPolicy is set to XmAUTOMATIC, ScrollBars will only be displayed if the workspace exceeds the clip area in one or both dimensions.  A resource value of XmSTATIC will cause 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. 

XmNscrollBarPlacement
Specifies the positioning of the ScrollBars in relation to the work window.  The following are the values:

•XmTOP_LEFT — The horizontal ScrollBar is placed above the work window and the vertical ScrollBar to the left of the  work window. 

•XmBOTTOM_LEFT — The horizontal ScrollBar is placed below the work window and the vertical ScrollBar to the left of the work window. 

•XmTOP_RIGHT — The horizontal ScrollBar is placed above the work window and the vertical ScrollBar to the right of the  work window. 

•XmBOTTOM_RIGHT — The horizontal ScrollBar is placed below the work window and the vertical ScrollBar to the right of the  work window. 

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 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. 

XmNspacing
Specifies the distance that separates the ScrollBars from the work window.

XmNverticalScrollBar
Specifies the widget ID of the vertical ScrollBar.

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 will force the ScrollBar display policy to XmSTATIC and allow the work area to grow or shrink at any time and will adjust its layout to accommodate the new size.  When the policy is XmCONSTANT, the work area will be allowed to grow or shrink as requested, but a clipping window will force 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. 

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 these resources, refer to the man page for that superclass. 

Callback Information

ScrolledWindow defines no new callback structures.  The application must use the ScrollBar callbacks to be notified of user input. 

Behavior

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 are necessary, such as managing or unmanaging a ScrollBar.  The query procedure performs whatever actions that 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 would just enclose the WorkWindow.  By using this mechanism, an application can size the ScrolledWindow so that it only needs to display a ScrollBar 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 will determine the minimum value for the other dimension that will just enclose the WorkWindow, fill in the appropriate elements in the reply structure, and return to the calling program.  Occasionally, using the specified width or height and the other minimum dimension would result in neither ScrollBar appearing.  When this happens, the query procedure will set both the width and height fields, indicating that in this situation the ideal size would cause a change in both dimensions.  If the calling application sets both the width and height fields, the ScrolledWindow will determine the minimum size for both dimensions and return those values in the reply structure. 

Keyboard Traversal

For information on keyboard traversal, see the man page for XmManager(3Xm) and its sections on behavior and default translations. 

RELATED INFORMATION

Composite(3Xm), Constraint(3Xm), Core(3Xm), XmCreateScrolledWindow(3Xm), XmManager(3Xm), and XmScrolledWindowSetAreas(3Xm). 

7th Edition