XmpSpinbox Widget

Name

XmpSpinbox widget class -- an extenisble data selection widget
Version 1.5, last updated 28 February 1997

Author

Charles S. Kerr (cskerr@geocities.com)

Source Code

spinbox1.5.tar.gz
(To download from Netscape, use the right mouse button to ``Save Link As...''.
You can also get spinbox1.5.tar.gz

Licensing

The XmpSpinbox widget is available at no charge. For more information, read the license.

Synopsis

Public Header: Spinbox.h
Class Name: XmpSpinbox
Class Hierarchy: core -> composite -> constraint -> XmManager -> XmpGeometry -> XmpSpinbox
Class Pointer: xmpSpinboxWidgetClass
Instantiation: widget = XtCreateWidget ( name, xmpSpinboxWidgetClass, ... )
Functions/Macros: XmpCreateSpinbox(), XmpSpinboxGetValue(), XmpSpinboxSetValue(), XmpSpinboxGetReal(), XmpSpinboxSetReal()

Description

A spinbox consists of two arrowbuttons and one textfield which are arranged in a number of different layouts as specified by XmNspinboxStyle. The textfield shows data specified by XmNvalue. The arrowbuttons can be used to scroll through the different values. The values can be represented in the textfield in a number of built-in formats as specified by XmNspinboxType: numbers, a 24-Hour clock, dollars, and text strings. The programmer can easily add custom formats as the need arises without hacking the widget. Actions are provided to allow increment/decrement while the textfield has focus.

New Resources

Spinbox defines the following resources:

Name	Class	Type	Default	Access
XmNarrowOrientation	XmCArrowOrientation	char	XmVERTICAL	CSG
XmNcolumns	XmCColumns	short	8	CSG
XmNspinboxCycle	XmCSpinboxCycle	Boolean	False	CSG
XmNspinboxStyle	XmCSpinboxStyle	char	XmSPINBOX_STACKED_RIGHT	CSG
XmNspinboxType	XmCSpinboxType	char	XmSPINBOX_NUMBER	CSG
XmNincrement	XmCIncrement	long	1	CSG
XmNincrementLarge	XmCIncrementLarge	long	dynamic	CSG
XmNmaximum	XmCMaximum	long	dynamic	CSG
XmNminimum	XmCMinimum	long	dynamic	CSG
XmNupdateText	XmCupdateText	Boolean	False	CSG
XmNuseClosestValue	XmCuseClosestValue	Boolean	False	CSG
XmNvalue	XmCValue	long	0	CSG

In addition, there are new resources that are specific to XmNspinboxType of

• XmSPINBOX_NUMBER,
• XmSPINBOX_STRINGS, and
• XmSPINBOX_USER_DEFINED,

XmNarrowOrientation

Determines whether the arrowbuttons will point vertically or horizontally. Possible values:

XmVERTICAL
XmHORIZONTAL

XmNcolumns

The number of character spaces that should fit horizontally in the textfield. The default is 8.

XmNincrement

This specifies the increment by which the spinbox will update when the arrowbuttons are pressed or when the user uses the IncrementSmall() or DecrementSmall() actions. For example, if XmNvalue is 5 and the XmNincrement is 2, pressing the ``up'' arrowbutton will change XmNvalue to 7 and the ``down'' arrowbutton will change it to 3. The default increment is 1.

XmNincrementLarge

The value to increment or decrement the spinbox when user uses the IncrementLarge() or DecrementLarge() actions. The default value for XmNincrementLarge is as follows:

XmNspinboxType	XmNincrementLarge
XmSPINBOX_CLOCK_HM	60
XmSPINBOX_CLOCK_HMS	60
XmSPINBOX_DOLLARS	100
XmSPINBOX_NUMBER (XmNdecimalPoints>0)	10 ^ XmNdecimalPoints
XmSPINBOX_NUMBER (XmNdecimalPoints==0)	(XmNmaximum-XmNminimum)/10
XmSPINBOX_STRINGS	(XmNmaximum-XmNminimum)/10
XmSPINBOX_USER_DEFINED	N/A

XmNminimum

XmNmaximum

The maximum/minimum value of the Spinbox. The default value is dependent upon the XmNspinboxType that has been set. The default values are as follows:

XmNspinboxType	Minimum	Maximum
XmSPINBOX_CLOCK_HM	0	(60*24)-1
XmSPINBOX_CLOCK_HMS	0	(60*60*24)-1
XmSPINBOX_DOLLARS	LONG_MIN+1	LONG_MAX-1
XmSPINBOX_NUMBER	LONG_MIN+1	LONG_MAX-1
XmSPINBOX_STRINGS	0	XmNitemCount-1
XmSPINBOX_USER_DEFINED	N/A	N/A

Every time XmNspinboxType is set, if XmNmaximum and XmNminimum are not explicitly set too, they are automatically set to the appropriate default. As a result, changing XmNspinboxType during runtime can cause the current value to suddenly be less than XmNminimum or greater than XmNmaximum. Because of this, it's a good idea to check the current value when changing the XmNspinboxType on the fly.

XmNspinboxCycle

If this is False (default), the value set by XmNmaximum will be the highest that the user can select, and XmNminimum will be the lowest that the user can select. However, if XmNspinboxCycle is True, then when the user scrolls above XmNmaximum, the spinbox will cycle down to XmNminimum. Similarly, going below XmNminimum will cycle the spinbox up to XmNmaximum.

XmNspinboxType

This defines the type of the spinbox. There are a handful of predefined types -- representations of numbers, a 24-hour clock, dollars, and strings. In addition, there is a well-defined method for the programmer to define his own types. Possible values:

XmSPINBOX_CLOCK_HM	/* Clock with Hours, Minutes */
XmSPINBOX_CLOCK_HMS	/* Clock with Hours, Minutes, and Seconds */
XmSPINBOX_DOLLARS
XmSPINBOX_NUMBER
XmSPINBOX_STRINGS
XmSPINBOX_USER_DEFINED

Since XmSPINBOX_USER_DEFINED allows the user more control over the spinbox, the XmNmaximum, XmNminimum, XmNincrementLarge, XmNgetValueProc, and XmNshowValueProc should be set explicitly when setting XmNspinboxType to XmSPINBOX_USER_DEFINED.

XmNspinboxStyle

Spinbox style defines the positioning of the arrowbuttons with respect to the textfield. Possible values are:

XmNspinboxStyle	Layout
XmSPINBOX_STACKED	stack { up, tf, down}
XmSPINBOX_STACKED_LEFT	stack { up, down }, tf
XmSPINBOX_STACKED_RIGHT	tf, stack { up, down }
XmSPINBOX_LEFT	down, up, tf
XmSPINBOX_RIGHT	tf, down, up
XmSPINBOX_SEPARATE	down, tf, up

XmNupdateText

This determines the conditions for calling the function specified by XmNgetValueProc. Setting it to True will call that function every time the user changes anything, similar to the Motif value changed callback; setting it to False (default) will call that function only when the user activates the textfield or when the textfield loses focus. This allows the user to type anything and then send it to XmNgetValueProc for approval, resulting in a friendlier interface and less overhead from calling XmNgetValueProc. This is similar to the way that XmtInputField handles user input.

XmNuseClosestValue

When this is false (default), text entries that are less than XmNminimum or greater than XmNmaximum will be ignored. When it is true, XmNvalue will be set to XmNminimum or XmNmaximum, respectively. Some people reported that their users were confused that the spinbox would accept some text entry numbers but not others, so this helps give the customers a little feedback about what's happening.

XmNvalue

This, the current value in the spinbox, must be between the values of XmNminimum and XmNmaximum.

Widget Hierarchy

When a spinbox is created with a specified name, the textfield child is named tf, the up arrowbutton is named up_ab, and the down arrowbutton is named down_ab.

The superclass of XmpSpinbox, XmpGeometry, is a free widget written by Alastair Gourlay. Mr. Gourlay has written an article in the X Resource issue #10 (ISBN 1-56592-067-8) about the XmpGeometry widget. The X Resource Archive at ftp.uu.net contains the original source code for the XmpGeometry widget ; however, since it is included with this widget it is not necessary unless you want to learn more about the XmpGeometry widget.

Callback Resources

Callback	Reason Constant
XmNvalueChangedCallback	XmCR_VALUE_CHANGED

Callback Structure

Each callback function is passed the following structure:

typedef struct
{
   int reason;
   const char *str;
   size_t str_len;
   int value;
}
XmpSpinboxCallbackStruct;

Translations / Action Routines

Spinbox defines the following action routines:

Action	Event	Description
DecrementLarge()	osfPageDown	Decrements the Spinbox by XmNincrementLarge.
DecrementSmall()	osfDown	Decrements the Spinbox by XmNincrement.
IncrementLarge()	osfPageUp	Increments the Spinbox by XmNincrementLarge.
IncrementSmall()	osfUp	Increments the Spinbox by XmNincrement.