|
XmScrolledWindow(3X)
Contents
|
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.
Classes [Toc] [Back]
ScrolledWindow inherits behavior and resources from Core,
Composite, Constraint, and XmManager Classes.
The class pointer is xmScrolledWindowWidgetClass.
The class name is XmScrolledWindow.
New Resources [Toc] [Back]
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 [Toc] [Back]
Class: XmCClipWindow
Default: dynamic
Type: Widget
Access: G
Class: XmCHorizontalScrollBar
Default: dynamic
Type: Widget
Access: CSG
Class: XmCScrollBarDisplayPolicy
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCScrollBarPlacement
Default: XmBOTTOM_RIGHT
Type: unsigned char
Access: CSG
Class: XmCScrolledWindowMarginHeight
Default: 0
Type: Dimension
Access: CSG
Class: XmCScrolledWindowMarginWidth
Default: 0
Type: Dimension
Access: CSG
Class: XmCScrollingPolicy
Default: XmAPPLICATION_DEFINED
Type: unsigned char
Access: CG
Class: XmCSpacing
Default: 4
Type: Dimension
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: CSG
Class: XmCVerticalScrollBar
Default: dynamic
Type: Widget
Access: CSG
Class: XmCVisualPolicy
Default: dynamic
Type: unsigned char
Access: G
Class: XmCWorkWindow
Default: NULL
Type: Widget
Access: CSG
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 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. 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. 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 XmAS_NEEDED when XmNscrollingPolicy
is XmAUTOMATIC, and XmSTATIC otherwise.
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. Specifies the margin
height on the top and bottom of the ScrolledWindow.
Specifies the margin width on the right and left
sides of the ScrolledWindow. 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. Specifies the distance
that separates the ScrollBars from the work
window. Specifies a list of callbacks that is
called when traversing to a widget or gadget that
is obscured due to its position in the work area
relative to the location of the ScrolledWindow
viewport. This resource is valid only when XmNscrollingPolicy
is XmAUTOMATIC. If this resource
is NULL, an obscured widget cannot be traversed to.
The callback reason is XmCR_OBSCURED_TRAVERSAL.
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. 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. Specifies the widget
ID of the viewing area.
Inherited Resources [Toc] [Back]
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 [Toc] [Back]
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCInitialFocus
Default: NULL
Type: Widget
Access: CSG
Class: XmCNavigationType
Default: XmTAB_GROUP
Type: XmNavigationType
Access: CSG
Class: XmCShadowThickness
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCStringDirection
Default: dynamic
Type: XmStringDirection
Access: CG
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCTraversalOn
Default: True
Type: Boolean
Access: CSG
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Composite Resource Set [Toc] [Back]
Class: XmCReadOnly
Default: NULL
Type: WidgetList
Access: G
Class: XmCInsertPosition
Default: NULL
Type: XtOrderProc
Access: CSG
Class: XmCReadOnly
Default: 0
Type: Cardinal
Access: G
Core Resource Set [Toc] [Back]
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: CSG
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
Class: XmCScreen
Default: dynamic
Type: Screen *
Access: CG
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
Access: CSG
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
Callback Information [Toc] [Back]
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;
Indicates why the callback was invoked. Points to the
XEvent that triggered the callback. Specifies the widget
or gadget to traverse to, which will be a descendant of
the work window. Specifies the direction of traversal.
See the description of the direction parameter in the
XmProcessTraversal(3X) man page for an explanation of the
valid values.
Translations [Toc] [Back]
XmScrolledWindow includes the translations from XmManager.
Additional Behavior [Toc] [Back]
This widget has the additional behavior described below:
If XmNscrollingPolicy is XmAUTOMATIC, scrolls the window
up the height of the viewport. The distance scrolled may
be reduced to provide some overlap. The actual distance
scrolled depends on the XmNpageIncrement resource of the
vertical ScrollBar. If XmNscrollingPolicy is XmAUTOMATIC,
scrolls the window down the height of the viewport. The
distance scrolled may be reduced to provide some overlap.
The actual distance scrolled depends on the XmNpageIncrement
resource of the vertical ScrollBar. If XmNscrollingPolicy
is XmAUTOMATIC, scrolls the window left the width
of the viewport. The distance scrolled may be reduced to
provide some overlap. The actual distance scrolled depends
on the XmNpageIncrement resource of the horizontal ScrollBar.
If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window right the width of the viewport. The distance
scrolled may be reduced to provide some overlap. The
actual distance scrolled depends on the XmNpageIncrement
resource of the horizontal ScrollBar. If XmNscrollingPolicy
is XmAUTOMATIC, scrolls the window horizontally to the
edge corresponding to the horizontal ScrollBar's minimum
value. If XmNscrollingPolicy is XmAUTOMATIC, scrolls the
window horizontally to the edge corresponding to the horizontal
ScrollBar's maximum value. If XmNscrollingPolicy
is XmAUTOMATIC, scrolls the window vertically to the edge
corresponding to the vertical ScrollBar's minimum value.
If XmNscrollingPolicy is XmAUTOMATIC, scrolls the window
vertically to the edge corresponding to the vertical
ScrollBar's maximum value.
Certain applications will want to replace the page bindings
with ones that are specific to the content of the
scrolled area.
Virtual Bindings [Toc] [Back]
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), XmScrolledWindowSetAreas(3X)
XmScrolledWindow(3X)
[ Back ] |