XmScrollBar(3X) UNIX System V XmScrollBar(3X)
NAME
XmScrollBar - 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 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 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
10/89 Page 1
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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 | 100 | 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 | 0 | CSG |
|________________________|________________________|________________|____________|________|
|XmNvalueChangedCallback | XmCCallback | XtCallbackList| NULL | C |
|________________________|________________________|________________|____________|________|
Page 2 10/89
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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 incremental
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 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.
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_INCREMENT.
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.
XmNminimum
Specifies the slider's minimum value.
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
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
10/89 Page 3
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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 -
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
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.
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.
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.
Page 4 10/89
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
XmNvalue
Specifies the slider's position, between XmNminimum and
(XmNmaximum - XmNsliderSize). The value is constrained to be
within these inclusive bounds.
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
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 G
__________________________________________________________________________________________________
XmNshadowThickness XmCShadowThickness Dimension 2 CSG
__________________________________________________________________________________________________
XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG
__________________________________________________________________________________________________
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG
__________________________________________________________________________________________________
XmNtraversalOn XmCTraversalOn Boolean dynamic CSG
10/89 Page 5
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
|_____________________|_______________________|__________________|______________________|________|
|XmNunitType | XmCUnitType | unsigned char | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNuserData | XmCUserData | Pointer | 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 |
|_____________________________|_______________________________|________________|______________________|________|
Page 6 10/89
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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
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)
10/89 Page 7
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
KPageUp: PageUpOrLeft(0)
KPageDown: PageDownOrRight(0)
KPageLeft: PageUpOrLeft(1)
KPageRight: PageDownOrRight(1)
KBeginLine: TopOrBottom()
KEndLine: TopOrBottom()
KBeginData: TopOrBottom()
KEndData: TopOrBottom()
KNextField: PrimitiveNextTabGroup()
KPrevField: PrimitivePrevTabGroup()
KHelp: PrimitiveHelp()
Action Routines
The ScrollBar action routines are described below:
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
XmNincrementCallback. If XmNprocessingDirection is XmMAX_ON_LEFT
or XmMAX_ON_TOP, 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 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 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 XmMAX_ON_RIGHT or
XmMAX_ON_BOTTOM, movement toward the right or bottom calls the
callbacks for XmNpageIncrementCallback. If XmNprocessingDirection
Page 8 10/89
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
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 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.
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.
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 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
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 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
10/89 Page 9
XmScrollBar(3X) UNIX System V XmScrollBar(3X)
XmNpageIncrementCallback, and movement to the left or top calls the
callbacks for XmNpageDecrementCallback. If XmNprocessingDirection
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
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
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, 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 10 10/89