XmSimpleSpinBox(library call) XmSimpleSpinBox(library call)

NAME

XmSimpleSpinBox -- a simple SpinBox widget class

SYNOPSIS

#include <Xm/SSpinB.h>

DESCRIPTION

The XmSimpleSpinBox widget is a user interface control to increment
and decrement an arbitrary TextField. For example, it can be used to
cycle through the months of the year or days of the month.

Widget subclassing is not supported for the XmSimpleSpinBox widget
class.

Classes

The XmSimpleSpinBox widget inherits behavior and resources from the
Core, Composite and XmManager classes.

The class pointer is XmSimpleSpinBoxWidgetClass.

The class name is XmSimpleSpinBoxWidget.

New Resources

The following table defines a set of widget resources used by the
application to specify data. The application 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, the application must 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, the application must remove the Xm
prefix and use the remaining letters (in either lower case or upper
case, but including 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).

XmSimpleSpinBox Resource
Set
Name Class Type Default Access
XmNarrowLayout XmCArrowLayout unsigned char XmARROWS_END CSG
XmNarrowSensitivity XmCArrowSensitivity unsigned char XmARROWS-_SENSITIVE CSG
XmNcolumns XmCColumn short 20 CSG
XmNdecimalPoints XmCDecimalPoints short 0 CSG
XmNeditable XmCEditable Boolean True CSG
XmNincrementValue XmCIncrementValue int 1 CSG
XmNinitialDelay XmCInitialDelay unsigned int 250 CSG
XmNmaximumValue XmCMaximumValue int 10 CSG
XmNminimumValue XmCMinimumValue int 0 CSG
XmNmodifyVerifyCallback XmCCallback XtCallbackList NULL C
XmNnumValues XmCNumValues int 0 CSG
XmNposition XmCPosition int 0 CSG
XmNrepeatDelay XmCRepeatDelay unsigned int 200 CSG
XmNspinBoxChildType XmCSpinBoxChildType unsigned char XmSTRING CG
XmNtextField XmCTextField Widget dynamic G
XmNvalueChangedCallback XmCCallback XtCallbackList NULL C
XmNvalues XmCValues XmStringTable NULL CSG

XmNarrowLayout
Specifies the style and position of the SpinBox arrows. The
following values are supported:

XmARROWS_FLAT_BEGINNING
The arrows are placed side by side to the right
of the TextField.

XmARROWS_FLAT_END
The arrows are placed side by side to the left of
the TextField.

XmARROWS_SPLIT
The down arrow is on the left and the up arrow is
on the right of the TextField.

XmARROWS_BEGINNING
The arrows are stacked and placed on the left of
the TextField.

XmARROWS_END
The arrows are stacked and placed on the right of
the TextField.

XmNarrowSensitivity
Specifies the sensitivity of the arrows in the
XmSimpleSpinBox. The following values are supported:

XmARROWS_SENSITIVE
Both arrows are active to user selection.

XmARROWS_DECREMENT_SENSITIVE
The down arrow is active and the up arrow is
inactive to user selection.

XmARROWS_INCREMENT_SENSITIVE
The up arrow is active and the down arrow is
inactive to user selection.

XmARROWS_INSENSITIVE
Both arrows are inactive to user selection.

XmNcolumns
Specifies the number of columns of the text field.

XmNdecimalPoints
Specifies the position of the radix character within the
numeric value when XmNspinBoxChildType is XmNUMERIC. This
resource is used to allow for floating point values in the
XmSimpleSpinBox widget.

XmNeditable
Specifies whether the text field can take input.


When XmNeditable is used on a widget it sets the dropsite
to XmDROP_SITE_ACTIVE.

XmNincrementValue
Specifies the amount to increment or decrement the
XmNposition when the XmNspinBoxChildType is XmNUMERIC. When
the Up action is activated, the XmNincrementValue is added
to the XmNposition value; when the Down action is
activated, the XmNincrementValue is subtracted from the
XmNposition value. When XmNspinBoxChildType is XmSTRING,
this resource is ignored.

XmNinitialDelay
Specifies the amount of time in milliseconds before the
Arrow buttons will begin to spin continuously.

XmNnumValues
Specifies the number of items in the XmNvalues list when
the XmNspinBoxChildType resource is XmSTRING. The value of
this resource must be a positive integer. The XmNnumValues
is maintained by the XmSimpleSpinBox widget when items are
added or deleted from the XmNvalues list. When
XmNspinBoxChildType is not XmSTRING, this resource is
ignored.

XmNvalues Supplies the list of strings to cycle through when the
XmNspinButtonChildType resource is XmSTRING. When
XmNspinBoxChildType is not XmSTRING, this resource is
ignored.

