XmScrollBar(3X) OSF/Motif 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
──────────────────────────────────────────────────────────────
Name Default Access
Class Type
──────────────────────────────────────────────────────────────
──────────────────────────────────────────────────────────────
XmNdecrementCallback NULL C
XmCCallback XtCallbackList
──────────────────────────────────────────────────────────────
XmNdragCallback NULL C
XmCCallback XtCallbackList
──────────────────────────────────────────────────────────────
XmNincrement 1 CSG
XmCIncrement int
──────────────────────────────────────────────────────────────
XmNincrementCallback NULL C
XmCCallback XtCallbackList
──────────────────────────────────────────────────────────────
XmNinitialDelay 250 ms CSG
XmCInitialDelay int
──────────────────────────────────────────────────────────────
XmNmaximum dynamic CSG
XmCMaximum int
──────────────────────────────────────────────────────────────
XmNminimum 0 CSG
XmCMinimum int
──────────────────────────────────────────────────────────────
XmNorientation XmVERTICAL CSG
XmCOrientation unsigned char
──────────────────────────────────────────────────────────────
XmNpageDecrementCallback NULL C
XmCCallback XtCallbackList
──────────────────────────────────────────────────────────────
XmNpageIncrement 10 CSG
XmCPageIncrement int
──────────────────────────────────────────────────────────────
XmNpageIncrementCallback NULL C
XmCCallback XtCallbackList
──────────────────────────────────────────────────────────────
XmNprocessingDirection dynamic CSG
XmCProcessingDirection unsigned char
──────────────────────────────────────────────────────────────
XmNrepeatDelay 50 ms CSG
XmCRepeatDelay int
──────────────────────────────────────────────────────────────
XmNshowArrows True CSG
XmCShowArrows Boolean
──────────────────────────────────────────────────────────────
XmNsliderSize dynamic CSG
XmCSliderSize int
──────────────────────────────────────────────────────────────
XmNtoBottomCallback NULL C
XmCCallback XtCallbackList
──────────────────────────────────────────────────────────────
XmNtoTopCallback NULL C
XmCCallback XtCallbackList
──────────────────────────────────────────────────────────────
XmNtroughColor dynamic CSG
XmCTroughColor Pixel
──────────────────────────────────────────────────────────────
XmNvalue dynamic CSG
XmCValue int
──────────────────────────────────────────────────────────────
XmNvalueChangedCallback NULL C
XmCCallback XtCallbackList
──────────────────────────────────────────────────────────────
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. Spec‐
ifies 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. Specifies 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
ofXmNincrement and (XmNmaximum- 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 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 maxi‐
mum value. ScrollBars contained within ScrolledWindows have a maximum
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 XmVERTI‐
CAL and XmHORIZONTAL. 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 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 - XmNminimum) when the
slider moves to the end of the ScrollBar with the minimum value, and
the lesser of XmNpageIncrement and (XmNmaximum- XmNsliderSize - previ‐
ous 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_INCREMENT.
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. Specifies the amount of time in milliseconds to wait between
subsequent 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 inclusive bounds. The default value is
(XmNmaximum - XmNminimum) divided by 10, with a minimum of 1. Speci‐
fies 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 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. Specifies the slider's position, between XmNmin‐
imum 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 call‐
backs are also called in place of XmNincrementCallback, XmNdecrement‐
Callback, XmNpageIncrementCallback, XmNpageDecrementCallback, XmNtoTop‐
Callback, 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
───────────────────────────────────────────────────────────────
Name Default Access
Class Type
───────────────────────────────────────────────────────────────
───────────────────────────────────────────────────────────────
XmNbottomShadowColor dynamic CSG
XmCBottomShadowColor Pixel
───────────────────────────────────────────────────────────────
XmNbottomShadowPixmap XmUNSPECIFIED_PIXMAP CSG
XmCBottomShadowPixmap Pixmap
───────────────────────────────────────────────────────────────
XmNforeground dynamic CSG
XmCForeground Pixel
───────────────────────────────────────────────────────────────
XmNhelpCallback NULL C
XmCCallback XtCallbackList
───────────────────────────────────────────────────────────────
XmNhighlightColor dynamic CSG
XmCHighlightColor Pixel
───────────────────────────────────────────────────────────────
XmNhighlightOnEnter False CSG
XmCHighlightOnEnter Boolean
───────────────────────────────────────────────────────────────
XmNhighlightPixmap dynamic CSG
XmCHighlightPixmap Pixmap
───────────────────────────────────────────────────────────────
XmNhighlightThickness dynamic CSG
XmCHighlightThickness Dimension
───────────────────────────────────────────────────────────────
XmNnavigationType XmSTICKY_TAB_GROUP CSG
XmCNavigationType XmNavigationType
───────────────────────────────────────────────────────────────
XmNshadowThickness 2 CSG
XmCShadowThickness Dimension
───────────────────────────────────────────────────────────────
XmNtopShadowColor dynamic CSG
XmCTopShadowColor Pixel
───────────────────────────────────────────────────────────────
XmNtopShadowPixmap dynamic CSG
XmCTopShadowPixmap Pixmap
───────────────────────────────────────────────────────────────
XmNtraversalOn dynamic CSG
XmCTraversalOn Boolean
───────────────────────────────────────────────────────────────
XmNunitType dynamic CSG
XmCUnitType unsigned char
───────────────────────────────────────────────────────────────
XmNuserData NULL CSG
XmCUserData XtPointer
───────────────────────────────────────────────────────────────
Core Resource Set
─────────────────────────────────────────────────────────────────────
Name Default Access
Class Type
─────────────────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────────────────
XmNaccelerators dynamic CSG
XmCAccelerators XtAccelerators
─────────────────────────────────────────────────────────────────────
XmNancestorSensitive dynamic G
XmCSensitive Boolean
─────────────────────────────────────────────────────────────────────
XmNbackground dynamic CSG
XmCBackground Pixel
─────────────────────────────────────────────────────────────────────
XmNbackgroundPixmap XmUNSPECIFIED_PIXMAP CSG
XmCPixmap Pixmap
─────────────────────────────────────────────────────────────────────
XmNborderColor XtDefaultForeground CSG
XmCBorderColor Pixel
─────────────────────────────────────────────────────────────────────
XmNborderPixmap XmUNSPECIFIED_PIXMAP CSG
XmCPixmap Pixmap
─────────────────────────────────────────────────────────────────────
XmNborderWidth 0 CSG
XmCBorderWidth Dimension
─────────────────────────────────────────────────────────────────────
XmNcolormap dynamic CG
XmCColormap Colormap
─────────────────────────────────────────────────────────────────────
XmNdepth dynamic CG
XmCDepth int
─────────────────────────────────────────────────────────────────────
XmNdestroyCallback NULL C
XmCCallback XtCallbackList
─────────────────────────────────────────────────────────────────────
XmNheight dynamic CSG
XmCHeight Dimension
─────────────────────────────────────────────────────────────────────
XmNinitialResourcesPersistent True C
XmCInitialResourcesPersistent Boolean
─────────────────────────────────────────────────────────────────────
XmNmappedWhenManaged True CSG
XmCMappedWhenManaged Boolean
─────────────────────────────────────────────────────────────────────
XmNscreen dynamic CG
XmCScreen Screen *
─────────────────────────────────────────────────────────────────────
XmNsensitive True CSG
XmCSensitive Boolean
─────────────────────────────────────────────────────────────────────
XmNtranslations dynamic CSG
XmCTranslations XtTranslations
─────────────────────────────────────────────────────────────────────
XmNwidth dynamic CSG
XmCWidth Dimension
─────────────────────────────────────────────────────────────────────
XmNx 0 CSG
XmCPosition Position
─────────────────────────────────────────────────────────────────────
XmNy 0 CSG
XmCPosition Position
─────────────────────────────────────────────────────────────────────
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 call‐
back was invoked. Points to the XEvent that triggered the callback.
Contains the new slider location value. Is used only for XmNtoTopCall‐
back and XmNtoBottomCallback. For horizontal ScrollBars, it contains
the x coordinate of where the mouse button selection occurred. For
vertical ScrollBars, it contains the y coordinate.
Translations
XmScrollBar includes translations from Primitive. The XmScrollBar
translations are listed below. These translations may not directly
correspond 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: PageDownOr‐
Right(0)
KLeft: IncrementUpOrLeft(1) MCtrl KLeft: PageUpOrLeft(1)
KRight: IncrementDownOrRight(1) MCtrl KRight: PageDownOr‐
Right(1)
KPageUp: PageUpOrLeft(0) KPageDown: PageDownOrRight(0)
KPageLeft: PageUpOrLeft(1) KPageRight: PageDownOrRight(1)
KBeginLine: TopOrBottom() KEndLine: TopOrBottom()
KBeginData: TopOrBottom() KEndData: TopOrBottom()
KNextField: PrimitiveNextTabGroup() KPrevField: PrimitivePrevTab‐
Group()
KActivate: PrimitiveParentActivate() 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 XmNprocessingDirec‐
tion is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement toward the right or
bottom calls the callbacks for XmNdecrementCallback. The XmNval‐
ueChangedCallback is called if the XmNincrementCallback or XmNdecre‐
mentCallback 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 XmNprocessingDirection is XmMAX_ON_RIGHT or
XmMAX_ON_BOTTOM, movement to the left or top calls the callbacks for
XmNdecrementCallback. If XmNprocessingDirection is XmMAX_ON_LEFT or
XmMAX_ON_TOP, movement to the left or top calls the callbacks for XmN‐
incrementCallback. The XmNvalueChangedCallback is called if the XmNin‐
crementCallback or XmNdecrementCallback 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 XmNdragCall‐
back. With an argument of 0, moves the slider down by one page incre‐
ment. With an argument of 1, moves the slider right by one page incre‐
ment. If XmNprocessingDirection is XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM,
movement toward the right or bottom calls the callbacks for XmNpageIn‐
crementCallback. If XmNprocessingDirection 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 XmNpro‐
cessingDirection is XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, movement to the
left or top calls the callbacks for XmNpageDecrementCallback. If XmN‐
processingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement to the
left or top calls the callbacks for XmNpageIncrementCallback. The XmN‐
valueChangedCallback is called if the XmNpageIncrementCallback or XmN‐
pageDecrementCallback is NULL. Calls the callbacks for XmNhelpCallback
if any exist. If there are no help callbacks for this widget, this
action calls the help callbacks 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 begin‐
ning 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 XmNval‐
ueChangedCallback 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 XmNincrementCallback, and movement to the left
or top calls the callbacks for XmNdecrementCallback. If XmNprocess‐
ingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement toward the
right or bottom calls the callbacks for XmNdecrementCallback, and move‐
ment 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 XmNprocess‐
ingDirection is XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, movement toward the
right or bottom calls the callbacks for XmNpageIncrementCallback, and
movement to the left or top calls the callbacks for XmNpageDecrement‐
Callback. If XmNprocessingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP,
movement toward the right or bottom calls the callbacks for XmN‐
pageDecrementCallback, and movement to the left or top calls the call‐
backs for XmNpageIncrementCallback. 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 ini‐
tial 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 bot‐
tom calls the callbacks for XmNtoBottomCallback, and movement to the
left or top calls the callbacks for XmNtoTopCallback. If XmNprocess‐
ingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement toward the
right or bottom calls the callbacks for XmNtoTopCallback, and movement
to the left or top calls the callbacks for XmNtoBottomCallback. The
XmNvalueChangedCallback is called if the XmNtoTopCallback or XmNtoBot‐
tomCallback 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 XmNtoBottomCallback.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information
about bindings for virtual buttons and keys, see VirtualBindings(3X).
RELATED INFORMATIONCore(3X), XmCreateScrollBar(3X), XmPrimitive(3X), XmScrollBarGetVal‐
ues(3X), and XmScrollBarSetValues(3X).
XmScrollBar(3X)
