XmScrollBar(3X)XmScrollBar(3X)NAMEXmScrollBar - The ScrollBar widget class
SYNOPSIS
#include <Xm/ScrollBar.h>
DESCRIPTION
The ScrollBar widget allows the user to view data that is too large to
be displayed all at once. ScrollBars are usually located inside a
ScrolledWindow and adjacent to the widget that contains the data to be
viewed. When the user interacts with the ScrollBar, the data within
the other widget scrolls.
A ScrollBar consists of two arrows placed at each end of a rectangle.
The rectangle is called the scroll region. A smaller rectangle, called
the slider, is placed within the scroll region. The data is scrolled
by clicking either arrow, selecting on the scroll region, or dragging
the slider. When an arrow is selected, the slider within the scroll
region is moved in the direction of the arrow by an amount supplied by
the application. If the mouse button is held down, the slider contin‐
ues to move at a constant rate.
The ratio of the slider size to the scroll region size typically corre‐
sponds to the relationship between the size of the visible data and the
total size of the data. For example, if 10 percent of the data is vis‐
ible, the slider typically occupies 10 percent of the scroll region.
This provides the user with a visual clue to the size of the invisible
data.
Classes
ScrollBar inherits behavior and resources from the Core and XmPrimitive
classes.
The class pointer is xmScrollBarWidgetClass.
The class name is XmScrollBar.
New Resources
The following table defines a set of widget resources used by the pro‐
grammer to specify data. The programmer can also set the resource val‐
ues 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).
XmScrollBar Resource Set
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCIncrement
Default: 1
Type: int
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCInitialDelay
Default: 250 ms
Type: int
Access: CSG
Class: XmCMaximum
Default: dynamic
Type: int
Access: CSG
Class: XmCMinimum
Default: 0
Type: int
Access: CSG
Class: XmCOrientation
Default: XmVERTICAL
Type: unsigned char
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCPageIncrement
Default: 10
Type: int
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCProcessingDirection
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCRepeatDelay
Default: 50 ms
Type: int
Access: CSG
Class: XmCShowArrows
Default: True
Type: Boolean
Access: CSG
Class: XmCSliderSize
Default: dynamic
Type: int
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCTroughColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCValue
Default: dynamic
Type: int
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Specifies the list of callbacks that is called when the user
takes an action that moves the ScrollBar by one increment and
the value decreases. The reason passed to the callback is
XmCR_DECREMENT. Specifies the list of callbacks that is called
on each incremental change of position when the slider is being
dragged. The reason sent by the callback is XmCR_DRAG. Speci‐
fies the amount by which the value increases or decreases when
the user takes an action that moves the slider by one increment.
The actual change in value is the lesser of XmNincrement and
(previous XmNvalue�- XmNminimum) when the slider moves to the
end of the ScrollBar with the minimum value, and the lesser of
XmNincrement and (XmNmaximum - XmNsliderSize�- previous XmN‐
value) when the slider moves to the end of the ScrollBar with
the maximum value. The value of this resource must be greater
than 0. Specifies the list of callbacks that is called when the
user takes an action that moves the ScrollBar by one increment
and the value increases. The reason passed to the callback is
XmCR_INCREMENT. Specifies the amount of time in milliseconds to
wait before starting continuous slider movement while a button
is pressed in an arrow or the scroll region. The value of this
resource must be greater than 0. Specifies the slider's maximum
value. ScrollBars contained within ScrolledWindows have a maxi‐
mum equal to the size of ScrollBar (that is, the height if it is
vertical, or the width if it is horizontal). XmNmaximum must be
greater than XmNminimum. Specifies the slider's minimum value.
XmNmaximum must be greater than XmNminimum. Specifies whether
the ScrollBar is displayed vertically or horizontally. This
resource can have values of XmVERTICAL and XmHORIZONTAL. Speci‐
fies the list of callbacks that is called when the user takes an
action that moves the ScrollBar by one page increment and the
value decreases. The reason passed to the callback is
XmCR_PAGE_DECREMENT. Specifies the amount by which the value
increases or decreases when the user takes an action that moves
the slider by one page increment. The actual change in value is
the lesser of XmNpageIncrement and (previous XmNvalue�- XmNmini‐
mum) when the slider moves to the end of the ScrollBar with the
minimum value, and the lesser of XmNpageIncrement and (XmNmaxi‐
mum - XmNsliderSize�- previous XmNvalue) when the slider moves
to the end of the ScrollBar with the maximum value. The value of
this resource must be greater than 0. Specifies the list of
callbacks that is called when the user takes an action that
moves the ScrollBar by one page increment and the value
increases. The reason passed to the callback is XmCR_PAGE_INCRE‐
MENT. Specifies whether the value for XmNmaximum should be on
the right or left side of XmNminimum for horizontal ScrollBars
or above or below XmNminimum for vertical ScrollBars. This
resource can have values of XmMAX_ON_TOP, XmMAX_ON_BOTTOM,
XmMAX_ON_LEFT and XmMAX_ON_RIGHT. If the XmScrollBar is oriented
vertically, the default value is XmMAX_ON_BOTTOM. If the
XmScrollBar is oriented horizontally, the default value may
depend on the value of the XmNstringDirection resource. Speci‐
fies the amount of time in milliseconds to wait between subse‐
quent slider movements after the XmNinitialDelay has been pro‐
cessed. The value of this resource must be greater than 0.
Specifies whether the arrows are displayed. Specifies the
length of the slider between the values of 1 and (XmNmaximum�-
XmNminimum). The value is constrained to be within these inclu‐
sive bounds. The default value is (XmNmaximum�- XmNminimum)
divided by 10, with a minimum of 1. Specifies the list of call‐
backs that is called when the user takes an action that moves
the slider to the end of the ScrollBar with the maximum value.
The reason passed to the callback is XmCR_TO_BOTTOM. Specifies
the list of callbacks that is called when the user takes an
action that moves the slider to the end of the ScrollBar with
the minimum value. The reason passed to the callback is
XmCR_TO_TOP. Specifies the color of the slider trough. Speci‐
fies the slider's position, between XmNminimum and (XmNmaximum�-
XmNsliderSize). The value is constrained to be within these
inclusive bounds. The initial value of this resource is the
larger of 0 and XmNminimum. Specifies the list of callbacks
that is called when the slider is released after being dragged.
These callbacks are also called in place of XmNincrementCall‐
back, XmNdecrementCallback, XmNpageIncrementCallback, XmN‐
pageDecrementCallback, XmNtoTopCallback, or XmNtoBottomCallback
when one of these callback lists would normally be called but
the value of the corresponding resource is NULL. The reason
passed to the callback is XmCR_VALUE_CHANGED.
Inherited Resources
ScrollBar inherits behavior and resources from the following super‐
classes. For a complete description of each resource, refer to the man
page for that superclass.
XmPrimitive Resource Set
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: XmCHighlightOnEnter
Default: False
Type: Boolean
Access: CSG
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCHighlightThickness
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCNavigationType
Default: XmSTICKY_TAB_GROUP
Type: XmNavigationType
Access: CSG
Class: XmCShadowThickness
Default: 2
Type: Dimension
Access: CSG
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCTraversalOn
Default: dynamic
Type: Boolean
Access: CSG
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Core Resource Set
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
A pointer to the following structure is passed to each callback: type‐
def struct {
int reason;
XEvent * event;
int value;
int pixel; } XmScrollBarCallbackStruct;
Indicates why the callback was invoked. Points to the XEvent that
triggered the callback. Contains the new slider location value. Is
used only for XmNtoTopCallback and XmNtoBottomCallback. For horizontal
ScrollBars, it contains the x coordinate of where the mouse button
selection occurred. For vertical ScrollBars, it contains the y coordi‐
nate.
Translations
XmScrollBar includes translations from Primitive. The XmScrollBar
translations are listed below. These translations may not directly cor‐
respond to a translation table. BSelect Press: Select() BSelect
Release:Release() BSelect Press Moved:Moved() BDrag Press: Select()
BDrag Release: Release() BDrag Press Moved:Moved() MCtrl BSelect
Press:TopOrBottom() MCtrl BSelect Release:Release() KUp:
IncrementUpOrLeft(0) MCtrl KUp: PageUpOrLeft(0) KDown:
IncrementDownOrRight(0) MCtrl KDown: PageDownOrRight(0) KLeft:
IncrementUpOrLeft(1) MCtrl KLeft: PageUpOrLeft(1) KRight:
IncrementDownOrRight(1) MCtrl KRight: PageDownOrRight(1) KPageUp:
PageUpOrLeft(0) KPageDown: PageDownOrRight(0) KPageLeft: PageU‐
pOrLeft(1) KPageRight: PageDownOrRight(1) KBeginLine: TopOrBot‐
tom() KEndLine: TopOrBottom() KBeginData: TopOrBottom() KEnd‐
Data: TopOrBottom() KNextField: PrimitiveNextTabGroup() KPre‐
vField: PrimitivePrevTabGroup() KActivate: PrimitiveParentActi‐
vate() KCancel: CancelDrag() KHelp: PrimitiveHelp()
Action Routines
The ScrollBar action routines are described below: If the key press
occurs during scrolling, cancels the scroll and returns the slider to
its previous location in the scrollbar, otherwise, and if the parent is
a manager, it passes the event to the parent. With an argument of 0,
moves the slider down by one increment. With an argument of 1, moves
the slider right by one increment. If XmNprocessingDirection is
XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, movement toward the right or bottom
calls the callbacks for XmNincrementCallback. If XmNprocessingDirection
is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement toward the right or bottom
calls the callbacks for XmNdecrementCallback. The XmNvalueChangedCall‐
back is called if the XmNincrementCallback or XmNdecrementCallback is
NULL. With an argument of 0, moves the slider up by one increment.
With an argument of 1, moves the slider left by one increment. If XmN‐
processingDirection is XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, movement to
the left or top calls the callbacks for XmNdecrementCallback. If XmN‐
processingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement to the
left or top calls the callbacks for XmNincrementCallback. The XmNval‐
ueChangedCallback is called if the XmNincrementCallback or XmNdecre‐
mentCallback is NULL. If the button press occurs within the slider,
the subsequent motion events move the slider to the position of the
pointer and call the callbacks for XmNdragCallback. With an argument
of 0, moves the slider down by one page increment. With an argument of
1, moves the slider right by one page increment. If XmNprocessingDirec‐
tion is XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, movement toward the right or
bottom calls the callbacks for XmNpageIncrementCallback. If XmNprocess‐
ingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement toward the
right or bottom calls the callbacks for XmNpageDecrementCallback. The
XmNvalueChangedCallback is called if the XmNpageIncrementCallback or
XmNpageDecrementCallback is NULL. With an argument of 0, moves the
slider up by one page increment. With an argument of 1, moves the
slider left by one page increment. If XmNprocessingDirection is
XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, movement to the left or top calls
the callbacks for XmNpageDecrementCallback. If XmNprocessingDirection
is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement to the left or top calls the
callbacks for XmNpageIncrementCallback. The XmNvalueChangedCallback is
called if the XmNpageIncrementCallback or XmNpageDecrementCallback is
NULL. Calls the callbacks for XmNhelpCallback if any exist. If there
are no help callbacks for this widget, this action calls the help call‐
backs for the nearest ancestor that has them. Traverses to the first
item in the next tab group. If the current tab group is the last entry
in the tab group list, it wraps to the beginning of the tab group list.
If the parent is a manager, passes the event to the parent. Traverses
to the first item in the previous tab group. If the beginning of the
tab group list is reached, it wraps to the end of the tab group list.
If the button press occurs within the slider and the slider position is
changed, the callbacks for XmNvalueChangedCallback are called. In the
arrow: Moves the slider by one increment in the direction of the
arrow. If XmNprocessingDirection is XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM,
movement toward the right or bottom calls the callbacks for XmNincre‐
mentCallback, and movement to the left or top calls the callbacks for
XmNdecrementCallback. If XmNprocessingDirection is XmMAX_ON_LEFT or
XmMAX_ON_TOP, movement toward the right or bottom calls the callbacks
for XmNdecrementCallback, and movement to the left or top calls the
callbacks for XmNincrementCallback. The XmNvalueChangedCallback is
called if the XmNincrementCallback or XmNdecrementCallback is NULL.
In the scroll region between an arrow and the slider: Moves the
slider by one page increment in the direction of the arrow. If
XmNprocessingDirection is XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM,
movement toward the right or bottom calls the callbacks for XmN‐
pageIncrementCallback, and movement to the left or top calls the
callbacks for XmNpageDecrementCallback. If XmNprocessingDirec‐
tion is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement toward the right
or bottom calls the callbacks for XmNpageDecrementCallback, and
movement to the left or top calls the callbacks for XmNpageIn‐
crementCallback. The XmNvalueChangedCallback is called if the
XmNpageIncrementCallback or XmNpageDecrementCallback is NULL.
In the slider: Activates the interactive dragging of the
slider.
If the button is held down in either the arrows or the scroll
region longer than the XmNinitialDelay resource, the slider is
moved again by the same increment and the same callbacks are
called. After the initial delay has been used, the time delay
changes to the time defined by the resource XmNrepeatDelay.
MCtrl BSelect Press in an arrow or in the scroll region between
an arrow and the slider moves the slider as far as possible in
the direction of the arrow. If XmNprocessingDirection is
XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, movement toward the right or
bottom calls the callbacks for XmNtoBottomCallback, and movement
to the left or top calls the callbacks for XmNtoTopCallback. If
XmNprocessingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, move‐
ment toward the right or bottom calls the callbacks for XmNto‐
TopCallback, and movement to the left or top calls the callbacks
for XmNtoBottomCallback. The XmNvalueChangedCallback is called
if the XmNtoTopCallback or XmNtoBottomCallback is NULL. Pressing
KBeginLine or KBeginData moves the slider to the minimum value
and invokes the XmNtoTopCallback. Pressing KEndLine or KEndData
moves the slider to the maximum value and invokes the XmNtoBot‐
tomCallback.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information
about bindings for virtual buttons and keys, see VirtualBindings(3X).
SEE ALSOCore(3X), XmCreateScrollBar(3X), XmPrimitive(3X), XmScrollBarGetVal‐
ues(3X), XmScrollBarSetValues(3X)XmScrollBar(3X)
