Text Field and Arrow Button Widget (DtSpinBox)

Use the DtSpinBox for cycling through a list of text items or incrementing and decrementing a numeric entry. DtSpinBox is a subclass of the XmManager class and is used to display a text field and two arrows.

The DtSpinBox widget is a user interface control used to increment and decrement an arbitrary text or numeric field. You can use it, for example, to cycle through the months of the year or days of the month. Figure 7-1 “Examples of the DtSpinBox widget” shows examples of the DtSpinBox widget.

Figure 7-1 Examples of the DtSpinBox widget

Library and Header Files

The DtSpinBox widget is in the libDtWidget library. The header file is Dt/SpinBox.h.

Demo Program

A demo containing an example of the DtSpinBox widget is in /usr/dt/examples/dtwidget/controls.c.

Moving to XmSimpleSpinBox

To use the Motif 2.1 DtSimpleSpinBox widget, change the Dt names for the class, types, and creation routines to Xm, and change SpinBox to SimpleSpinBox. For example, change all occurrences of DtSpinBox to XmSimpleSpinBox in your code. Alternatively, you can compile your existing code with -DDT_USE_XM_SSPINBOX. This information is supplied in case you choose to revise your CDE 1.0 application to use the Motif 2.1 widget.

Convenience Functions

Table 7-1 “DtSpinBox Convenience Functions” lists the convenience functions for the DtSpinBox widget. See the DtSpinBox(3) man page for more information.

Table 7-1 DtSpinBox Convenience Functions

`Function`	`Description`
`DtCreateSpinBox()`	Creates a SpinBox widget.
`DtSpinBoxAddItem()`	Adds an item into a DtSpinBox widget at a specified location.
`DtSpinBoxDeletePos()`	Deletes a specified item from a DtSpinBox widget.
`DtSpinBoxSetItem()`	Sets the current item in a DtSpinBox widget.

Classes

DtSpinBoxWidget inherits behavior and resources from the Core, Composite, Constraint, and XmManager classes.

The class pointer is dtSpinBoxWidgetClass.

The class name is DtSpinBoxWidget.

DtSpinBoxWidget does not support subclassing.

Resources

The DtSpinBox widget defines the following set of widget resources. Table 7-2 “DtSpinBoxWidget Resources” lists the class, type, default, and access for each resource.

DtNarrowLayout specifies the style and position of the DtSpinBox arrows.
DtNarrowSensitivity specifies the sensitivity of the arrows in the DtSpinBox.
DtNspinBoxChildType specifies the style of the DtSpinBox.
DtNdecimalPoints specifies the position of the decimal point within the integer value when the child type is numeric.
DtNincrementValue specifies the amount to increment or decrement the position when the child type is numeric.
DtNinitialDelay specifies the amount of time in milliseconds before the arrow buttons begin to spin continuously.
DtNnumValues specifies the number of items in the DtNvalues list when the child type is a string.
DtNvalues supplies the list of strings to cycle through when the child type resource is a string.
DtNmaximumValue specifies the upper bound on the DtSpinBox range when the child type is numeric.
DtNminimumValue specifies the lower bound on the DtSpinBox range when the child type is numeric.
DtNmodifyVerifyCallback is called just before the DtSpinBox position changes. The application can use this callback to implement new application-related logic, including setting a new position, spinning to, or canceling the impending action.
DtNposition has a different value based on the child type resource. When the child type is a string, DtNposition is the index into the DtNvalues list for the current item. When the child type is numeric, DtNposition is the integer value of the DtSpinBox that falls within the maximum and minimum value range.
DtNrepeatDelay is the number of milliseconds between repeated calls to the DtNvalueChangedCallback while the user is spinning the DtSpinBox.
DtNvalueChangedCallback is called whenever the value of the DtNposition resource is changed through the use of the spinner arrows.

See the DtSpinBox(3) man page for more information.

Table 7-2 DtSpinBoxWidget Resources

