XmScrollBar(3X) SDK X11 R4.11MU05 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 |
+-------------------------+------------------------+----------------+------------+--------+
|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 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 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.
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 |
+----------------------+-----------------------+------------------+----------------------+--------+
|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 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
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 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 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 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).
Licensed material--property of copyright holder(s)