XmScrollBar(3X)

XmScrollBar --The ScrollBar widget class

As shipped in IRIX 6.5.15. Unchanged since IRIX 6.5.

NAME
XmScrollBar --The ScrollBar widget class

SYNOPSIS
#include <Xm/ScrollBar.h>

VERSION
This page documents version 1.2 of the Motif library.

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 Scrolled-
Window and adjacent to the widget that contains the data to be viewed.
When the user interacts with the ScrollBar, the data within the other wid-
get 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 click-
ing 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 continues 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 to-
tal size of the data. For example, if 10 percent of the data is visible,
the slider typically occupies 10 percent of the scroll region. This pro-
vides 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 program-
mer 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 re-
maining letters (in either lowercase or uppercase, but include any under-
scores 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 Class Type Default Access
-----------------------------------------------------------------------------------------
XmNdecrementCallback XmCCallback XtCallbackList NULL C
XmNdragCallback XmCCallback XtCallbackList NULL C
XmNincrement XmCIncrement int 1 CSG
XmNincrementCallback XmCCallback XtCallbackList NULL C
XmNinitialDelay XmCInitialDelay int 250 ms CSG
XmNmaximum XmCMaximum int dynamic CSG
XmNminimum XmCMinimum int 0 CSG
XmNorientation XmCOrientation unsigned char XmVERTICAL CSG
XmNpageDecrementCallback XmCCallback XtCallbackList NULL C
XmNpageIncrement XmCPageIncrement int 10 CSG
XmNpageIncrementCallback XmCCallback XtCallbackList NULL C
XmNprocessingDirection XmCProcessingDirection unsigned char dynamic CSG
XmNrepeatDelay XmCRepeatDelay int 50 ms CSG
XmNshowArrows XmCShowArrows Boolean True CSG
XmNsliderSize XmCSliderSize int dynamic CSG
XmNtoBottomCallback XmCCallback XtCallbackList NULL C
XmNtoTopCallback XmCCallback XtCallbackList NULL C
XmNtroughColor XmCTroughColor Pixel dynamic CSG
XmNvalue XmCValue int dynamic CSG
XmNvalueChangedCallback XmCCallback XtCallbackList NULL C

XmNdecrementCallback
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.

XmNdragCallback
Specifies the list of callbacks that is called on each incremen-
tal change of position when the slider is being dragged. The
reason sent by the callback is XmCR_DRAG.

XmNincrement
Specifies the amount by which the value increases or decreases
when the user takes an action that moves the slider by one incre-
ment. 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 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.

XmNincrementCallback
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_IN-
CREMENT.

XmNinitialDelay
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.

XmNmaximumSpecifies the slider's maximum 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.

XmNminimumSpecifies the slider's minimum value. XmNmaximum must be greater
than XmNminimum.

XmNorientation
Specifies whether the ScrollBar is displayed vertically or hori-
zontally. This resource can have values of XmVERTICAL and XmHOR-
IZONTAL.

XmNpageDecrementCallback
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.

XmNpageIncrement
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 XmN-
pageIncrement 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- XmNslider-
Size - 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.

XmNpageIncrementCallback
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.

XmNprocessingDirection
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 Xm-
MAX_ON_RIGHT. If the XmScrollBar is oriented vertically, the de-
fault value is XmMAX_ON_BOTTOM. If the XmScrollBar is oriented
horizontally, the default value may depend on the value of the
XmNstringDirection resource.

XmNrepeatDelay
Specifies the amount of time in milliseconds to wait between sub-
sequent slider movements after the XmNinitialDelay has been
processed. The value of this resource must be greater than 0.

XmNshowArrows
Specifies whether the arrows are displayed.

XmNsliderSize
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 - XmN-
minimum) divided by 10, with a minimum of 1.

XmNtoBottomCallback
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 maximum value. The reason passed to the callback is
XmCR_TO_BOTTOM.

XmNtoTopCallback
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.

XmNtroughColor
Specifies the color of the slider trough.

XmNvalue Specifies the slider's position, between XmNminimum and (XmNmaxi-
mum - XmNsliderSize). The value is constrained to be within
these inclusive bounds. The initial value of this resource is
the larger of 0 and XmNminimum.

XmNvalueChangedCallback
Specifies the list of callbacks that is called when the slider is
released after being dragged. These callbacks are also called in
place of XmNincrementCallback, XmNdecrementCallback, XmNpageIn-
crementCallback, XmNpageDecrementCallback, XmNtoTopCallback, or
XmNtoBottomCallback when one of these callback lists would nor-
mally 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 superclasses.
For a complete description of each resource, refer to the man page for that
superclass.

XmPrimitive Resource Set
Name Class Type Default Access
-------------------------------------------------------------------------------------------------
XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCHighlightColor Pixel dynamic CSG
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNhighlightThickness XmCHighlightThickness Dimension dynamic CSG
XmNnavigationType XmCNavigationType XmNavigationType XmSTICKY_TAB_GROUP CSG
XmNshadowThickness XmCShadowThickness Dimension 2 CSG
XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG
XmNtraversalOn XmCTraversalOn Boolean dynamic CSG
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData XtPointer NULL CSG

