XmScrolledWindow(3X) UNIX System V 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 display 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. 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.
Classes
ScrolledWindow inherits behavior and resources from Core, Composite,
Constraint, and XmManager Classes.
10/89 Page 1
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
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 |
|_____________________________|_______________________________|_______________|_______________________|________|
|XmNverticalScrollBar | XmCVerticalScrollBar | Widget | dynamic | CSG |
|_____________________________|_______________________________|_______________|_______________________|________|
|XmNvisualPolicy | XmCVisualPolicy | unsigned char| dynamic | CG |
|_____________________________|_______________________________|_______________|_______________________|________|
|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
Page 2 10/89
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
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 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
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:
⊕ 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 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.
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,
10/89 Page 3
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
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. 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.
Page 4 10/89
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
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 |
|_____________________|_____________________________|___________________|______________________|________|
|XmNnavigationType | XmCNavigationType | XmNavigationType | XmTAB_GROUP | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNshadowThickness | XmCShadowThickness | Dimension | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNstringDirection | XmCStringDirection | XmStringDirection| dynamic | CG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNtopShadowColor | XmCBackgroundTopShadowColor| Pixel | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNtraversalOn | XmCTraversalOn | Boolean | True | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNunitType | XmCUnitType | unsigned char | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNuserData | XmCUserData | Pointer | NULL | CSG |
|_____________________|_____________________________|___________________|______________________|________|
_______________________________________________________________________
Composite Resource Set
_______________________________________________________________________
Name Class Type Default Access
_______________________________________________________________________
_______________________________________________________________________
XmNchildren XmCReadOnly WidgetList NULL G
_______________________________________________________________________
XmNinsertPosition XmCInsertPosition (*)() NULL CSG
_______________________________________________________________________
XmNnumChildren XmCReadOnly Cardinal 0 G
_______________________________________________________________________
10/89 Page 5
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
| | | | | |
___|__________________|___________________|____________|_________|________|_____________________________________
| | | | Core Resource Set | | |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|Name | | Class | | | Type | | Default | Access|
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|accelerators | | XmCAcceler
|ators | | X
|tAccelera
|tors| dynamic | CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|ancestorSensitive | | XmCSensiti
|ve | | B
|oolean | | dynamic | G |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|background | | XmCBackgro
|und | | P
|ixel | | dynamic | CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|backgroundPixmap | | XmCPixmap| | | P
|ixmap | | XmUNSPECIFIED_PIXMAP| CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|borderColor | | XmCBorderC
|olor | | P
|ixel | | XtDefaultForeground | CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|borderPixmap | | XmCPixmap| | | P
|ixmap | | XmUNSPECIFIED_PIXMAP| CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|borderWidth | | XmCBorderW
|idth | | D
|imension| | 0 | CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|colormap | | XmCColorma
|p | | C
|olormap | | dynamic | CG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|depth | | XmCDepth | | | i
|nt | | dynamic | CG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|destroyCallback | | XmCCallbac
|k | | X
|tCallback
|List| NULL | C |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|height | | XmCHeight| | | D
|imension| | dynamic | CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|initialResourcesPer
|sistent| XmCInitial
|ResourcesPers
|istent| B
|oolean | | True | C |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|mappedWhenManaged | | XmCMappedW
|henManaged | | B
|oolean | | True | CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|screen | | XmCScreen| | | S
|creen * | | dynamic | CG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|sensitive | | XmCSensiti
|ve | | B
|oolean | | True | CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|translations | | XmCTransla
|tions | | X
|tTranslat
|ions| dynamic | CSG |
|__|__________________|_______|___________|____________|______|__|________|____|______________________|________|
|XmN
|width | | XmCWidth | | | D
|imension| | dynamic | CSG |
|_____________________|_______|___________|____________|______|__|_____________|______________________|________|
|XmNx | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNy | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
Callback Information
ScrolledWindow defines no new callback structures. The application must
use the ScrollBar callbacks to be notified of user input.
Page 6 10/89
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
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 my 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 my 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 my 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 my 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.
10/89 Page 7
XmScrolledWindow(3X) UNIX System V XmScrolledWindow(3X)
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), and XmScrolledWindowSetAreas(3X).
Page 8 10/89