'\" 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" 3
.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