NAME

       XmSpinBoxValidatePosition  —  translate  the  current value of the specified XmSpinBox child into a valid
       position

SYNOPSIS

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

DESCRIPTION

       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.

RETURN 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.

EXAMPLES

       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);
       }

SEE ALSO

       XmSpinBox(3), XmCreateSpinBox(3)

                                                                                    XmSpinBoxValidatePosition(3)