[Contents]
[Index]
[Next]
[Previous]
XmScrollBar
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).
- 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. 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
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
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.
- 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
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.
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)
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
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 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.
- 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 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
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).