1cdk_template(3)            Library Functions Manual            cdk_template(3)
2
3
4

NAME

6       cdk_template - a curses template widget.
7

SYNOPSIS

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

DESCRIPTION

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

AVAILABLE FUNCTIONS

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 (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

KEY BINDINGS

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               ┌────────────────┬─────────────────────────────────────┐
399Key             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               └────────────────┴─────────────────────────────────────┘

SEE ALSO

439       cdk(3), cdk_binding(3), cdk_display(3), cdk_screen(3)
440
441
442
443                                                               cdk_template(3)
Impressum