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.  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
159       cleanCDKTemplate
160            clears the information from the field.
161
162       destroyCDKTemplate
163            removes the widget from the screen and frees any memory the object
164            used.
165
166       drawCDKTemplate
167            draws the template widget on the screen.  If box is true, the wid‐
168            get is drawn with a box.
169
170       eraseCDKTemplate
171            removes  the  widget  from  the screen.  This does NOT destroy the
172            widget.
173
174       getCDKTemplateBox
175            returns true if the widget will be drawn with a box around it.
176
177       getCDKTemplateMin
178            returns the minimum characters that must  be  entered  before  the
179            widget will exit.
180
181       getCDKTemplateValue
182            returns the current value of the widget.
183
184       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
191            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
196            ESCAPE the function returns a NULL pointer.  The widget data exit‐
197                   Type is set to vESCAPE_HIT.
198
199            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
204       mixCDKTemplate
205            returns a char* pointer to the field value and the plate.
206
207       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
222       newCDKTemplate
223            creates a template widget, returning a pointer to it.  Parameters:
224
225            screen
226                 is the screen you wish this widget to be placed in.
227
228            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
232            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
236            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
241            label
242                 is the string to display in the label of the template field.
243
244            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
251                  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
263
264
265                  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
275            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
281            box  is true if the widget should be drawn with a box around it.
282
283            shadow
284                 turns the shadow on or off around this widget.
285
286            If the widget  could  not  be  created  then  a  NULL  pointer  is
287            returned.
288
289       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
293       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
298       setCDKTemplateBackgroundAttrib
299            sets the  background  attribute  of  the  widget.   The  parameter
300            attribute is a curses attribute, e.g., A_BOLD.
301
302       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 (3).
306
307       setCDKTemplateBox
308            sets  a  flag,  true if the widget will be drawn with a box around
309            it.
310
311       setCDKTemplateBoxAttribute
312            sets the attribute of the box.
313
314       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
319       setCDKTemplateHorizontalChar
320            sets the horizontal drawing character for the  box  to  the  given
321            character.
322
323       setCDKTemplateLLChar
324            sets  the  lower left hand corner of the widget's box to the given
325            character.
326
327       setCDKTemplateLRChar
328            sets the lower right hand corner of the widget's box to the  given
329            character.
330
331       setCDKTemplateMin
332            sets  the minimum number of characters that must be entered before
333            the widget will exit.
334
335       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
340       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
345       setCDKTemplateULChar
346            sets the upper left hand corner of the widget's box to  the  given
347            character.
348
349       setCDKTemplateURChar
350            sets  the upper right hand corner of the widget's box to the given
351            character.
352
353       setCDKTemplateValue
354            sets a value in the widget.
355
356       setCDKTemplateVerticalChar
357            sets the vertical drawing character for the box to the given char‐
358            acter.
359
360       unmixCDKTemplate
361            returns a char* pointer to the field value without any plate char‐
362            acters.
363

KEY BINDINGS

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

SEE ALSO

411       cdk(3), cdk_binding(3), cdk_display(3), cdk_screen(3)
412
413
414
415                                                               cdk_template(3)
Impressum