NAME¶

XmSpinBox — The SpinBox widget class "XmSpinBox" "widget class" "SpinBox"

SYNOPSIS¶

#include <Xm/SpinB.h>

DESCRIPTION¶

SpinBox allows the user to select a value from a ring of related but mutually exclusive choices which are displayed in sequence. The SpinBox always has an increment arrow, a decrement arrow, and one or more other children. The choices are displayed, one at a time, in a traversable text child ( XmText or XmTextField. The user clicks <Btn1> on an arrow to display the next (or previous) item in the ring of choices. By pressing and holding <Btn1> on an arrow, the user continuously cycles through the choices. The traversable children in a SpinBox can be of type XmNUMERIC or XmSTRING, as defined by the XmNspinBoxChildType constraint resource. The ring of choices for numeric children is defined by minimum, maximum, incremental, and decimal point values. The ring of choices for string children is defined in an array of compound strings. The application programmer can include multiple traversable children in the SpinBox. For example, a SpinBox might consist of a pair of arrows and month, day, and year text fields. The arrows only spin the child that currently has focus. Arrow size is specified by the SpinBox resource XmNarrowSize. This value sets both width and height of each arrow in pixels. The programmer can display SpinBox arrows in one of several layouts, as specified by the XmNarrowLayout resource:

XmARROWS_BEGINNING

Places a pair of left and right arrows before the children.

XmARROWS_END

Places a pair of left and right arrows after the children.

XmARROWS_SPLIT

Places one arrow on each side of the children.

XmARROWS_FLAT_BEGINNING

Places a pair of arrows side by side before the XmSpinBox children.

XmARROWS_FLAT_BEGINNING

Places a pair of arrows side by side after the XmSpinBox children.

Positions for XmARROWS_BEGINNING and XmARROWS_END are dependent on the VendorShell resource XmNlayoutDirection. When layout direction is left-to-right, beginning arrows are positioned to the left of the children. When layout direction is right-to-left, beginning arrows are positioned to the right. The actions of the arrows are determined by the VendorShell resource XmNlayoutDirection. For left-to-right layouts, the right arrow is the increment arrow and the left arrow is the decrement arrow. For right-to-left layouts, the right arrow is the decrement arrow and the left arrow is the increment arrow. For a numeric type child, the increment arrow increases the displayed value by the incremental value up to the maximum. The decrement arrow decreases the displayed value by the given incremental value down to the minimum. The increment arrow for a string type child moves toward the last entry of the array of compound strings (by increasing the SpinBox constraint resource XmNposition). The decrement arrow moves toward the first entry of the compound string array. The programmer can also control the sensitivity of each arrow in the SpinBox. Sensitive arrows spin choices; insensitive arrows do not spin choices. Arrow sensitivity is set for the SpinBox widget by using the XmNdefaultArrowSensitivity resource, but it can be modified on a per child basis by using the XmNarrowSensitivity constraint resource. SpinBox provides two callbacks to application programmers. (In addition, the callbacks of the SpinBox's children may be invoked.) Each of these callbacks receives a pointer to XmSpinBoxCallbackStruct. The XmNmodifyVerifyCallback procedures are called before a new choice is displayed. The XmNvalueChangedCallback procedures are called after a new choice is displayed. XmNmodifyVerifyCallback tells the application what the new position will be in the ring of choices. This callback can be used to make the SpinBox stop at the upper and lower limits or go to a different, nonconsecutive choice. The application allows the change in position by leaving the doit member set to True. The application can spin to a position other than the next consecutive position by leaving doit set to True and by changing the position member to the desired position. When doit is set to False by an application, there is no change in the choice displayed. After a new choice is displayed, the XmNvalueChangedCallback procedure is called. The application can use this procedure to perform tasks when specific values are reached or when boundaries are crossed. For example, if the user spins from January back to December, the application could change to the previous year. If the user spins from December to January, the application could change to the next year. SpinBox dimensions can be set using the Core resources XmNheight and XmNwidth. If dimensions are not specified, the SpinBox size is determined by the sizes of its arrows and children. The SpinBox will attempt to grow so that the arrows and all children are visible. SpinBox uses the XmQTaccessTextual trait and holds the XmQTnavigator trait.

Classes¶

SpinBox inherits behavior, resources, and traits from the Core, Composite, Constraint, and XmManager classes. The class pointer is xmSpinBoxWidgetClass. The class name is XmSpinBox.

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

XmSpinBox Resource
Set
Name	Class	Type	Default	Access
XmNarrowLayout	XmCArrowLayout	unsigned char	XmARROWS_BEGINNING	CSG
XmNarrowOrientation	XmCArrowOrientation	unsigned char	XmARROWS_VERTICAL	CSG
XmNarrowSize	XmCArrowSize	Dimension	16	CSG
XmNdefaultArrowSensitivity	XmCDefaultArrowSensitivity	unsigned char	XmARROWS_SENSITIVE	CSG
XmNdetailShadowThickness	XmCDetailShadowThickness	Dimension	2	CSG
XmNinitialDelay	XmCInitialDelay	unsigned int	250 ms	CSG
XmNmarginHeight	XmCMarginHeight	Dimension	dynamic	CSG
XmNmarginWidth	XmCMarginWidth	Dimension	dynamic	CSG
XmNmodifyVerifyCallback	XmCCallback	XtCallbackList	NULL	C
XmNrepeatDelay	XmCRepeatDelay	unsigned int	200 ms	CSG
XmNspacing	XmCSpacing	Dimension	dynamic	CSG
XmNvalueChangedCallback	XmCCallback	XtCallbackList	NULL	C

XmNarrowLayout

Specifies placement of the two arrows in the widget. Possible layouts are as follows:

XmNarrowSize

Specifies both the width and height of the arrow in pixels.

XmNdefaultArrowSensitivity

Specifies the default sensitivity of the arrows in the widget. Insensitive arrows change color, cannot be depressed, and perform no action. (This resource may be overridden by the constraint resource XmNarrowSensitivity for individual traversable text children of the SpinBox.) Possible default sensitivity values are as follows:

XmNdetailShadowThickness

Specifies the thickness of the inside arrow shadows. The default thickness is 2 pixels.

XmNinitialDelay

Specifies how long, in milliseconds, the mouse button must be held down before automatic spinning begins. In other words, when the user selects the increment or decrement arrow and keeps it depressed, this delay occurs before the choices start spinning. If XmNinitialDelay is 0, then XmNrepeatDelay is used as the initial delay.

XmNmarginHeight

Specifies the amount of blank space between the top edge of the SpinBox widget and the first item in each column, and the bottom edge of the SpinBox widget and the last item in each column.

XmNmarginWidth

Specifies the amount of blank space between the left edge of the SpinBox widget and the first item in each row, and the right edge of the SpinBox widget and the last item in each row.

XmNmodifyVerifyCallback

This callback is called before the SpinBox position changes (see the Constraint resource XmNposition). The application can use this callback to set the next position, change SpinBox resources, or cancel the impending action. For example, this callback can be used to stop the spinning just before wrapping at the upper and lower position boundaries. If the doit member is set to False, nothing happens. Otherwise the position changes. Reasons sent by the callback are XmCR_SPIN_NEXT, XmCR_SPIN_PRIOR, XmCR_SPIN_FIRST, or XmCR_SPIN_LAST.

XmNrepeatDelay

When the user selects and keeps an arrow button depressed by pressing and holding <Btn1>, spinning begins. After the time specified in XmNinitialDelay elapses, the SpinBox position changes automatically until the arrow button is released. The XmNrepeatDelay resource specifies the delay in milliseconds between each automatic change. If XmNrepeatDelay is set to 0 (zero), automatic spinning is turned off and XmNinitialDelay is ignored.

XmNspacing

Specifies the horizontal and vertical spacing between items contained within the SpinBox widget.

XmNvalueChangedCallback

This is called n+1 times for n SpinBox position changes (see the Constraint resource XmNposition). Reasons sent by the callback are XmCR_OK, XmCR_SPIN_NEXT, XmCR_SPIN_PRIOR, XmCR_SPIN_FIRST, or XmCR_SPIN_LAST. Other members are detailed in the callback structure description.

XmSpinBox Constraint
Resource Set
Name	Class	Type	Default	Access
XmNarrowSensitivity	XmCArrowSensitivity	unsigned char	XmARROWS_DEFAULT_SENSITIVITY	CSG
XmNdecimalPoints	XmCDecimalPoints	short	0	CSG
XmNincrementValue	XmCIncrementValue	int	1	CSG
XmNmaximumValue	XmCMaximumValue	int	10	CSG
XmNminimumValue	XmCMinimumValue	int	0	CSG
XmNnumValues	XmCNumValues	int	0	CSG
XmNposition	XmCPosition	int	0	CSG
XmNpositionType	XmCPositionType	char	XmPOSITION_VALUE	CG
XmNspinBoxChildType	XmSpinBoxChildType	unsigned char	XmSTRING	CG
XmNvalues	XmCValues	XmStringTable	NULL	CSG

XmNarrowSensitivity

Specifies the sensitivity of the arrows for a SpinBox child. By using this resource in the definition of a SpinBox child, the application programmer can override the default SpinBox sensitivity (set by XmNdefaultArrowSensitivity) for a particular child. This allows each traversable child to have a different arrow sensitivity. The arrow sensitivity values are as follows:

XmNdecimalPoints

Specifies the number of decimal places used when displaying the value of a SpinBox numeric type child. If the number of decimal places specified is greater than the number of digits in a displayed value, the value is padded with 0 (zeros). For example, when XmNinitialValue is 1 and XmNmaximumValue is 1000 and XmNdecimalPoints is 3, the range of values displayed in the SpinBox is 0.001 to 1.000. This is used only when XmNspinBoxChildType is XmNUMERIC.

XmNincrementValue

Specifies the amount by which to increment or decrement a SpinBox numeric type child. This is used only when XmNspinBoxChildType is XmNUMERIC.

XmNmaximumValue

Specifies the highest possible value for a numeric SpinBox. This is used only when XmNspinBoxChildType is XmNUMERIC.

XmNminimumValue

Specifies the lowest possible value for a numeric SpinBox. This is used only when XmNspinBoxChildType is XmNUMERIC.

XmNnumValues

Specifies the number of strings in XmNvalues. The application must change this value when strings are added or removed from XmNvalues. This is used only when XmNspinBoxChildType is XmSTRING.

XmNposition

Specifies the position of the currently displayed item. The interpritation of XmNposition is dependent upon the value of the XmNpositionType resource.

When XmNpositionType is XmPOSITION_INDEX the XmNposition value is interpreted as follows: For XmSpinBox children of type XmNUMERIC, the XmNposition resource is interpreted as an index into an array of items. The minimum allowable value for XmNposition is 0. The maximum allowable value for XmNposition is (XmNmaximumValue-XmNminimumValue)/XmNincrementValue. The value display by the XmSpinBox child is XmNminimumValue+(XmNposition*XmNincrementValue). For XmSpinBox children of type XmSTRING, the XmNposition resource is interpreted as an index into an array of XmNnumValues items. The minimum allowable value for XmNposition is 0. The maximum allowable value for XmNposition is XmNnumValues - 1. The value displayed by the XmSpinBox is the XmNposition'th value in the XmNvalues array.

When XmNpositionType is XmPOSITION_VALUE the XmNposition value is interpreted as follows:

For XmSpinBox children of type XmNUMERIC, the XmNposition resource is interpreted as the actual value to be displayed. The minimum allowable value for XmNposition is XmNminimumValue. The maximum allowable value for XmNposition is XmNmaximumValue. The value displayed by the XmSpinBox child is XmNposition. For XmSpinBox children of type XmSTRING, the interpretation is the same for XmPOSITION_VALUE as for XmPOSITION_INDEX.

Position values falling outside the specified range are invalid. When an application assigns a value to XmNposition which is less than the minimum, XmNposition is set to the minimum and an error message is displayed. When an application assigns a value to XmNposition which is greater than the maximum, XmNposition is set to the maximum and an error message is displayed.

XmNpositionType

Specifies how values the XmNposition resource are to be interpreted. Valid values include XmPOSITION_INDEX and XmPOSITION_VALUE.

XmNspinBoxChildType

Specifies the type of data displayed in the child:

XmNvalues

Specifies the array of XmStrings to be displayed in a SpinBox string type child. The application must change XmNnumValues when strings are added to or removed from XmNvalues. This is used only when XmNspinBoxChildType is XmSTRING.

Inherited Resources¶

SpinBox inherits behavior and resources from the superclasses described in the following tables. For a complete description of each resource, refer to the reference page for that superclass.

XmManager 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
XmNhighlightPixmap	XmCHighlightPixmap	Pixmap	dynamic	CSG
XmNinitialFocus	XmCInitialFocus	Widget	dynamic	CSG
XmNlayoutDirection	XmCLayoutDirection	XmDirection	dynamic	CG
XmNnavigationType	XmCNavigationType	XmNavigationType	XmTAB_GROUP	CSG
XmNpopupHandlerCallback	XmCCallback	XtCallbackList	NULL	C
XmNshadowThickness	XmCShadowThickness	Dimension	0	CSG
XmNstringDirection	XmCStringDirection	XmStringDirection	dynamic	CG
XmNtopShadowColor	XmCTopShadowColor	Pixel	dynamic	CSG
XmNtopShadowPixmap	XmCTopShadowPixmap	Pixmap	dynamic	CSG
XmNtraversalOn	XmCTraversalOn	Boolean	True	CSG
XmNunitType	XmCUnitType	unsigned char	dynamic	CSG
XmNuserData	XmCUserData	XtPointer	NULL	CSG

Composite Resource
Set
Name	Class	Type	Default	Access
XmNchildren	XmCReadOnly	WidgetList	NULL	G
XmNinsertPosition	XmCInsertPosition	XtOrderProc	NULL	CSG
XmNnumChildren	XmCReadOnly	Cardinal	0	G

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

Callback¶

A pointer to the following structure is passed to each callback:

typedef struct
{
        int  reason;
        XEvent  * event;
        Widget  widget;
        Boolean  doit;
        int  position;
        XmString  value;
        Boolean  crossed_boundary;
} XmSpinBoxCallbackStruct;

reason

Indicates why the callback was invoked. Reasons may be the following:

event

Points to the XEvent that triggered this callback.

widget

Specifies the child widget affected by this callback.

doit

When the callback is XmNmodifyVerifyCallback, doit indicates whether or not an action will be performed before the SpinBox position changes. If the callback leaves doit set to True (the default), the spinning action is performed. If the callback sets doit to False, the spinning action is not performed. When the callback is XmNvalueChangedCallback, doit is ignored.

position

Specifies the next value of the SpinBox position (same as XmNposition). This is an output field for the XmNmodifyVerifyCallback, which may change the next position as dictated by the needs of an application.

value

Specifies the new XmString value in the text child widget. The user program must copy this string if it is to be used outside the callback routine.

crossed_boundary

Specifies whether or not the SpinBox has crossed the upper or lower boundary (the last or first compound string, or the maximum or minimum value). The crossed_boundary value is True if the SpinBox has just crossed a boundary, and False if it has not.

Translations¶

The XmSpinBox translations are as follows: The following key names are listed in the X standard key event translation table syntax. This format is the one used by Motif to specify the widget actions corresponding to a given key. A brief overview of the format is provided under VirtualBindings(3). For a complete description of the format, please refer to the X Toolkit Instrinsics Documentation.

<Btn1Down>:

SpinBArm()

<Btn1Up>:

SpinBDisarm()

:<Key><osfUp> :

SpinBPrior()

:<Key><osfDown> :

SpinBNext()

:<Key><osfLeft> :

SpinBLeft()

:<Key><osfRight> :

SpinBRight()

:<Key><osfBeginData> :

SpinBFirst()

:<Key><osfEndData> :

SpinBLast()

Accelerators¶

The XmNaccelerators resource of a SpinBox are added to each traversable text child. The default XmNaccelerators are defined in the following list. The bindings for <Key><osfUp> and <Key> <osfDown> cannot be changed.

<Key> <osfUp>:

SpinBPrior()

<Key> <osfDown>:

SpinBNext()

<KeyUp> <osfUp>:

SpinBDisarm()

<KeyUp> <osfDown>:

SpinBDisarm()

<Key> <osfLeft>:

SpinBLeft()

<Key> <osfRight>:

SpinBRight()

<KeyUp> <osfLeft>:

SpinBDisarm()

<KeyUp> <osfRight>:

SpinBDisarm()

<Key> <osfBeginData>:

SpinBFirst()

<Key> <osfEndData>:

SpinBLast()

Action Routines¶

The XmSpinBox action routines are as follows:

SpinBArm():

Visually arms the SpinBox by drawing the armed arrow so that it appears to be depressed. This action is initiated when the user presses <Btn1> while the pointer is within the boundaries of either the increment or decrement arrow. The arrow remains visually armed as long as <Btn1> remains depressed.

If the time period specified by XmNrepeatDelay is not greater than zero milliseconds, nothing else happens while <Btn1> remains depressed.

If the time period specified by XmNrepeatDelay is greater than zero milliseconds, and the arrow is disarmed before the time period specified by XmNinitialDelay has elapsed, nothing else happens in this action.

If the time period specified by XmNrepeatDelay is greater than zero milliseconds, and the arrow is still armed after the time period specified by XmNinitialDelay has elapsed, the following occurs:

If doit remains set to True, the following occurs:

These events are repeated each time the XmNrepeatDelay period elapses and the arrow remains armed.

SpinBDisarm():

Visually disarms the SpinBox by drawing the previously armed arrow so that it no longer appears to be depressed.

If the time period specified by XmNrepeatDelay is not greater than zero milliseconds, or the time period specified by XmNinitialDelay has not elapsed, the following then occurs:

If doit remains set to True, the following occurs:

If an XmNvalueChangedCallback procedure is issued after the button has been armed, regardless of the value of XmNrepeatDelay or whether the XmNinitialDelay has expired:

SpinBFirst():

The following occurs:

If doit remains set to True, the following occurs:

SpinBLast():

The following occurs:

If doit remains set to True, the following occurs:

SpinBLeft():

If the VendorShell resource XmNlayoutDirection is left-to-right, the SpinBPrior action is invoked. Otherwise, the SpinBNext action is invoked.

SpinBNext():

Visually arms the SpinBox by drawing the increment arrow so that it appears to be depressed. The following occurs:

If doit remains set to True, the following occurs:

SpinBPrior():

Visually arms the SpinBox by drawing the decrement arrow so that it appears to be depressed. The following occurs:

If doit remains set to True, the following occurs:

SpinBRight():

If the VendorShell resource XmNlayoutDirection is left-to-right, the SpinBNext action is invoked. Otherwise, the SpinBPrior action is invoked.

RELATED¶

Composite(3), Constraint(3), Core(3), XmCreateSpinBox(3), XmManager(3), XmString(3), XmVaCreateSpinBox(3), and XmVaCreateManagedSpinBox(3).