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)