XmSpinBoxValidatePosition - Man Page

#include <Xm/SpinBox​.h>
int XmSpinBoxValidatePosition(
Widget textfield,
int *position);

The XmSpinBoxValidatePosition function is a utility that can be used by applications wanting to implement a policy for tracking user modifications to editable XmSpinBox children of type XmNUMERIC​. The specifics of when and how the user​'s modifications take effect is left up to the application​.

text_field

The text_field argument specifies the widget ID of the child of the XmSpinBox that is being modified​. The requirement on text_field is that it holds the accessTextual trait (already a requirement for children of XmSpinBox)​. This way, XmSpinBox can extract the string out of the text_field widget (even if it is not an XmTextField)​.

position

The location pointed to by the position argument is assigned the result of the translation done by XmSpinBoxValidatePosition​. XmSpinBoxValidatePosition first checks to make sure this is an XmNUMERIC XmSpinBox child​. If it is not, XSmpinBoxValidatePosition sets position to the current position and returns XmCURRENT_VALUE​.

XmSpinBoxValidatePosition attempts to translate the input string to a floating point number​. If this translation fails, XmSpinBoxValidatePosition sets position to the current position and returns XmCURRENT_VALUE​.

XmSpinBoxValidatePosition converts the floating point number to an integer using the XmNdecimalPoints resource​. Extra decimal places are truncated​. The resulting integer is range checked to make sure it falls within the valid range defined by XmNminimumValue and XmNmaximumValue inclusive​. If the input falls outside this range, XmSpinBoxValidatePosition sets position to the nearest limit and returns either XmMINIMUM_VALUE or XmMAXIMUM_VALUE​.

Finally, XmSpinBoxValidatePosition checks the integer to make sure it belongs to the series defined by XmNminimumValue ​.​.​. XmNminimumValue + ((n - 1) * XmNincrementValue)​. If the integer does not belong to this series, XmSpinBoxValidatePosition sets position to the nearest element which is less than or equal to the integer and returns XmINCREMENT_VALUE​.

Otherwise, XmSpinBoxValidatePosition assigns the integer to position and returns XmVALID_VALUE​.

The XmSpinBoxValidatePosition function returns the status of the validation​. The set of possible values returned is as follows:

XmCURRENT_VALUE

Cannot convert, returning current position_value​.

XmMINIMUM_VALUE

Less than min​.

XmMAXIMUM_VALUE

More than max​.

XmINCREMENT_VALUE

Not on increment​.

XmVALID_VALUE

Okay​.

This first example demonstrates how the XmSpinBoxValidatePosition function could be used from inside an XmNmodifyVerifyCallback callback installed on the XmSpinBox or the XmSimpleSpinBox:

/*
 * Install a callback on a spin box arrow press​.
 */
  XtAddCallback(sb, XmNmodifyVerifyCallback, ModifyVerifyCB, NULL);
  XtAddCallback(simple_sb, XmNmodifyVerifyCallback, ModifyVerifyCB, NULL);

with the callback doing:

void ModifyVerifyCB(widget, call_data, client_data) {
    XmSpinBoxCallbackStruct *cbs = (XmSpinBoxCallbackStruct*) call_data;
    int position;
    Widget textual = NULL;
    if (XtIsSubclass(w, xmSimpleSpinBoxWidgetClass))
    {
        Arg args[1];
        XtSetArg(args[0], XmNtextField, &textual);
        XtGetValues(w, args, 1);
    }
    else if (XtIsSubclass(w, xmSpinBoxWidgetClass))
      textual = cbs->widget;
    else
      textual = (Widget) NULL;

    ​.​.​.

    if (XmSpinBoxValidatePosition(textual, &position) == XmCURRENT_VALUE)
      XBell(XtDisplay(w), 0);
    else
      cbs->position = position;
}

This second example demonstrates how the XmSpinBoxValidatePosition function could be used from inside an XmNactivateCallback callback installed on the TextField child of the XmSpinBox:

/*
 * Install a callback on a spin box arrow press​.
 */
XtAddCallback(tf, XmNactivateCallback, ModifyVerifyChildCB, NULL);

with the callback doing:

void ModifyVerifyChildCB(widget, call_data, client_data) {
    int     position;
    Widget  textual = widget;
    Arg     args[1];

    if (XmSpinBoxValidatePosition (textual, &position) == XmCURRENT_VALUE)
      XBell(XtDisplay(widget), 0);

    /* Set the position constraint resource of the textfield */

    XtSetArg(args[0], XmNposition, position);
    XtSetValues(textual, args, 1);
}

XmSpinBox(3), XmCreateSpinBox(3)