XmScrollBar(3X) 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 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: XtCallback-
List 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: XmCCall-
back 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. 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 of XmNincrement 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 maximum
value. ScrollBars contained within ScrolledWindows have a maximum equal to the size of ScrollBar (that is, the height if it is ver-
tical, or the width if it is horizontal). XmNmaximum must be greater than XmNminimum. Specifies the slider's minimum value. XmNmax-
imum must be greater than XmNminimum. Specifies whether the ScrollBar is displayed vertically or horizontally. This resource can
have values of XmVERTICAL 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- 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_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 XmN-
stringDirection resource. 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. 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. 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. 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 XmNminimum and (XmNmaximum- XmNsliderSize). The value is con-
strained 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 XmNin-
crementCallback, 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
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: XmCMapped-
WhenManaged 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: Posi-
tion Access: 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;
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 coordinate.
Translations
XmScrollBar includes translations from Primitive. The XmScrollBar translations are listed below. These translations may not directly corre-
spond 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: IncrementU-
pOrLeft(0) MCtrl KUp: PageUpOrLeft(0) KDown: IncrementDownOrRight(0) MCtrl KDown: PageDownOrRight(0) KLeft: Incremen-
tUpOrLeft(1) MCtrl KLeft: PageUpOrLeft(1) KRight: IncrementDownOrRight(1) MCtrl KRight: PageDownOrRight(1) KPageUp: PageU-
pOrLeft(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: 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 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 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, move-
ment to the left or top calls the callbacks for XmNincrementCallback. The XmNvalueChangedCallback is called if the XmNincrementCallback 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 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 XmNprocessingDirection is XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, movement
toward the right or bottom calls the callbacks for XmNpageIncrementCallback. 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 XmN-
pageIncrementCallback 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 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 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 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 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 XmN-
processingDirection is XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, movement toward the right or bottom calls the callbacks for XmNpageIncre-
mentCallback, 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 XmNpageIncrement-
Callback 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, 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).
SEE ALSO
Core(3X), XmCreateScrollBar(3X), XmPrimitive(3X), XmScrollBarGetValues(3X), XmScrollBarSetValues(3X)
XmScrollBar(3X)