1XmSpinBoxValidatePosition(library call)XmSpinBoxValidatePosition(library call)
2
3
4
6 XmSpinBoxValidatePosition — translate the current value of the speci‐
7 fied XmSpinBox child into a valid position
8
10 #include <Xm/SpinBox.h>
11 int XmSpinBoxValidatePosition(
12 Widget textfield,
13 int *position);
14
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 ... XmNminumumValue +
52 ((n - 1) * XmNincrementlValue). 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
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
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
141 XmSpinBox(3), XmCreateSpinBox(3)
142
143
144
145 XmSpinBoxValidatePosition(library call)