1cdk_template(3) Library Functions Manual cdk_template(3)
2
3
4
6 cdk_template - a curses template widget.
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10
11 #include <cdk.h>
12
13 char *activateCDKTemplate (
14 CDKTEMPLATE *template,
15 chtype * actions);
16
17 void cleanCDKTemplate (
18 CDKTEMPLATE *template);
19
20 void destroyCDKTemplate (
21 CDKTEMPLATE *template);
22
23 void drawCDKTemplate (
24 CDKTEMPLATE *template,
25 boolean box);
26
27 void eraseCDKTemplate (
28 CDKTEMPLATE *template);
29
30 boolean getCDKTemplateBox (
31 CDKTEMPLATE *template);
32
33 int getCDKTemplateMin (
34 CDKTEMPLATE *template);
35
36 char *getCDKTemplateValue (
37 CDKTEMPLATE *template);
38
39 char *injectCDKTemplate (
40 CDKTEMPLATE *template,
41 chtype input);
42
43 char *mixCDKTemplate (
44 CDKTEMPLATE *template);
45
46 void moveCDKTemplate (
47 CDKTEMPLATE *template,
48 int xpos,
49 int ypos,
50 boolean relative,
51 boolean refresh);
52
53 CDKTEMPLATE *newCDKTemplate (
54 CDKSCREEN *cdkscreen,
55 int xpos,
56 int ypos,
57 const char *title,
58 const char *label,
59 const char *plate,
60 const char *overlay,
61 boolean box,
62 boolean shadow);
63
64 void positionCDKTemplate (
65 CDKTEMPLATE *template);
66
67 void setCDKTemplate (
68 CDKTEMPLATE *template,
69 const char *value,
70 boolean box);
71
72 void setCDKTemplateBackgroundAttrib (
73 CDKTEMPLATE *template,
74 chtype attribute);
75
76 void setCDKTemplateBackgroundColor (
77 CDKTEMPLATE *template,
78 const char * color);
79
80 void setCDKTemplateBox (
81 CDKTEMPLATE *template,
82 boolean box);
83
84 void setCDKTemplateBoxAttribute (
85 CDKTEMPLATE *template,
86 chtype character);
87
88 void setCDKTemplateCB (
89 CDKTEMPLATE *template,
90 TEMPLATECB callbackFunction);
91
92 void setCDKTemplateHorizontalChar (
93 CDKTEMPLATE *template,
94 chtype character);
95
96 void setCDKTemplateLLChar (
97 CDKTEMPLATE *template,
98 chtype character);
99
100 void setCDKTemplateLRChar (
101 CDKTEMPLATE *template,
102 chtype character);
103
104 void setCDKTemplateMin (
105 CDKTEMPLATE *template,
106 int minimum);
107
108 void setCDKTemplatePostProcess (
109 CDKTEMPLATE *template,
110 PROCESSFN callback,
111 void * data);
112
113 void setCDKTemplatePreProcess (
114 CDKTEMPLATE *template,
115 PROCESSFN callback,
116 void * data);
117
118 void setCDKTemplateULChar (
119 CDKTEMPLATE *template,
120 chtype character);
121
122 void setCDKTemplateURChar (
123 CDKTEMPLATE *template,
124 chtype character);
125
126 void setCDKTemplateValue (
127 CDKTEMPLATE *template,
128 const char *value);
129
130 void setCDKTemplateVerticalChar (
131 CDKTEMPLATE *template,
132 chtype character);
133
134 char *unmixCDKTemplate (
135 CDKTEMPLATE *template,
136 const char *string);
137
139 The Cdk template widget creates a template widget which allows a user
140 to type information into an entry field with a pre-set field format.
141 Typical uses for this widget would be a date field or a time field.
142 The following are functions which create or manipulate the Cdk template
143 box widget.
144
146 activateCDKTemplate
147 activates the template widget and lets the user interact with the
148 widget.
149
150 · The parameter template is a pointer to a non-NULL template
151 widget.
152
153 · If the actions parameter is passed with a non-NULL value, the
154 characters in the array will be injected into the widget.
155
156 To activate the widget interactively pass in a NULL pointer
157 for actions.
158
159 If the character entered into this widget is RETURN or TAB then
160 this function will return a char * representing the information
161 typed into the widget and the widget data exitType will be set to
162 vNORMAL.
163
164 If the character entered was ESCAPE then the function will return
165 NULL pointer and the widget data exitType is set to vESCAPE_HIT.
166
167 cleanCDKTemplate
168 clears the information from the field.
169
170 destroyCDKTemplate
171 removes the widget from the screen and frees any memory the object
172 used.
173
174 drawCDKTemplate
175 draws the template widget on the screen. If box is true, the wid‐
176 get is drawn with a box.
177
178 eraseCDKTemplate
179 removes the widget from the screen. This does NOT destroy the
180 widget.
181
182 getCDKTemplateBox
183 returns true if the widget will be drawn with a box around it.
184
185 getCDKTemplateMin
186 returns the minimum characters that must be entered before the
187 widget will exit.
188
189 getCDKTemplateValue
190 returns the current value of the widget.
191
192 injectCDKTemplate
193 injects a single character into the widget.
194
195 · The parameter template is a pointer to a non-NULL template
196 widget.
197
198 · The parameter character is the character to inject into the
199 widget.
200
201 The return value and side-effect (setting the widget data exit‐
202 Type) depend upon the injected character:
203
204 RETURN or TAB
205 the function returns a char * representing the information
206 typed into the widget. The widget data exitType is set to
207 vNORMAL.
208
209 ESCAPE the function returns a NULL pointer. The widget data exit‐
210 Type is set to vESCAPE_HIT.
211
212 Otherwise
213 unless modified by preprocessing, postprocessing or key
214 bindings, the function returns a NULL pointer. The widget
215 data exitType is set to vEARLY_EXIT.
216
217 mixCDKTemplate
218 returns a char* pointer to the field value and the plate.
219
220 moveCDKTemplate
221 moves the given widget to the given position.
222
223 · The parameters xpos and ypos are the new position of the wid‐
224 get.
225
226 The parameter xpos is an integer or one of the predefined val‐
227 ues TOP, BOTTOM, and CENTER.
228
229 The parameter ypos may be an integer or one of the pre-defined
230 values LEFT, RIGHT, and CENTER.
231
232 · The parameter relative states whether the xpos/ypos pair is a
233 relative move or an absolute move.
234
235 For example, if xpos = 1 and ypos = 2 and relative = TRUE,
236 then the widget would move one row down and two columns right.
237 If the value of relative was FALSE, then the widget would move
238 to the position (1,2).
239
240 Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
241 relative = TRUE (weird things may happen).
242
243 · The final parameter refresh is a boolean value which states
244 whether the widget will be repainted after the move.
245
246 newCDKTemplate
247 creates a template widget, returning a pointer to it. Parameters:
248
249 screen
250 is the screen you wish this widget to be placed in.
251
252 xpos controls the placement of the object along the horizontal
253 axis. It may be an integer or one of the pre-defined values
254 LEFT, RIGHT, and CENTER.
255
256 ypos controls the placement of the object along the vertical axis.
257 It may be an integer or one of the pre-defined values TOP,
258 BOTTOM, and CENTER.
259
260 title
261 is the string to display at the top of the widget. The title
262 can be more than one line; just provide a carriage return
263 character at the line break.
264
265 label
266 is the string to display in the label of the template field.
267
268 plate
269 defines the character to allow at each position in the tem‐
270 plate field. This is done by creating a character plate by
271 using special format character to tell the template widget
272 what type of character is allowed where in the template wid‐
273 get. The following table lists the format types.
274
275 Plate_Character Effect
276 ──────────────────────────────────────────────────────
277 # Accepts an integer.
278 A Accepts an alphabetic value.
279 C Accepts an alphabetic value. Auto‐
280 matically converts the character to
281 upper case.
282 c Accepts an alphabetic value. Auto‐
283 matically converts the character to
284 lower case.
285 M Accepts alphanumeric characters.
286 X Accepts alphanumeric characters.
287 Automatically converts the charac‐
288 ter to upper case.
289 x Accepts alphanumeric characters.
290 Automatically converts the charac‐
291 ter to upper case.
292 Anything else Ignored and assumed a non-editable
293 position.
294 ──────────────────────────────────────────────────────
295
296 overlay
297 is the overlay of the template field. If the field needs
298 some sort of overlay, this parameter supplies this. A date
299 field could have YY/MM/DD, the overlay parameter would dis‐
300 play YY/MM/DD on an empty template field.
301
302 box is true if the widget should be drawn with a box around it.
303
304 shadow
305 turns the shadow on or off around this widget.
306
307 If the widget could not be created then a NULL pointer is
308 returned.
309
310 positionCDKTemplate
311 allows the user to move the widget around the screen via the sin‐
312 gle keystroke commands. See cdk_position (3) for key bindings.
313
314 setCDKTemplate
315 lets the programmer modify certain elements of an existing tem‐
316 plate widget.
317
318 The parameter names correspond to the same parameter names listed
319 in the newCDKTemplate function.
320
321 setCDKTemplateBackgroundAttrib
322 sets the background attribute of the widget.
323
324 The parameter attribute is a curses attribute, e.g., A_BOLD.
325
326 setCDKTemplateBackgroundColor
327 sets the background color of the widget.
328
329 The parameter color is in the format of the Cdk format strings.
330
331 For more information, see the cdk_display [4m(3).
332
333 setCDKTemplateBox
334 sets a flag, true if the widget will be drawn with a box around
335 it.
336
337 setCDKTemplateBoxAttribute
338 sets the attribute of the box.
339
340 setCDKTemplateCB
341 allows the programmer to set a different widget input handler.
342
343 The parameter callbackFunction is of type TEMPLATECB.
344
345 The default input handler is CDKTemplateCallBack.
346
347 setCDKTemplateHorizontalChar
348 sets the horizontal drawing character for the box to the given
349 character.
350
351 setCDKTemplateLLChar
352 sets the lower left hand corner of the widget's box to the given
353 character.
354
355 setCDKTemplateLRChar
356 sets the lower right hand corner of the widget's box to the given
357 character.
358
359 setCDKTemplateMin
360 sets the minimum number of characters that must be entered before
361 the widget will exit.
362
363 setCDKTemplatePostProcess
364 allows the user to have the widget call a function after the key
365 has been applied to the widget. To learn more about post-process‐
366 ing see cdk_process (3).
367
368 setCDKTemplatePreProcess
369 allows the user to have the widget call a function after a key is
370 hit and before the key is applied to the widget. To learn more
371 about preprocessing see cdk_process (3).
372
373 setCDKTemplateULChar
374 sets the upper left hand corner of the widget's box to the given
375 character.
376
377 setCDKTemplateURChar
378 sets the upper right hand corner of the widget's box to the given
379 character.
380
381 setCDKTemplateValue
382 sets a value in the widget.
383
384 setCDKTemplateVerticalChar
385 sets the vertical drawing character for the box to the given char‐
386 acter.
387
388 unmixCDKTemplate
389 returns a char* pointer to the field value without any plate char‐
390 acters.
391
393 When the widget is activated there are several default key bindings
394 which will help the user enter or manipulate the information quickly.
395 The following table outlines the keys and their actions for this wid‐
396 get.
397
398 ┌────────────────┬─────────────────────────────────────┐
399 │Key │ Action │
400 ├────────────────┼─────────────────────────────────────┤
401 ├────────────────┼─────────────────────────────────────┤
402 │Delete │ Deletes the character at the cur‐ │
403 │ │ sor. │
404 ├────────────────┼─────────────────────────────────────┤
405 │Backspace │ Deletes the character before cur‐ │
406 │ │ sor, moves cursor left. │
407 ├────────────────┼─────────────────────────────────────┤
408 │Ctrl-P │ Pastes whatever is in the paste │
409 │ │ buffer, into the widget. │
410 ├────────────────┼─────────────────────────────────────┤
411 │Ctrl-K │ Cuts the contents from the widget │
412 │ │ and saves a copy in the paste buf‐ │
413 │ │ fer. │
414 ├────────────────┼─────────────────────────────────────┤
415 │Ctrl-T │ Copies the contents of the widget │
416 │ │ into the paste buffer. │
417 ├────────────────┼─────────────────────────────────────┤
418 │Ctrl-E │ Erases the contents of the widget. │
419 ├────────────────┼─────────────────────────────────────┤
420 │Return │ Exits the widget and returns a │
421 │ │ char* representing the information │
422 │ │ which was typed into the field. It │
423 │ │ also sets the widget data exitType │
424 │ │ to vNORMAL. │
425 ├────────────────┼─────────────────────────────────────┤
426 │Tab │ Exits the widget and returns a │
427 │ │ char* representing the information │
428 │ │ which was typed into the field. It │
429 │ │ also sets the widget data exitType │
430 │ │ to vNORMAL. │
431 ├────────────────┼─────────────────────────────────────┤
432 │Escape │ Exits the widget and returns a NULL │
433 │ │ pointer. It also sets the widget │
434 │ │ data exitType to vESCAPE_HIT. │
435 ├────────────────┼─────────────────────────────────────┤
436 │Ctrl-L │ Refreshes the screen. │
437 └────────────────┴─────────────────────────────────────┘
439 cdk(3), cdk_binding(3), cdk_display(3), cdk_screen(3)
440
441
442
443 cdk_template(3)