XmScrolledWindow(Xm) UNIX System V
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).
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
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 XmASNEEDED 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
XmAPPLICATIONDEFINED.
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 and the vertical ScrollBar to the left of the
work window.
⊕ XmBOTTOMLEFT - The horizontal ScrollBar is placed below
the work window and the vertical ScrollBar to the left of
the work window.
⊕ XmTOPRIGHT - The horizontal ScrollBar is placed above
the work window and the vertical ScrollBar to the right
of the work window.
⊕ XmBOTTOMRIGHT - 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 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.
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.
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
XmNunitType XmCUnitType unsigned char XmPIXELS 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
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 XmAPPLICATIONDEFINED 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(Xm) and its sections on behavior and default
translations.
RELATED INFORMATION
Composite(Xm), Constraint(Xm), Core(Xm),
XmCreateScrolledWindow(Xm), XmManager(Xm), and
XmScrolledWindowSetAreas(Xm).
(printed 2/14/90) XmScrolledWindow(Xm)