XmScrollBar(3Xm) XmScrollBar(3Xm)
NAME
XmScrollBar - the ScrollBar widget class.
AES SUPPORT LEVEL
full-use
SYNOPSIS
#include <Xm/ScrollBar.h>
DESCRIPTION
The ScrollBar widget allows the user to view data that
is too large to be displayed at one time. ScrollBars
are usually located beside or within 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 selecting on either arrow or the scroll region, or
by dragging the slider. When an arrow is selected, the
slider within the scroll region will be moved in the
direction of the arrow by an amount supplied by the
application. If the mouse button is held down, the
slider will continue to move at a constant rate.
The ratio of the slider size and the scroll region size
corresponds to the relationship between the size of the
visible data and the total size of the data. For
example, if ten percent of the data is visible, the
slider will occupy ten 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
- 1 -
XmScrollBar(3Xm) XmScrollBar(3Xm)
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
lower case or upper case, 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 CSG
XmNmaximum XmCMaximum int 0 CSG
XmNminimum XmCMinimum int 0 CSG
XmNorientation XmCOrientation unsigned char XmVERTICAL CSG
XmNpageDecrementCallback XmCCallback XtCallbackList NULL CSG
XmNpageIncrement XmCPageIncrement int 10 C
XmNpageIncrementCallback XmCCallback XtCallbackList NULL C
XmNprocessingDirection XmCProcessingDirection unsigned char XmMAX_ON_BOTTOM CSG
XmNrepeatDelay XmCRepeatDelay int 50 CSG
XmNshowArrows XmCShowArrows Boolean True CSG
XmNsliderSize XmCSliderSize int 10 CSG
XmNtoBottomCallback XmCCallback XtCallbackList NULL C
XmNtoTopCallback XmCCallback XtCallbackList NULL C
XmNvalue XmCValue int 0 CSG
XmNvalueChangedCallback XmCCallback XtCallbackList NULL C
XmNdecrementCallback
Specifies the list of callbacks that is called
when an arrow is selected which decreases the
slider value by one increment. The reason sent by
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 to move the slider when the
corresponding arrow is selected.
- 2 -
XmScrollBar(3Xm) XmScrollBar(3Xm)
XmNincrementCallback
Specifies the list of callbacks that is called
when an arrow is selected which increases the
slider value by one increment. The reason sent by
the callback is XmCR_INCREMENT.
XmNinitialDelay
Specifies the amount of time to wait
(milliseconds) before starting continuous slider
movement while an arrow or the scroll region is
being pressed.
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 slider area is selected and the slider
value is decreased by one page increment. The
reason sent by the callback is
XmCR_PAGE_DECREMENT.
XmNpageIncrement
Specifies the amount to move the slider when
selection occurs on the slide area.
XmNpageIncrementCallback
Specifies the list of callbacks that is called
when the slider area is selected and the slider
value is increased by one page increment. The
reason sent by 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.
XmNrepeatDelay
Specifies the amount of time to wait
(milliseconds) between subsequent slider movements
- 3 -
XmScrollBar(3Xm) XmScrollBar(3Xm)
after the XmNinitialDelay has been processed.
XmNshowArrows
Specifies whether the arrows are displayed.
XmNsliderSize
Specifies the size of the slider between the
values of 0 and maximum - minimum.
XmNtoBottomCallback
Specifies the list of callbacks that are called
when the user selects <Shift> mouse button 1 down
in the bottom arrow button. This callback sends
as a value the maximum ScrollBar value minus the
ScrollBar slider size. The slider location is not
automatically repositioned. The reason sent by
the callback is XmCR_TO_BOTTOM.
XmNtoTopCallback
Specifies the list of callbacks that are called
when the user selects <Shift> mouse button 1 down
in the top arrow button. This callback sends as a
value the minimum ScrollBar slider value. The
slider location is not automatically repositioned.
The reason sent by the callback is XmCR_TO_TOP.
XmNvalue
Specifies the slider's position between minimum
and maximum.
XmNvalueChangedCallback
Specifies the list of callbacks that is called
when the slider is released while being dragged;
this is in place of XmNincrementCallback,
XmNdecrementCallback, XmNpageIncrementCallback or
XmNpageDecrementCallback when they do not have any
callbacks attached. The reason sent by the
callback is XmCR_VALUE_CHANGED.
Inherited Resources
ScrollBar inherits behavior and resources from the
following superclasses. For a complete description of
these resources, refer to the man page for that
superclass.
XmPrimitive Resource Set
Name Class Type Default Access
______________________________________________________________________________________________
XmNbottomShadowColor XmCForeground Pixel dynamic CSG
- 4 -
XmScrollBar(3Xm) XmScrollBar(3Xm)
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCForeground Pixel Black CSG
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNhighlightThickness XmCHighlightThickness short 0 CSG
XmNshadowThickness XmCShadowThickness short 2 CSG
XmNtopShadowColor XmCBackground Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNtraversalOn XmCTraversalOn Boolean False CSG
XmNuserData XmCUserData caddr_t NULL CSG
Core Resource Set
Name Class Type Default Access
____________________________________________________________________________________________
XmNaccelerators XmCAccelerators XtTranslations NULL CSG
XmNancestorSensitive XmCSensitive Boolean True G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderColor XmCBorderColor Pixel Black CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap XtCopyFromParent CG
XmNdepth XmCDepth int XtCopyFromParent CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension 0 CSG
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Pointer XtCopyScreen CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations NULL CSG
XmNwidth XmCWidth Dimension 0 CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Callback Information
The following structure is returned with 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.
- 5 -
XmScrollBar(3Xm) XmScrollBar(3Xm)
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.
Behavior
<Btn1Down>:
(in arrow): Moves the slider one increment or
decrement in the direction of the arrow and calls
the callbacks for XmNincrementCallback or
XmNdecrementCallback. The
XmNvalueChangedCallbacks will be called if the
XmNincrementCallbacks or XmNdecrementCallbacks are
empty.
(in scroll region): Moves the slider one page
increment or page decrement depending on which
side of the slider is selected and calls the
callbacks for XmNpageIncrementCallback or
XmNpageDecrementCallback. The
XmNvalueChangedCallbacks will be called if the
XmNpageIncrementCallbacks or
XmNpageDecrementCallbacks are empty.
(in slider): Activates the interactive dragging
of the slider. If the button is held down in
either the arrows or scroll region longer than the
XmNinitialDelay resource, then 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.
Button1<PtrMoved>:
If the button press occurs within the slider, the
subsequent motion events move the slider to the
new position and the callbacks for XmNdragCallback
are called.
<Btn1Up>:
If the button press occurs within the slider and
the slider position is changed, then the callbacks
for XmNvalueChangedCallback are called.
Shift<Btn1Down>:
This mouse button press in the top arrow button
causes the callbacks for XmNtoTopCallback to be
called.
- 6 -
XmScrollBar(3Xm) XmScrollBar(3Xm)
Shift<Btn1Down>:
This mouse button press in the bottom arrow button
causes the callbacks for XmNtoBottomCallback to be
called.
<Key>Up:
For vertical ScrollBars, pressing the up arrow
cursor key decrements the slider one unit and
calls XmNdecrementCallback. The
XmNvalueChangedCallbacks will be called if the
XmNdecrementCallbacks are empty.
<Key>Down:
For vertical ScrollBars, pressing the down arrow
cursor key increments the slider one unit and
calls XmNincrementCallback. The
XmNvalueChangedCallbacks will be called if the
XmNincrementCallbacks are empty.
<Key>Left:
For horizontal ScrollBars, pressing the left arrow
cursor key decrements the slider one unit and
calls XmNdecrementCallback. The
XmNvalueChangedCallbacks will be called if the
XmNdecrementCallbacks are empty.
<Key>Right:
For horizontal ScrollBars, pressing the right
arrow cursor key increments the slider one unit
and calls XmNincrementCallback. The
XmNvalueChangedCallbacks will be called if the
XmNincrementCallbacks are empty.
Default Translations
~Shift ~Ctrl ~Meta ~Alt <Btn1Down>:Select()
~Shift ~Ctrl ~Meta ~Alt <Btn1Up>:Release()
~Shift ~Ctrl ~Meta ~Alt Button1<PtrMoved>:Moved()
Shift ~Ctrl ~Meta ~Alt <Btn1Down>:GoToTop()
Shift ~Ctrl ~Meta ~Alt <Btn1Down>:GoToBottom()
~Shift ~Ctrl ~Meta ~Alt <Key>Up:UpOrLeft(0)
~Shift ~Ctrl ~Meta ~Alt <Key>Down:DownOrRight(0)
~Shift ~Ctrl ~Meta ~Alt <Key>Left:UpOrLeft(1)
~Shift ~Ctrl ~Meta ~Alt <Key>Right:DownOrRight(1)
<EnterWindow>: Enter()
<LeaveWindow>: Leave()
Keyboard Traversal
If the XtNtraversalOn resource is set to True at either
create time or during a call to XtSetValues, the
Manager superclass will automatically augment the
- 7 -
XmScrollBar(3Xm) XmScrollBar(3Xm)
Manager widget's translations to support keyboard
traversal. Refer to XmManager(3X) for a complete
description of these translations.
RELATED INFORMATION
Core(3X), XmCreateScrollBar(3X), XmPrimitive(3X),
XmScrollBarGetValues(3X), and XmScrollBarSetValues(3X).
- 8 -