XmScrollBar(X3mot)

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

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

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

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

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 XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, then movement toward the right or bottom calls the callbacks for XmNincrementCallback. If XmNprocessingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, then 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, then movement to the left or top calls the callbacks for XmNdecrementCallback. If XmNprocessingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, then 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, then movement toward the right or bottom calls the callbacks for XmNpageIncrementCallback. If XmNprocessingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, then 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, then movement to the left or top calls the callbacks for XmNpageDecrementCallback. If XmNprocessingDirection is XmMAX_ON_LEFT or XmMAX_ON_TOP, then 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 XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, then 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, then 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 XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, then 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, then 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 XmMAX_ON_RIGHT or XmMAX_ON_BOTTOM, then 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, then 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(X3mot).

References

Core(X3mot), XmCreateScrollBar(X3mot), XmPrimitive(X3mot), XmScrollBarGetValues(X3mot) and XmScrollBarSetValues(X3mot).