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)