XmScrolledWindow(3Xm) XmScrolledWindow(3Xm)
NAME
XmScrolledWindow - the ScrolledWindow widget class.
AES SUPPORT LEVEL
full-use
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
- 1 -
XmScrolledWindow(3Xm) XmScrolledWindow(3Xm)
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).
XmScrolledWindow Resource Set
Name Class Type Default Access
______________________________________________________________________________________________________________
XmNclipWindow XmCClipWindow Widget NULL G
XmNhorizontalScrollBar XmCHorizontalScrollBar Widget NULL CSG
XmNscrollBarDisplayPolicy XmCScrollBarDisplayPolicy unsigned char XmSTATIC CG
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
- 2 -
XmScrolledWindow(3Xm) XmScrolledWindow(3Xm)
XmNverticalScrollBar XmCVerticalScrollBar Widget NULL CSG
XmNvisualPolicy XmCVisualPolicy unsigned char XmVARIABLE 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
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
- 3 -
XmScrolledWindow(3Xm) XmScrolledWindow(3Xm)
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
- 4 -
XmScrolledWindow(3Xm) XmScrolledWindow(3Xm)
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.
XmManager Resource Set
Name Class Type Default Access
______________________________________________________________________________________________
XmNbottomShadowColor XmCForeground Pixel dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCForeground Pixel Black CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNshadowThickness XmCShadowThickness short 0 CSG
XmNtopShadowColor XmCBackground Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNuserData XmCUserData caddr_t NULL CSG
Composite Resource Set
Name Class Type Default Access
______________________________________________________________________
XmNinsertPosition XmCInsertPosition XmRFunction NULL CSG
Core Resource Set
Name Class Type Default Access
____________________________________________________________________________________________
XmNaccelerators XmCAccelerators XtTranslations NULL CSG
XmNancestorSensitive XmCSensitive Boolean True G
- 5 -
XmScrolledWindow(3Xm) XmScrolledWindow(3Xm)
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderColor XmCBorderColor Pixel Black CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap XtCopyFromParent CG
XmNdepth XmCDepth int XtCopyFromParent CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension 0 CSG
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Pointer XtCopyScreen CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations NULL CSG
XmNwidth XmCWidth Dimension 0 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.
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
- 6 -
XmScrolledWindow(3Xm) XmScrolledWindow(3Xm)
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(3X) and its sections on behavior and
default translations.
RELATED INFORMATION
Composite(3X), Constraint(3X), Core(3X),
XmCreateScrolledWindow(3X), XmManager(3X), and
XmScrolledWindowSetAreas(3X).
- 7 -