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)