`Name`	`Class`	`Type`	`Default`	`Access`
`DtNarrowLayout`	`DtCArrowLayout`	`unsigned char`	`DtARROWS_END`	CSG
`DtNarrowSensitivity`	`DtCArrowSensitivity`	`unsigned char`	`DtARROWS_SENSITIVE`	CSG
`DtNspinBoxChildType`	`DtCSpinBoxChildType`	`unsigned char`	`DtSTRING`	CG
`DtNdecimalPoints`	`DtCDecimalPoints`	`short`	`0`	CSG
`DtNincrementValue`	`DtCIncrementValue`	`int`	`1`	CSG
`DtNinitialDelay`	`DtCInitialDelay`	`unsigned int`	`250 ms`	CSG
`DtNnumValues`	`DtCNumValues`	`int`	`0`	CSG
`DtNvalues`	`DtCValues`	`XmString Table`	`NULL`	CSG
`DtNmaximumValue`	`DtCMaximumValue`	`int`	`10`	CSG
`DtNminimumValue`	`DtCMinimumValue`	`int`	`0`	CSG
`DtNmodifyVerify Callback`	`DtCCallback`	`XtCallback List`	`NULL`	C
`DtNposition`	`DtCPosition`	`int`	`0`	CSG
`DtNrepeatDelay`	`DtCRepeatDelay`	`unsigned int`	`200 ms`	CSG
`DtNvalueChanged Callback`	`DtCCallback`	`XtCallback List`	`NULL`	C

Callback Structures

The callback structure follows and is described in Table 7-3 “DtSpinBox Callbacks”

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

Table 7-3 DtSpinBox Callbacks

`Callback`	`Description`
`reason`	Use this callback for three possible reasons. For the first call to the callback at the beginning of a spin, or for a single activation of the spin arrows, `DtCR_OK` is the reason. If the DtSpinBox is being continuously spun, the reason is `DtCR_SPIN_NEXT` or `DtCR_SPIN_PRIOR`, depending on the arrow that is spinning.
`event`	A pointer to the event that caused this callback to be invoked. It can be NULL when the DtSpinBox is continuously spinning.
`widget`	The widget identifier for the text widget that is affected by the spin.
`doit`	Sets this value only when the `call_data` comes from the DtNmodifyVerifyCallback. For a modifyVerify callback, the setting of this field by an application determines whether the action that initiated the callback should be performed. When this field is set to False, the action is not performed.
`position`	The new value of the DtNposition resource that results from the spin.
`value`	The new XmString value displayed in the Text widget that results from the spin. This string must be copied if it is used beyond the scope of the `call_data` structure.
`crossed_boundary`	This Boolean is True when the spinbox cycles, and/or DtNspinBoxChildType of XmSTRING wraps from the first item to the last or the last item to the first. When the DtNspinBoxChildType is XmNUMERIC, the boundary is crossed when the DtSpinBox cycles from the maximum value to the minimum value or vice versa.

Example of DtSpinBox Widget

The following example shows how to create and use a DtSpinBox widget. You can find this code as part of the controls.c demo in the /usr/dt/examples/dtwidget directory.

/*
 * Example code for SpinBox
 */
 
#include <Dt/SpinBox.h>
 
static char *spinValueStrings[] = {
 "alpha", "beta", "gamma", "delta",
 "epsilon", "zeta", "eta", "theta",
 "iota", "kappa", "lambda", "mu",
 "nu", "xi", "omicron", "pi",
 "rho", "sigma", "tau", "upsilon",
 "phi", "chi", "psi", "omega"
};
 
static void ModifyVerifyCb(Widget, XtPointer, XtPointer);
 
