1cdk_template(3) Library Functions Manual cdk_template(3)
2
6 cdk_template - a curses template widget.
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 char *activateCDKTemplate (
14 CDKTEMPLATE *template,
15 chtype * actions);
16 void cleanCDKTemplate (
18 CDKTEMPLATE *template);
19 void destroyCDKTemplate (
21 CDKTEMPLATE *template);
22 void drawCDKTemplate (
24 CDKTEMPLATE *template,
25 boolean box);
26 void eraseCDKTemplate (
28 CDKTEMPLATE *template);
29 boolean getCDKTemplateBox (
31 CDKTEMPLATE *template);
32 int getCDKTemplateMin (
34 CDKTEMPLATE *template);
35 char *getCDKTemplateValue (
37 CDKTEMPLATE *template);
38 char *injectCDKTemplate (
40 CDKTEMPLATE *template,
41 chtype input);
42 char *mixCDKTemplate (
44 CDKTEMPLATE *template);
45 void moveCDKTemplate (
47 CDKTEMPLATE *template,
48 int xpos,
49 int ypos,
50 boolean relative,
51 boolean refresh);
52 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 void positionCDKTemplate (
65 CDKTEMPLATE *template);
66 void setCDKTemplate (
68 CDKTEMPLATE *template,
69 const char *value,
70 boolean box);
71 void setCDKTemplateBackgroundAttrib (
73 CDKTEMPLATE *template,
74 chtype attribute);
75 void setCDKTemplateBackgroundColor (
77 CDKTEMPLATE *template,
78 const char * color);
79 void setCDKTemplateBox (
81 CDKTEMPLATE *template,
82 boolean box);
83 void setCDKTemplateBoxAttribute (
85 CDKTEMPLATE *template,
86 chtype character);
87 void setCDKTemplateCB (
89 CDKTEMPLATE *template,
90 TEMPLATECB callbackFunction);
91 void setCDKTemplateHorizontalChar (
93 CDKTEMPLATE *template,
94 chtype character);
95 void setCDKTemplateLLChar (
97 CDKTEMPLATE *template,
98 chtype character);
99 void setCDKTemplateLRChar (
101 CDKTEMPLATE *template,
102 chtype character);
103 void setCDKTemplateMin (
105 CDKTEMPLATE *template,
106 int minimum);
107 void setCDKTemplatePostProcess (
109 CDKTEMPLATE *template,
110 PROCESSFN callback,
111 void * data);
112 void setCDKTemplatePreProcess (
114 CDKTEMPLATE *template,
115 PROCESSFN callback,
116 void * data);
117 void setCDKTemplateULChar (
119 CDKTEMPLATE *template,
120 chtype character);
121 void setCDKTemplateURChar (
123 CDKTEMPLATE *template,
124 chtype character);
125 void setCDKTemplateValue (
127 CDKTEMPLATE *template,
128 const char *value);
129 void setCDKTemplateVerticalChar (
131 CDKTEMPLATE *template,
132 chtype character);
133 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 · The parameter template is a pointer to a non-NULL template
151 widget.
152 · If the actions parameter is passed with a non-NULL value, the
154 characters in the array will be injected into the widget.
155 To activate the widget interactively pass in a NULL pointer
157 for actions.
158 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 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 cleanCDKTemplate
168 clears the information from the field.
169 destroyCDKTemplate
171 removes the widget from the screen and frees any memory the object
172 used.
173 drawCDKTemplate
175 draws the template widget on the screen. If box is true, the wid‐
176 get is drawn with a box.
177 eraseCDKTemplate
179 removes the widget from the screen. This does NOT destroy the
180 widget.
181 getCDKTemplateBox
183 returns true if the widget will be drawn with a box around it.
184 getCDKTemplateMin
186 returns the minimum characters that must be entered before the
187 widget will exit.
188 getCDKTemplateValue
190 returns the current value of the widget.
191 injectCDKTemplate
193 injects a single character into the widget.
194 · The parameter template is a pointer to a non-NULL template
196 widget.
197 · The parameter character is the character to inject into the
199 widget.
200 The return value and side-effect (setting the widget data exit‐
202 Type) depend upon the injected character:
203 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 ESCAPE the function returns a NULL pointer. The widget data exit‐
210 Type is set to vESCAPE_HIT.
211 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 mixCDKTemplate
218 returns a char* pointer to the field value and the plate.
219 moveCDKTemplate
221 moves the given widget to the given position.
222 · The parameters xpos and ypos are the new position of the wid‐
224 get.
225 The parameter xpos is an integer or one of the predefined val‐
227 ues TOP, BOTTOM, and CENTER.
228 The parameter ypos may be an integer or one of the pre-defined
230 values LEFT, RIGHT, and CENTER.
231 · The parameter relative states whether the xpos/ypos pair is a
233 relative move or an absolute move.
234 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 Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
241 relative = TRUE (weird things may happen).
242 · The final parameter refresh is a boolean value which states
244 whether the widget will be repainted after the move.
245 newCDKTemplate
247 creates a template widget, returning a pointer to it. Parameters:
248 screen
250 is the screen you wish this widget to be placed in.
251 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 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 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 label
266 is the string to display in the label of the template field.
267 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 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 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 box is true if the widget should be drawn with a box around it.
303 shadow
305 turns the shadow on or off around this widget.
306 If the widget could not be created then a NULL pointer is
308 returned.
309 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 setCDKTemplate
315 lets the programmer modify certain elements of an existing tem‐
316 plate widget.
317 The parameter names correspond to the same parameter names listed
319 in the newCDKTemplate function.
320 setCDKTemplateBackgroundAttrib
322 sets the background attribute of the widget.
323 The parameter attribute is a curses attribute, e.g., A_BOLD.
325 setCDKTemplateBackgroundColor
327 sets the background color of the widget.
328 The parameter color is in the format of the Cdk format strings.
330 For more information, see the cdk_display [4m(3).
332 setCDKTemplateBox
334 sets a flag, true if the widget will be drawn with a box around
335 it.
336 setCDKTemplateBoxAttribute
338 sets the attribute of the box.
339 setCDKTemplateCB
341 allows the programmer to set a different widget input handler.
342 The parameter callbackFunction is of type TEMPLATECB.
344 The default input handler is CDKTemplateCallBack.
346 setCDKTemplateHorizontalChar
348 sets the horizontal drawing character for the box to the given
349 character.
350 setCDKTemplateLLChar
352 sets the lower left hand corner of the widget's box to the given
353 character.
354 setCDKTemplateLRChar
356 sets the lower right hand corner of the widget's box to the given
357 character.
358 setCDKTemplateMin
360 sets the minimum number of characters that must be entered before
361 the widget will exit.
362 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 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 setCDKTemplateULChar
374 sets the upper left hand corner of the widget's box to the given
375 character.
376 setCDKTemplateURChar
378 sets the upper right hand corner of the widget's box to the given
379 character.
380 setCDKTemplateValue
382 sets a value in the widget.
383 setCDKTemplateVerticalChar
385 sets the vertical drawing character for the box to the given char‐
386 acter.
387 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 ┌────────────────┬─────────────────────────────────────┐
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 cdk_template(3)