XmScrollBar(3Xm)

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 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.

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 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
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(3Xm) for a complete description of these translations.

RELATED INFORMATION
Core(3Xm), XmCreateScrollBar(3Xm), XmPrimitive(3Xm), XmScrollBarGetValues(3Xm), and XmScrollBarSetValues(3Xm).