Core Resource Set
Name Class Type Default Access
---------------------------------------------------------------------------------------------------------------
XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG
XmNancestorSensitive XmCSensitive Boolean dynamic G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap dynamic CG
XmNdepth XmCDepth int dynamic CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension dynamic CSG
XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Screen * dynamic CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations dynamic CSG
XmNwidth XmCWidth Dimension dynamic CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG

Callback Information
A pointer to the following structure is passed to each callback:

typedef struct
{
int reason;
XEvent * event;
int value;
int pixel;
} XmScrollBarCallbackStruct;

reason Indicates why the callback was invoked.

event Points to the XEvent that triggered the callback.

value Contains the new slider location value.

pixel Is used only for XmNtoTopCallback and XmNtoBottomCallback. For hor-
izontal 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 transla-
tions 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: PageDownOrRight(0)

KLeft: IncrementUpOrLeft(1)
MCtrl KLeft: PageUpOrLeft(1)

KRight: IncrementDownOrRight(1)
MCtrl KRight: PageDownOrRight(1)

KPageUp: PageUpOrLeft(0)
KPageDown: PageDownOrRight(0)
KPageLeft: PageUpOrLeft(1)
KPageRight: PageDownOrRight(1)

KBeginLine: TopOrBottom()
KEndLine: TopOrBottom()

KBeginData: TopOrBottom()
KEndData: TopOrBottom()

KNextField: PrimitiveNextTabGroup()
KPrevField: PrimitivePrevTabGroup()

KActivate: PrimitiveParentActivate()
KCancel: CancelDrag()

KHelp: PrimitiveHelp()

Action Routines
The ScrollBar action routines are described below:

CancelDrag():
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.

IncrementDownOrRight(0|1):
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 XmN-
incrementCallback. If XmNprocessingDirection is XmMAX_ON_LEFT or
XmMAX_ON_TOP, movement toward the right or bottom calls the call-
backs for XmNdecrementCallback. The XmNvalueChangedCallback is
called if the XmNincrementCallback or XmNdecrementCallback is
NULL.

IncrementUpOrLeft(0|1):
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 XmNdecrement-
Callback. If XmNprocessingDirection is XmMAX_ON_LEFT or Xm-
MAX_ON_TOP, movement to the left or top calls the callbacks for
XmNincrementCallback. The XmNvalueChangedCallback is called if
the XmNincrementCallback or XmNdecrementCallback is NULL.

Moved(): If the button press occurs within the slider, the subsequent mo-
tion events move the slider to the position of the pointer and
call the callbacks for XmNdragCallback.

PageDownOrRight(0|1):
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
increment. If XmNprocessingDirection is XmMAX_ON_RIGHT or Xm-
MAX_ON_BOTTOM, movement toward the right or bottom calls the
callbacks for XmNpageIncrementCallback. If XmNprocessingDirec-
tion 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.

PageUpOrLeft(0|1):
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 incre-
ment. If XmNprocessingDirection is XmMAX_ON_RIGHT or Xm-
MAX_ON_BOTTOM, movement to the left or top calls the callbacks
for XmNpageDecrementCallback. If XmNprocessingDirection is Xm-
MAX_ON_LEFT or XmMAX_ON_TOP, movement to the left or top calls
the callbacks for XmNpageIncrementCallback. The XmNvalueChanged-
Callback is called if the XmNpageIncrementCallback or XmN-
pageDecrementCallback is NULL.

PrimitiveHelp():
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.

PrimitiveNextTabGroup():
Traverses to the first item in the next tab group. If the cur-
rent tab group is the last entry in the tab group list, it wraps
to the beginning of the tab group list.

PrimitiveParentActivate():
If the parent is a manager, passes the event to the parent.

PrimitivePrevTabGroup():
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.

Release():If the button press occurs within the slider and the slider posi-
tion is changed, the callbacks for XmNvalueChangedCallback are
called.

Select(): (in arrow): Moves the slider by one increment in the direction
of the arrow. If XmNprocessingDirection is XmMAX_ON_RIGHT or Xm-
MAX_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 movement to the left or top calls the callbacks for XmNincre-
mentCallback. The XmNvalueChangedCallback is called if the XmN-
incrementCallback or XmNdecrementCallback is NULL.

(in scroll region between an arrow and the slider): Moves the slider by
one page increment in the direction of the arrow. If XmNprocessingDirec-
tion 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 XmNpageDecrementCallback. If XmN-
processingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, movement toward the
right or bottom calls the callbacks for XmNpageDecrementCallback, and move-
ment to the left or top calls the callbacks for XmNpageIncrementCallback.
The XmNvalueChangedCallback is called if the XmNpageIncrementCallback or
XmNpageDecrementCallback is NULL.

(in 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 XmN-
repeatDelay.

TopOrBottom():
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 Xm-
MAX_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, movement
toward the right or bottom calls the callbacks for XmNtoTopCall-
back, and movement to the left or top calls the callbacks for Xm-
NtoBottomCallback. The XmNvalueChangedCallback is called if the
XmNtoTopCallback or XmNtoBottomCallback is NULL. Pressing KBe-
ginLine 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).

RELATED INFORMATION
Core(3X), XmCreateScrollBar(3X), XmPrimitive(3X), XmScrollBarGetValues(3X),
and XmScrollBarSetValues(3X).

XmScrollBar(3X)