 |
Index for
Section 3X |
|
 |
Alphabetical
listing for X |
|
 |
Bottom of
page |
|
XmScrollBar(3X)
OSF/Motif
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
XmNdecrementCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNdragCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNincrement
Class: XmCIncrement
Default: 1
Type: int
Access: CSG
XmNincrementCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNinitialDelay
Class: XmCInitialDelay
Default: 250 ms
Type: int
Access: CSG
XmNmaximum
Class: XmCMaximum
Default: dynamic
Type: int
Access: CSG
XmNminimum
Class: XmCMinimum
Default: 0
Type: int
Access: CSG
XmNorientation
Class: XmCOrientation
Default: XmVERTICAL
Type: unsigned char
Access: CSG
XmNpageDecrementCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNpageIncrement
Class: XmCPageIncrement
Default: 10
Type: int
Access: CSG
XmNpageIncrementCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNprocessingDirection
Class: XmCProcessingDirection
Default: dynamic
Type: unsigned char
Access: CSG
XmNrepeatDelay
Class: XmCRepeatDelay
Default: 50 ms
Type: int
Access: CSG
XmNshowArrows
Class: XmCShowArrows
Default: True
Type: Boolean
Access: CSG
XmNsliderSize
Class: XmCSliderSize
Default: dynamic
Type: int
Access: CSG
XmNtoBottomCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNtoTopCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNtroughColor
Class: XmCTroughColor
Default: dynamic
Type: Pixel
Access: CSG
XmNvalue
Class: XmCValue
Default: dynamic
Type: int
Access: CSG
XmNvalueChangedCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: 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 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 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.
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.
XmPrimitive Resource Set
XmNbottomShadowColor
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNbottomShadowPixmap
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNforeground
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
XmNhelpCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNhighlightColor
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
XmNhighlightOnEnter
Class: XmCHighlightOnEnter
Default: False
Type: Boolean
Access: CSG
XmNhighlightPixmap
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNhighlightThickness
Class: XmCHighlightThickness
Default: dynamic
Type: Dimension
Access: CSG
XmNnavigationType
Class: XmCNavigationType
Default: XmSTICKY_TAB_GROUP
Type: XmNavigationType
Access: CSG
XmNshadowThickness
Class: XmCShadowThickness
Default: 2
Type: Dimension
Access: CSG
XmNtopShadowColor
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNtopShadowPixmap
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNtraversalOn
Class: XmCTraversalOn
Default: dynamic
Type: Boolean
Access: CSG
XmNunitType
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
XmNuserData
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Core Resource Set
XmNaccelerators
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: CSG
XmNancestorSensitive
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
XmNbackground
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
XmNbackgroundPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderColor
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
XmNborderPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderWidth
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
XmNcolormap
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
XmNdepth
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
XmNdestroyCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNheight
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
XmNinitialResourcesPersistent
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
XmNmappedWhenManaged
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
XmNscreen
Class: XmCScreen
Default: dynamic
Type: Screen *
Access: CG
XmNsensitive
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
XmNtranslations
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
Access: CSG
XmNwidth
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
XmNx
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
XmNy
Class: XmCPosition
Default: 0
Type: Position
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;
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 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
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 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.
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).
SEE ALSO
Core(3X), XmCreateScrollBar(3X), XmPrimitive(3X), XmScrollBarGetValues(3X),
XmScrollBarSetValues(3X)
|
Index for
Section 3X |
|
|
Alphabetical
listing for X |
|
 |
Top of
page |
|