XmNmaximumValue
Specifies the upper bound on the XmSimpleSpinBox's range
when XmNspinBoxChildType is XmNUMERIC.

XmNminimumValue
Specifies the lower bound on the XmSimpleSpinBox's range
when XmNspinBoxChildType is XmNUMERIC.

XmNmodifyVerifyCallback
Specifies the callback to be invoked just before the
XmSimpleSpinBox position changes. The application can use
this callback to implement new application-related logic
(including setting new position spinning to, or canceling
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 application sets the
doit member of the XmSimpleSpinBoxCallbackStruct to False,
nothing happens. Otherwise, the position changes. Reasons
sent by the callback are XmCR_SPIN_NEXT, or
XmCR_SPIN_PRIOR.

XmNposition
The XmNposition resource has a different value based on the
XmNspinBoxChildType resource. When XmNspinBoxChildType is
XmSTRING, the XmNposition is the index into the XmNvalues
list for the current item. When the XmNspinBoxChildType
resource is XmNUMERIC, the XmNposition is the integer value
of the XmSimpleSpinBox that falls within the range of
XmNmaximumValue and XmNminimumValue.

XmNrepeatDelay
Specifies the number of milliseconds between repeated calls
to the XmNvalueChangedCallback while the user is spinning
the XmSimpleSpinBox.

XmNspinBoxChildType
Specifies the style of the XmSimpleSpinBox. The following
values are supported:

XmSTRING The child is a string value that is specified
through the XmNvalues resource and incremented
and decremented by changing the XmNposition
resource.

XmNUMERIC The child is a numeric value that is specified
through the XmNposition resource and incremented
according to the XmNincrementValue resource.

XmtextField
Specifies the textfield widget.

XmNvalueChangedCallback
Specifies the callback to be invoked whenever the value of
the XmNposition resource is changed through the use of the
spinner arrows. The XmNvalueChangedCallback passes the
XmSimpleSpinBoxCallbackStruct call_data structure.

Inherited Resources

The XmSimpleSpinBox widget inherits behavior and resources from the
following named superclasses. For a complete description of each
resource, see the man 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 NULL CSG
XmNnavigationType XmCNavigationType XmNavigationType dynamic CSG
XmNshadowThickness XmCShadowThickness Dimension dynamic CSG
XmNstringDirection XmCStringDirection XmStringDirection dynamic CG
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

Composite Resource
Set
Name Class Type Default Access
XmNchildren XmCReadOnly WidgetList NULL G
XmNinsertPosition XmCInsertPosition XtOrderProc default procedure 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 Information

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

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

The reason argument indicates why the callback was invoked. There are
three possible reasons for this callback to be issued. The reason is
XmCR_OK when this is the first call to the callback at the beginning
of a spin or if it is a single activation of the spin arrows. If the
XmSimpleSpinBox is in the process of being continuously spun, then
the reason will be XmCR_SPIN_NEXT or XmCR_SPIN_PRIOR, depending on
the arrow that is spinning.

The event argument points to the XEvent that triggered the callback.
It can be NULL when the XmSimpleSpinBox is continuously spinning.

The widget argument is the widget identifier for the simple spin box
widget that has been affected by this callback.

The doit argument is set only when the call_data comes from the
XmNmodifyVerifyCallback. It indicates that the action that caused the
callback to be called should be performed. The action is not
performed if doit is set to False.

The position argument is the new value of the XmNposition resource as
a result of the spin.

The value argument is the new XmString value displayed in the Text
widget as a result of the spin. The application must copy this string
if it is used beyond the scope of the call_data structure.

The crossed_boundary argument is True when the spinbox cycles. This
is the case when a XmNspinBoxChildType of XmSTRING wraps from the
first item to the last or the last item to the first. In the case of
the XmNspinBoxChildType of XmNUMERIC, the boundary is crossed when
the XmSimpleSpinBox cycles from the maximum value to the minimum or
vice versa.

ERRORS/WARNINGS
The toolkit will display a warning if the application tries to set
the value of the XmNtextField resource, which is read-only (marked G
in the resource table).

SEE ALSO

XmSpinBox(3), XmCreateSimpleSpinBox(3), XmCreateSpinBox(3),
XmSimpleSpinBoxAddItem(3), XmSimpleSpinBoxDeletePos(3),
XmSimpleSpinBoxSetItem(3), Composite(3), Core(3), XmManager(3),
XmText(3), XmTextField(3), XtGetValues(3), XtSetValues(3),
XmVaCreateSimpleSpinBox(3), and XmVaCreateManagedSimpleSpinBox(3).

XmSimpleSpinBox(library call)