 |
Index for
Section 3X |
|
 |
Alphabetical
listing for X |
|
 |
Bottom of
page |
|
XmScrolledWindow(3X)
OSF/Motif
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 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
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 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
XmNclipWindow
Class: XmCClipWindow
Default: dynamic
Type: Widget
Access: G
XmNhorizontalScrollBar
Class: XmCHorizontalScrollBar
Default: dynamic
Type: Widget
Access: CSG
XmNscrollBarDisplayPolicy
Class: XmCScrollBarDisplayPolicy
Default: dynamic
Type: unsigned char
Access: CSG
XmNscrollBarPlacement
Class: XmCScrollBarPlacement
Default: XmBOTTOM_RIGHT
Type: unsigned char
Access: CSG
XmNscrolledWindowMarginHeight
Class: XmCScrolledWindowMarginHeight
Default: 0
Type: Dimension
Access: CSG
XmNscrolledWindowMarginWidth
Class: XmCScrolledWindowMarginWidth
Default: 0
Type: Dimension
Access: CSG
XmNscrollingPolicy
Class: XmCScrollingPolicy
Default: XmAPPLICATION_DEFINED
Type: unsigned char
Access: CG
XmNspacing
Class: XmCSpacing
Default: 4
Type: Dimension
Access: CSG
XmNtraverseObscuredCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: CSG
XmNverticalScrollBar
Class: XmCVerticalScrollBar
Default: dynamic
Type: Widget
Access: CSG
XmNvisualPolicy
Class: XmCVisualPolicy
Default: dynamic
Type: unsigned char
Access: G
XmNworkWindow
Class: XmCWorkWindow
Default: NULL
Type: Widget
Access: 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 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 XmAS_NEEDED 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,
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.
XmNtraverseObscuredCallback
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.
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.
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
XmNbottomShadowColor
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNbottomShadowPixmap
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNforeground
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
XmNhelpCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNhighlightColor
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
XmNhighlightPixmap
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNinitialFocus
Class: XmCInitialFocus
Default: NULL
Type: Widget
Access: CSG
XmNnavigationType
Class: XmCNavigationType
Default: XmTAB_GROUP
Type: XmNavigationType
Access: CSG
XmNshadowThickness
Class: XmCShadowThickness
Default: dynamic
Type: Dimension
Access: CSG
XmNstringDirection
Class: XmCStringDirection
Default: dynamic
Type: XmStringDirection
Access: CG
XmNtopShadowColor
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNtopShadowPixmap
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNtraversalOn
Class: XmCTraversalOn
Default: True
Type: Boolean
Access: CSG
XmNunitType
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
XmNuserData
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Composite Resource Set
XmNchildren
Class: XmCReadOnly
Default: NULL
Type: WidgetList
Access: G
XmNinsertPosition
Class: XmCInsertPosition
Default: NULL
Type: XtOrderProc
Access: CSG
XmNnumChildren
Class: XmCReadOnly
Default: 0
Type: Cardinal
Access: G
Core Resource Set
XmNaccelerators
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: CSG
XmNancestorSensitive
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
XmNbackground
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
XmNbackgroundPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderColor
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
XmNborderPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderWidth
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
XmNcolormap
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
XmNdepth
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
XmNdestroyCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNheight
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
XmNinitialResourcesPersistent
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
XmNmappedWhenManaged
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
XmNscreen
Class: XmCScreen
Default: dynamic
Type: Screen *
Access: CG
XmNsensitive
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
XmNtranslations
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
Access: CSG
XmNwidth
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
XmNx
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
XmNy
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
Callback Information
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;
reason
Indicates why the callback was invoked.
event
Points to the XEvent that triggered the callback.
traversal_destination
Specifies the widget or gadget to traverse to, which will be a
descendant of the work window.
direction
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
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 may 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 may 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 may 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 may 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.
Certain applications will want to replace the page bindings with ones that
are specific to the content of the scrolled area.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information about
bindings for virtual buttons and keys, see VirtualBindings(3X).
SEE ALSO
Composite(3X), Constraint(3X), Core(3X), XmCreateScrolledWindow(3X),
XmManager(3X), XmProcessTraversal(3X), XmScrollBar(3X),
XmScrollVisible(3X), XmScrolledWindowSetAreas(3X)
|
Index for
Section 3X |
|
|
Alphabetical
listing for X |
|
 |
Top of
page |
|