static void CreateSpinBoxes(Widget parent)
{
    Widget titleLabel, spinBox;
    XmString *valueXmstrings;
    int numValueStrings;
    XmString labelString;
    Arg args[20];
    int i, n;
 
    /* Create value compound strings */
 
    numValueStrings = XtNumber(spinValueStrings);
 valueXmstrings = (XmString *)XtMalloc(numValueStrings
 sizeof(XmString*));
 for (i = 0; i < numValueStrings; i++) {
  valueXmstrings[i] =
   XmStringCreateLocalized(spinValueStrings[i]);
    }
 
    /* Create title label */
 
    labelString = XmStringCreateLocalized("SpinBox Widget");
    n = 0;
    XtSetArg(args[n], XmNlabelString, labelString); n++;
    titleLabel = XmCreateLabel(parent, "title", args, n);
    XtManageChild(titleLabel);
    XmStringFree(labelString);
 
 /*
 * Create a SpinBox containing string values.
 */
 
    n = 0;
    XtSetArg(args[n], DtNvalues, valueXmstrings); n++;
    XtSetArg(args[n], DtNnumValues, numValueStrings); n++;
    XtSetArg(args[n], DtNcolumns, 10); n++;
    spinBox = DtCreateSpinBox(parent, "spinBox1", args, n);
    XtManageChild(spinBox);
 
    /*
  * Create a SpinBox containing numeric values to 3 decimal places.
  * Position the arrows on either side of the displayed value.
  */
 
    n = 0;
    XtSetArg(args[n], DtNspinBoxChildType, DtNUMERIC); n++;
    XtSetArg(args[n], DtNminimumValue, 1000); n++;
    XtSetArg(args[n], DtNmaximumValue, 100000); n++;
    XtSetArg(args[n], DtNincrementValue,1000); n++;
    XtSetArg(args[n], DtNdecimalPoints,3); n++;
    XtSetArg(args[n], DtNposition,1000); n++;
    XtSetArg(args[n], DtNarrowLayout,DtARROWS_SPLIT); n++;
    XtSetArg(args[n], DtNcolumns, 10); n++;
    spinBox = DtCreateSpinBox(parent, "spinBox2", args, n);
    XtManageChild(spinBox);
 
    /*
* Create a SpinBox containing numeric values to 2 decimal places.
* Position the arrows on the left of the displayed value.
* Disallow alternate user changes by adding a modify/verify
 callback.
    */
 
    n = 0;
    XtSetArg(args[n], DtNspinBoxChildType, DtNUMERIC); n++;
    XtSetArg(args[n], DtNminimumValue, 1500); n++;
    XtSetArg(args[n], DtNmaximumValue, 60500); n++;
    XtSetArg(args[n], DtNincrementValue,1500); n++;
    XtSetArg(args[n], DtNdecimalPoints,2); n++;
    XtSetArg(args[n], DtNposition,7500); n++
 XtSetArg(args[n], DtNarrowLayout,DtARROWS_FLAT_BEGINNING); n++;
    XtSetArg(args[n], DtNcolumns, 10); n++;
    spinBox = DtCreateSpinBox(parent, "spinBox3", args, n);
    XtManageChild(spinBox);
 
    XtAddCallback(spinBox, DtNmodifyVerifyCallback, ModifyVerifyCb,
 NULL);
 
 /*
 * Create a SpinBox containing string values.
 * Position the arrows on the left of the display value
 */
 
    n = 0;
    XtSetArg(args[n], DtNvalues, valueXmstrings); n++;
    XtSetArg(args[n], DtNnumValues, numValueStrings); n++;
    XtSetArg(args[n], DtNarrowLayout, DtARROWS_BEGINNING); n++;
    XtSetArg(args[n], DtNcolumns, 10); n++;
    spinBox = DtCreateSpinBox(parent, "spinBox4", args, n);
    XtManageChild(spinBox);
 
   /*
   * Create a SpinBox containing numeric values to 3 decimal places.
   * Position the arrows on the right of the displayed value.
   */
 
    n = 0;
    XtSetArg(args[n], DtNspinBoxChildType, DtNUMERIC); n++;
    XtSetArg(args[n], DtNminimumValue, 1000); n++;
    XtSetArg(args[n], DtNmaximumValue, 100000); n++;
    XtSetArg(args[n], DtNincrementValue,1000); n++;
    XtSetArg(args[n], DtNdecimalPoints,3); n++;
    XtSetArg(args[n], DtNposition,1000); n++;
    XtSetArg(args[n], DtNarrowLayout, DtARROWS_FLAT_END); n++;
    XtSetArg(args[n], DtNcolumns, 10); n++;
    spinBox = DtCreateSpinBox(parent, "spinBox5", args, n);
    XtManageChild(spinBox);
 
    /*
     * Free value strings, SpinBox has taken a copy.
     */
 
    for (i = 0; i < numValueStrings; i++) {
  XmStringFree(valueXmstrings[i]);
    }
    XtFree((char*)valueXmstrings);
 
}
 
 /*
 * modify/verify callback.
 *
  * Allow/disallow alternate user changes
  */
 
static void ModifyVerifyCb(Widget w, XtPointer cd, XtPointer cb)
{
    DtSpinBoxCallbackStruct *scb= (DtSpinBoxCallbackStruct*)cb;
    static Boolean allowChange = True;
 
    scb->doit = allowChange;
 
    if (allowChange == False) {
 printf("DtSpinBox: DtNmodifyVerifyCallback.
Change disallowed.\n");
 XBell(XtDisplay(w), 0);
    }
 
    allowChange = (allowChange == True) ? False: True;
}

Text Field and Arrow Button Widget (DtSpinBox)

Technical documentation

» Table of Contents

» Glossary

» Index