XmSpinBoxValidatePosition(UNIX SysteXmSpinBoxValidatePosition(3X)



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

     VERSION
          This page documents Motif 2.1.

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

          XmSpinBoxValidatePositionattempts 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



     Page 1                                          (printed 1/22/99)

     XmSpinBoxValidatePosition(UNIX SysteXmSpinBoxValidatePosition(3X)



          make sure it belongs to the series defined by
          XmNminimumValue ... XmNminumumValue + ((n - 1) *
          XmNincrementlValue). 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
          XmSpinBoxValidatePositionfunction 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);



     Page 2                                          (printed 1/22/99)

     XmSpinBoxValidatePosition(UNIX SysteXmSpinBoxValidatePosition(3X)



                  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
          XmSpinBoxValidatePositionfunction 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)












     Page 3                                          (printed 1/22/99)