XmScrollBar(Xm) UNIX System V
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 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 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
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 to move the slider when the
corresponding arrow is selected.
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
XmCRINCREMENT.
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 XmCRPAGEDECREMENT.
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 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.
XmNrepeatDelay
Specifies the amount of time to wait (milliseconds)
between subsequent slider movements 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
XmCRTOBOTTOM.
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 XmCRTOTOP.
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 XmCRVALUECHANGED.
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
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
XmNunitType XmCUnitType unsigned char XmPIXELS 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.
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.
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 Manager widget's
translations to support keyboard traversal. Refer to
XmManager(Xm) for a complete description of these
translations.
RELATED INFORMATION
Core(Xm), XmCreateScrollBar(Xm), XmPrimitive(Xm),
XmScrollBarGetValues(Xm), and XmScrollBarSetValues(Xm).
(printed 2/14/90) XmScrollBar(Xm)