XmSpinBoxValidatePosition(3)

1XmSpinBoxValidatePosition(library call)XmSpinBoxValidatePosition(library call)
2
3
4

NAME

6       XmSpinBoxValidatePosition  —  translate the current value of the speci‐
7       fied XmSpinBox child into a valid position
8

SYNOPSIS

10       #include <Xm/SpinBox.h>
11       int XmSpinBoxValidatePosition(
12       Widget textfield,
13       int *position);
14

DESCRIPTION

16       The XmSpinBoxValidatePosition function is a utility that can be used by
17       applications  wanting to implement a policy for tracking user modifica‐
18       tions to editable XmSpinBox children of type XmNUMERIC.  The  specifics
19       of  when and how the user's modifications take effect is left up to the
20       application.
21
22       text_field
23                 The text_field argument specifies the widget ID of the  child
24                 of  the  XmSpinBox that is being modified. The requirement on
25                 text_field is that it holds the accessTextual trait  (already
26                 a requirement for children of XmSpinBox). This way, XmSpinBox
27                 can extract the string out of the text_field widget (even  if
28                 it is not an XmTextField).
29
30       position  The  location pointed to by the position argument is assigned
31                 the result of the translation done by  XmSpinBoxValidatePosi‐
32                 tion.   XmSpinBoxValidatePosition  first  checks to make sure
33                 this is an XmNUMERIC XmSpinBox child. If it is  not,  XSmpin‐
34                 BoxValidatePosition sets position to the current position and
35                 returns XmCURRENT_VALUE.
36
37       XmSpinBoxValidatePosition attempts to translate the input string  to  a
38       floating  point number. If this translation fails, XmSpinBoxValidatePo‐
39       sition sets  position  to  the  current  position  and  returns  XmCUR‐
40       RENT_VALUE.
41
42       XmSpinBoxValidatePosition  converts  the  floating  point  number to an
43       integer using the XmNdecimalPoints resource. Extra decimal  places  are
44       truncated. The resulting integer is range checked to make sure it falls
45       within the valid range defined by XmNminimumValue  and  XmNmaximumValue
46       inclusive.  If the input falls outside this range, XmSpinBoxValidatePo‐
47       sition sets position to the nearest limit and  returns  either  XmMINI‐
48       MUM_VALUE or XmMAXIMUM_VALUE.
49
50       Finally,  XmSpinBoxValidatePosition  checks the integer to make sure it
51       belongs to the series defined by XmNminimumValue ... XmNminimumValue  +
52       ((n  -  1) * XmNincrementValue). If the integer does not belong to this
53       series, XmSpinBoxValidatePosition sets position to the nearest  element
54       which  is  less  than  or  equal  to  the  integer and returns XmINCRE‐
55       MENT_VALUE.
56
57       Otherwise, XmSpinBoxValidatePosition assigns the  integer  to  position
58       and returns XmVALID_VALUE.
59

RETURN VALUE

61       The  XmSpinBoxValidatePosition function returns the status of the vali‐
62       dation.  The set of possible values returned is as follows:
63
64       XmCURRENT_VALUE
65                 Cannot convert, returning current position_value.
66
67       XmMINIMUM_VALUE
68                 Less than min.
69
70       XmMAXIMUM_VALUE
71                 More than max.
72
73       XmINCREMENT_VALUE
74                 Not on increment.
75
76       XmVALID_VALUE
77                 Okay.
78

EXAMPLES

80       This first example demonstrates how the XmSpinBoxValidatePosition func‐
81       tion  could  be  used  from  inside an XmNmodifyVerifyCallback callback
82       installed on the XmSpinBox or the XmSimpleSpinBox:
83
84       /*
85        * Install a callback on a spin box arrow press.
86        */
87         XtAddCallback(sb, XmNmodifyVerifyCallback, ModifyVerifyCB, NULL);
88         XtAddCallback(simple_sb, XmNmodifyVerifyCallback, ModifyVerifyCB, NULL);
89
90       with the callback doing:
91
92       void ModifyVerifyCB(widget, call_data, client_data) {
93           XmSpinBoxCallbackStruct *cbs = (XmSpinBoxCallbackStruct*) call_data;
94           int position;
95           Widget textual = NULL;
96           if (XtIsSubclass(w, xmSimpleSpinBoxWidgetClass))
97           {
98               Arg args[1];
99               XtSetArg(args[0], XmNtextField, &textual);
100               XtGetValues(w, args, 1);
101           }
102           else if (XtIsSubclass(w, xmSpinBoxWidgetClass))
103             textual = cbs->widget;
104           else
105             textual = (Widget) NULL;
106
107           ...
108
109           if (XmSpinBoxValidatePosition(textual, &position) == XmCURRENT_VALUE)
110             XBell(XtDisplay(w), 0);
111           else
112             cbs->position = position;
113       }
114
115       This second  example  demonstrates  how  the  XmSpinBoxValidatePosition
116       function  could  be  used  from  inside an XmNactivateCallback callback
117       installed on the TextField child of the XmSpinBox:
118
119       /*
120        * Install a callback on a spin box arrow press.
121        */
122       XtAddCallback(tf, XmNactivateCallback, ModifyVerifyChildCB, NULL);
123
124       with the callback doing:
125
126       void ModifyVerifyChildCB(widget, call_data, client_data) {
127           int     position;
128           Widget  textual = widget;
129           Arg     args[1];
130
131           if (XmSpinBoxValidatePosition (textual, &position) == XmCURRENT_VALUE)
132             XBell(XtDisplay(widget), 0);
133
134           /* Set the position constraint resource of the textfield */
135
136           XtSetArg(args[0], XmNposition, position);
137           XtSetValues(textual, args, 1);
138       }
139

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

EXAMPLES

SEE ALSO