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. The parameter template is a pointer to a non-NULL tem‐
149 plate widget. If the actions parameter is passed with a non-NULL
150 value, the characters in the array will be injected into the wid‐
151 get. To activate the widget interactively pass in a NULL pointer
152 for actions. If the character entered into this widget is RETURN
153 or TAB then this function will return a char * representing the
154 information typed into the widget and the widget data exitType
155 will be set to vNORMAL. If the character entered was ESCAPE then
156 the function will return NULL pointer and the widget data exitType
157 is set to vESCAPE_HIT.
158 cleanCDKTemplate
160 clears the information from the field.
161 destroyCDKTemplate
163 removes the widget from the screen and frees any memory the object
164 used.
165 drawCDKTemplate
167 draws the template widget on the screen. If box is true, the wid‐
168 get is drawn with a box.
169 eraseCDKTemplate
171 removes the widget from the screen. This does NOT destroy the
172 widget.
173 getCDKTemplateBox
175 returns true if the widget will be drawn with a box around it.
176 getCDKTemplateMin
178 returns the minimum characters that must be entered before the
179 widget will exit.
180 getCDKTemplateValue
182 returns the current value of the widget.
183 injectCDKTemplate
185 injects a single character into the widget. The parameter tem‐
186 plate is a pointer to a non-NULL template widget. The parameter
187 character is the character to inject into the widget. The return
188 value and side-effect (setting the widget data exitType) depend
189 upon the injected character:
190 RETURN or TAB
192 the function returns a char * representing the information
193 typed into the widget. The widget data exitType is set to
194 vNORMAL.
195 ESCAPE the function returns a NULL pointer. The widget data exit‐
197 Type is set to vESCAPE_HIT.
198 Otherwise
200 unless modified by preprocessing, postprocessing or key
201 bindings, the function returns a NULL pointer. The widget
202 data exitType is set to vEARLY_EXIT.
203 mixCDKTemplate
205 returns a char* pointer to the field value and the plate.
206 moveCDKTemplate
208 moves the given widget to the given position. The parameters xpos
209 and ypos are the new position of the widget. The parameter xpos
210 is an integer or one of the predefined values TOP, BOTTOM, and
211 CENTER. The parameter ypos may be an integer or one of the pre-
212 defined values LEFT, RIGHT, and CENTER. The parameter relative
213 states whether the xpos/ypos pair is a relative move or an abso‐
214 lute move. For example, if xpos = 1 and ypos = 2 and relative =
215 TRUE, then the widget would move one row down and two columns
216 right. If the value of relative was FALSE then the widget would
217 move to the position (1,2). Do not use the values TOP, BOTTOM,
218 LEFT, RIGHT, or CENTER when relative = TRUE (weird things may hap‐
219 pen). The final parameter refresh is a boolean value which states
220 whether the widget will be repainted after the move.
221 newCDKTemplate
223 creates a template widget, returning a pointer to it. Parameters:
224 screen
226 is the screen you wish this widget to be placed in.
227 xpos controls the placement of the object along the horizontal
229 axis. It may be an integer or one of the pre-defined values
230 LEFT, RIGHT, and CENTER.
231 ypos controls the placement of the object along the vertical axis.
233 It may be an integer or one of the pre-defined values TOP,
234 BOTTOM, and CENTER.
235 title
237 is the string to display at the top of the widget. The title
238 can be more than one line; just provide a carriage return
239 character at the line break.
240 label
242 is the string to display in the label of the template field.
243 plate
245 defines the character to allow at each position in the tem‐
246 plate field. This is done by creating a character plate by
247 using special format character to tell the template widget
248 what type of character is allowed where in the template wid‐
249 get. The following table lists the format types.
250 Plate_Character Effect
252 ──────────────────────────────────────────────────────
253 # Accepts an integer.
254 A Accepts an alphabetic value.
255 C Accepts an alphabetic value. Auto‐
256 matically converts the character to
257 upper case.
258 c Accepts an alphabetic value. Auto‐
259 matically converts the character to
260 lower case.
261 M Accepts alphanumeric characters.
262 X Accepts alphanumeric characters.
266 Automatically converts the charac‐
267 ter to upper case.
268 x Accepts alphanumeric characters.
269 Automatically converts the charac‐
270 ter to upper case.
271 Anything else Ignored and assumed a non-editable
272 position.
273 ──────────────────────────────────────────────────────
274 overlay
276 is the overlay of the template field. If the field needs
277 some sort of overlay, this parameter supplies this. A date
278 field could have YY/MM/DD, the overlay parameter would dis‐
279 play YY/MM/DD on an empty template field.
280 box is true if the widget should be drawn with a box around it.
282 shadow
284 turns the shadow on or off around this widget.
285 If the widget could not be created then a NULL pointer is
287 returned.
288 positionCDKTemplate
290 allows the user to move the widget around the screen via the sin‐
291 gle keystroke commands. See cdk_position (3) for key bindings.
292 setCDKTemplate
294 lets the programmer modify certain elements of an existing tem‐
295 plate widget. The parameter names correspond to the same parame‐
296 ter names listed in the newCDKTemplate function.
297 setCDKTemplateBackgroundAttrib
299 sets the background attribute of the widget. The parameter
300 attribute is a curses attribute, e.g., A_BOLD.
301 setCDKTemplateBackgroundColor
303 sets the background color of the widget. The parameter color is
304 in the format of the Cdk format strings. For more information,
305 see the cdk_display [4m(3).
306 setCDKTemplateBox
308 sets a flag, true if the widget will be drawn with a box around
309 it.
310 setCDKTemplateBoxAttribute
312 sets the attribute of the box.
313 setCDKTemplateCB
315 allows the programmer to set a different widget input handler.
316 The parameter callbackFunction is of type TEMPLATECB. The default
317 input handler is CDKTemplateCallBack.
318 setCDKTemplateHorizontalChar
320 sets the horizontal drawing character for the box to the given
321 character.
322 setCDKTemplateLLChar
324 sets the lower left hand corner of the widget's box to the given
325 character.
326 setCDKTemplateLRChar
328 sets the lower right hand corner of the widget's box to the given
329 character.
330 setCDKTemplateMin
332 sets the minimum number of characters that must be entered before
333 the widget will exit.
334 setCDKTemplatePostProcess
336 allows the user to have the widget call a function after the key
337 has been applied to the widget. To learn more about post-process‐
338 ing see cdk_process (3).
339 setCDKTemplatePreProcess
341 allows the user to have the widget call a function after a key is
342 hit and before the key is applied to the widget. To learn more
343 about preprocessing see cdk_process (3).
344 setCDKTemplateULChar
346 sets the upper left hand corner of the widget's box to the given
347 character.
348 setCDKTemplateURChar
350 sets the upper right hand corner of the widget's box to the given
351 character.
352 setCDKTemplateValue
354 sets a value in the widget.
355 setCDKTemplateVerticalChar
357 sets the vertical drawing character for the box to the given char‐
358 acter.
359 unmixCDKTemplate
361 returns a char* pointer to the field value without any plate char‐
362 acters.
363
365 When the widget is activated there are several default key bindings
366 which will help the user enter or manipulate the information quickly.
367 The following table outlines the keys and their actions for this wid‐
368 get.
369 ┌────────────────┬─────────────────────────────────────┐
371 │Key │ Action │
372 ├────────────────┼─────────────────────────────────────┤
373 ├────────────────┼─────────────────────────────────────┤
374 │Delete │ Deletes the character at the cur‐ │
375 │ │ sor. │
376 ├────────────────┼─────────────────────────────────────┤
377 │Backspace │ Deletes the character before cur‐ │
378 │ │ sor, moves cursor left. │
379 ├────────────────┼─────────────────────────────────────┤
380 │Ctrl-P │ Pastes whatever is in the paste │
381 │ │ buffer, into the widget. │
382 ├────────────────┼─────────────────────────────────────┤
383 │Ctrl-K │ Cuts the contents from the widget │
384 │ │ and saves a copy in the paste buf‐ │
385 │ │ fer. │
386 ├────────────────┼─────────────────────────────────────┤
387 │Ctrl-T │ Copies the contents of the widget │
388 │ │ into the paste buffer. │
389 ├────────────────┼─────────────────────────────────────┤
390 │Ctrl-E │ Erases the contents of the widget. │
391 ├────────────────┼─────────────────────────────────────┤
392 │Return │ Exits the widget and returns a │
393 │ │ char* representing the information │
394 │ │ which was typed into the field. It │
395 │ │ also sets the widget data exitType │
396 │ │ to vNORMAL. │
397 ├────────────────┼─────────────────────────────────────┤
398 │Tab │ Exits the widget and returns a │
399 │ │ char* representing the information │
400 │ │ which was typed into the field. It │
401 │ │ also sets the widget data exitType │
402 │ │ to vNORMAL. │
403 ├────────────────┼─────────────────────────────────────┤
404 │Escape │ Exits the widget and returns a NULL │
405 │ │ pointer. It also sets the widget │
406 │ │ data exitType to vESCAPE_HIT. │
407 ├────────────────┼─────────────────────────────────────┤
408 │Ctrl-L │ Refreshes the screen. │
409 └────────────────┴─────────────────────────────────────┘
411 cdk(3), cdk_binding(3), cdk_display(3), cdk_screen(3)
412 cdk_template(3)