XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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 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 continues to move at a constant rate.
The ratio of the slider size to the scroll region size
typically corresponds 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 visible, 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 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
Page 1 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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 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
XmCRDECREMENT.
XmNdragCallback
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 XmCRDRAG.
XmNincrement
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
Page 2 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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.
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
XmCRINCREMENT.
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.
XmNmaximum
Specifies 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.
XmNminimum
Specifies the slider's minimum value. XmNmaximum
must be greater than XmNminimum.
XmNorientation
Specifies whether the ScrollBar is displayed
vertically or horizontally. This resource can
have values of XmVERTICAL and XmHORIZONTAL.
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
XmCRPAGEDECREMENT.
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
XmNpageIncrement and (previous XmNvalue -
XmNminimum) when the slider moves to the end of
the ScrollBar with the minimum value, and the
Page 3 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
lesser of XmNpageIncrement 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.
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
XmCRPAGEINCREMENT.
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 XmMAXONTOP,
XmMAXONBOTTOM,XmMAXONLEFT, and XmMAXONRIGHT.
If the XmScrollBar is oriented vertically, the
default value is XmMAXONBOTTOM. 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 subsequent 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 -
XmNminimum) divided by 10, with a minimum of 1.
Page 4 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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 XmCRTOBOTTOM.
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 XmCRTOTOP.
XmNtroughColor
Specifies the color of the slider trough.
XmNvalue Specifies 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.
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,
XmNpageIncrementCallback,
XmNpageDecrementCallback, 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 XmCRVALUECHANGED.
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
Page 5 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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.
Page 6 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
pixel 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 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: 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()
Page 7 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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 XmMAXONRIGHT or
XmMAXONBOTTOM, movement toward the right or
bottom calls the callbacks for
XmNincrementCallback. If XmNprocessingDirection
is XmMAXONLEFT or XmMAXONTOP, movement toward
the right or bottom calls the callbacks 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 XmMAXONRIGHT or
XmMAXONBOTTOM, movement to the left or top calls
the callbacks for XmNdecrementCallback. If
XmNprocessingDirection is XmMAXONLEFT or
XmMAXONTOP, 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 motion 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 increment. With an argument of 1, moves
the slider right by one page increment. If
XmNprocessingDirection is XmMAXONRIGHT or
Page 8 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
XmMAXONBOTTOM, movement toward the right or
bottom calls the callbacks for
XmNpageIncrementCallback. If
XmNprocessingDirection is XmMAXONLEFT or
XmMAXONTOP, 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 increment. If
XmNprocessingDirection is XmMAXONRIGHT or
XmMAXONBOTTOM, movement to the left or top calls
the callbacks for XmNpageDecrementCallback. If
XmNprocessingDirection is XmMAXONLEFT or
XmMAXONTOP, movement to the left or top calls
the callbacks for XmNpageIncrementCallback. The
XmNvalueChangedCallback is called if the
XmNpageIncrementCallback or
XmNpageDecrementCallback 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 current 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 position is changed, the callbacks for
XmNvalueChangedCallback are called.
Select(): (in arrow): Moves the slider by one increment in
Page 9 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
the direction of the arrow. If
XmNprocessingDirection is XmMAXONRIGHT or
XmMAXONBOTTOM, movement toward the right or
bottom calls the callbacks for
XmNincrementCallback, and movement to the left or
top calls the callbacks for XmNdecrementCallback.
If XmNprocessingDirection is XmMAXONLEFT or
XmMAXONTOP, 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 scroll region between an arrow and the
slider): Moves the slider by one page increment
in the direction of the arrow. If
XmNprocessingDirection is XmMAXONRIGHT or
XmMAXONBOTTOM, movement toward the right or
bottom calls the callbacks for
XmNpageIncrementCallback, and movement to the left
or top calls the callbacks for
XmNpageDecrementCallback. If
XmNprocessingDirection is XmMAXONLEFT or
XmMAXONTOP, movement toward the right or bottom
calls the callbacks for XmNpageDecrementCallback,
and movement 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
XmNrepeatDelay.
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
XmMAXONRIGHT or XmMAXONBOTTOM, movement toward
the right or bottom calls the callbacks for
XmNtoBottomCallback, and movement to the left or
Page 10 (printed 4/30/98)
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
top calls the callbacks for XmNtoTopCallback. If
XmNprocessingDirection is XmMAXONLEFT or
XmMAXONTOP, 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 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 XmNtoBottomCallback.
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).
Page 11 (printed 4/30/98)