XmSpinBoxValidatePosition(library calXlm)SpinBoxValidatePosition(library call)




 NAME    [Toc]    [Back]
      XmSpinBoxValidatePosition - translate the current value of the
      specified XmSpinBox child into a valid position

 SYNOPSIS    [Toc]    [Back]
      #include <Xm/SpinBox.h>
      int XmSpinBoxValidatePosition(
      Widget textfield,
      int *position);

 DESCRIPTION    [Toc]    [Back]
      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 ... 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.



                                    - 1 -       Formatted:  January 24, 2005






 XmSpinBoxValidatePosition(library calXlm)SpinBoxValidatePosition(library call)




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

 RETURN VALUE    [Toc]    [Back]
      The XmSpinBoxValidatePosition function returns the status of the
      validation.  The set of possible values returned is as follows:

      XmCURRENT_VALUE    [Toc]    [Back]
                Cannot convert, returning current position_value.

      XmMINIMUM_VALUE    [Toc]    [Back]
                Less than min.

      XmMAXIMUM_VALUE    [Toc]    [Back]
                More than max.

      XmINCREMENT_VALUE    [Toc]    [Back]
                Not on increment.

      XmVALID_VALUE    [Toc]    [Back]
                Okay.

 EXAMPLES    [Toc]    [Back]
      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;

          ...



                                    - 2 -       Formatted:  January 24, 2005






 XmSpinBoxValidatePosition(library calXlm)SpinBoxValidatePosition(library call)




          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    [Toc]    [Back]
      XmSpinBox(3), XmCreateSpinBox(3)


                                    - 3 -       Formatted:  January 24, 2005