'\" t
...\" SpinBoxV.sgm /main/7 1996/09/08 21:02:39 rws $
.de P!
.fl
\!!1 setgray
.fl
\\&.\"
.fl
\!!0 setgray
.fl			\" force out current output buffer
\!!save /psv exch def currentpoint translate 0 0 moveto
\!!/showpage{}def
.fl			\" prolog
.sy sed -e 's/^/!/' \\$1\" bring in postscript file
\!!psv restore
.
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
.TH "XmSpinBoxValidatePosition" "library call"
.SH "NAME"
\fBXmSpinBoxValidatePosition\fP \(em translate the current value of the specified XmSpinBox child
into a valid position
.SH "SYNOPSIS"
.PP
.nf
#include <Xm/SpinBox\&.h>
\fBint \fBXmSpinBoxValidatePosition\fP\fR(
\fBWidget \fBtextfield\fR\fR,
\fBint \fB*position\fR\fR);
.fi
.SH "DESCRIPTION"
.PP
The
\fBXmSpinBoxValidatePosition\fP function
is a utility that can be used by applications wanting to
implement a policy for tracking user modifications to editable
\fBXmSpinBox\fP children of type
\fBXmNUMERIC\fP\&. The specifics of when and how the user\&'s
modifications take effect is left up to the application\&.
.IP "\fItext_field\fP" 10
The \fItext_field\fP argument specifies the
widget ID of the child of the \fBXmSpinBox\fP that is
being modified\&. The requirement on \fItext_field\fP
is that it holds the
\fBaccessTextual\fP trait (already a requirement for
children of \fBXmSpinBox\fP)\&. This way,
\fBXmSpinBox\fP can extract the string out of the
\fItext_field\fP widget (even if it is not an
\fBXmTextField\fP)\&.
.IP "\fIposition\fP" 10
The location pointed to by the position argument is assigned the result
of the translation done by \fBXmSpinBoxValidatePosition\fP\&.
\fBXmSpinBoxValidatePosition\fP first checks to make sure this is an
\fBXmNUMERIC\fP \fBXmSpinBox\fP child\&. If it is not,
\fBXSmpinBoxValidatePosition\fP sets position to the current
position and returns \fBXmCURRENT_VALUE\fP\&.
.PP
\fBXmSpinBoxValidatePosition\fP
attempts to translate the input string to a floating point number\&. If
this translation fails,
\fBXmSpinBoxValidatePosition\fP sets position to the current position and
returns \fBXmCURRENT_VALUE\fP\&.
.PP
\fBXmSpinBoxValidatePosition\fP converts the floating point number to an integer using the
\fBXmNdecimalPoints\fP resource\&. Extra decimal places are truncated\&. The resulting integer is range
checked to make sure it falls within the valid range defined by \fBXmNminimumValue\fP and
\fBXmNmaximumValue\fP inclusive\&. If the input falls outside this range,
\fBXmSpinBoxValidatePosition\fP sets position to the nearest limit and returns either
\fBXmMINIMUM_VALUE\fP or \fBXmMAXIMUM_VALUE\fP\&.
.PP
Finally, \fBXmSpinBoxValidatePosition\fP checks the integer to make sure it belongs to the series
defined by \fBXmNminimumValue \&.\&.\&. XmNminimumValue + ((n - 1) * XmNincrementValue)\fP\&. If
the integer does not belong to this series, \fBXmSpinBoxValidatePosition\fP sets position to the
nearest element which is less than or equal to the integer and returns
\fBXmINCREMENT_VALUE\fP\&.
.PP
Otherwise, \fBXmSpinBoxValidatePosition\fP assigns the integer to position and returns
\fBXmVALID_VALUE\fP\&.
.SH "RETURN VALUE"
.PP
The
\fBXmSpinBoxValidatePosition\fP function returns the status of the validation\&.
The set of possible values returned is as follows:
.IP "\fBXmCURRENT_VALUE\fP" 10
Cannot convert, returning current position_value\&.
.IP "\fBXmMINIMUM_VALUE\fP" 10
Less than min\&.
.IP "\fBXmMAXIMUM_VALUE\fP" 10
More than max\&.
.IP "\fBXmINCREMENT_VALUE\fP" 10
Not on increment\&.
.IP "\fBXmVALID_VALUE\fP" 10
Okay\&.
.SH "EXAMPLES"
.PP
This first example demonstrates how the \fBXmSpinBoxValidatePosition\fP
function could be used from inside an
\fBXmNmodifyVerifyCallback\fP callback installed on the
\fBXmSpinBox\fP or the
\fBXmSimpleSpinBox\fP:
.PP
.nf
\f(CW/*
 * Install a callback on a spin box arrow press\&.
 */
  XtAddCallback(sb, XmNmodifyVerifyCallback, ModifyVerifyCB, NULL);
  XtAddCallback(simple_sb, XmNmodifyVerifyCallback, ModifyVerifyCB, NULL);\fR
.fi
.PP
.PP
with the callback doing:
.PP
.nf
\f(CWvoid 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;
}\fR
.fi
.PP
.PP
This second example demonstrates how the \fBXmSpinBoxValidatePosition\fP
function could be used from inside an
\fBXmNactivateCallback\fP callback installed on
the \fBTextField\fP child of the \fBXmSpinBox\fP:
.PP
.nf
\f(CW/*
 * Install a callback on a spin box arrow press\&.
 */
XtAddCallback(tf, XmNactivateCallback, ModifyVerifyChildCB, NULL);\fR
.fi
.PP
.PP
with the callback doing:
.PP
.nf
\f(CWvoid 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);
}\fR
.fi
.PP
.SH "SEE ALSO"
.PP
\fBXmSpinBox\fP(3),
\fBXmCreateSpinBox\fP(3)
...\" created by instant / docbook-to-man, Sun 22 Dec 1996, 20:30