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

NAME

6       cdk_entry - curses text-entry widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       char *activateCDKEntry (
14                      CDKENTRY *entry,
15                      chtype *actions);
16
17       void cleanCDKEntry (
18                      CDKENTRY *entry);
19
20       void destroyCDKEntry (
21                      CDKENTRY *entry);
22
23       void drawCDKEntry (
24                      CDKENTRY *entry,
25                      boolean box);
26
27       void eraseCDKEntry (
28                      CDKENTRY *entry);
29
30       boolean getCDKEntryBox (
31                      CDKENTRY *entry);
32
33       chtype getCDKEntryFillerChar (
34                      CDKENTRY *entry);
35
36       chtype getCDKEntryHiddenChar (
37                      CDKENTRY *entry);
38
39       int getCDKEntryMax (
40                      CDKENTRY *entry);
41
42       int getCDKEntryMin (
43                      CDKENTRY *entry);
44
45       char *getCDKEntryValue (
46                      CDKENTRY *entry);
47
48       int injectCDKEntry (
49                      CDKENTRY *entry,
50                      chtype input);
51
52       void moveCDKEntry (
53                      CDKENTRY *entry,
54                      int xpos,
55                      int ypos,
56                      boolean relative,
57                      boolean refresh);
58
59       CDKENTRY *newCDKEntry (
60                      CDKSCREEN *cdkscreen,
61                      int xpos,
62                      int ypos,
63                      const char *title,
64                      const char *label,
65                      chtype fieldAttribute,
66                      chtype fillerCharacter,
67                      EDisplayType displayType,
68                      int fieldWidth,
69                      int minimumLength,
70                      int maximumLength,
71                      boolean box,
72                      boolean shadow);
73
74       void positionCDKEntry (
75                      CDKENTRY *entry);
76
77       void setCDKEntry (
78                      CDKENTRY *entry,
79                      const char *value,
80                      int minimumLength,
81                      int maximumLength,
82                      boolean box);
83
84       void setCDKEntryBackgroundAttrib (
85                      CDKENTRY *entry,
86                      chtype attribute);
87
88       void setCDKEntryBackgroundColor (
89                      CDKENTRY *entry,
90                      const char * color);
91
92       void setCDKEntryBox (
93                      CDKENTRY *entry,
94                      boolean box);
95
96       void setCDKEntryBoxAttribute (
97                      CDKENTRY *entry,
98                      chtype character);
99
100       void setCDKEntryCB (
101                      CDKENTRY *entry,
102                      ENTRYCB callBackFunction);
103
104       void setCDKEntryFillerChar (
105                      CDKENTRY *entry,
106                      chtype character);
107
108       void setCDKEntryHiddenChar (
109                      CDKENTRY *entry,
110                      chtype character);
111
112       void setCDKEntryHighlight (
113                      CDKENTRY *entry,
114                      chtype highlight,
115                      boolean cursor);
116
117       void setCDKEntryHorizontalChar (
118                      CDKENTRY *entry,
119                      chtype character);
120
121       void setCDKEntryLLChar (
122                      CDKENTRY *entry,
123                      chtype character);
124
125       void setCDKEntryLRChar (
126                      CDKENTRY *entry,
127                      chtype character);
128
129       void setCDKEntryMax (
130                      CDKENTRY *entry,
131                      int maximum);
132
133       void setCDKEntryMin (
134                      CDKENTRY *entry,
135                      int minimum);
136
137       void setCDKEntryPostProcess (
138                      CDKENTRY *entry,
139                      PROCESSFN callback,
140                      void * data);
141
142       void setCDKEntryPreProcess (
143                      CDKENTRY *entry,
144                      PROCESSFN callback,
145                      void * data);
146
147       void setCDKEntryULChar (
148                      CDKENTRY *entry,
149                      chtype character);
150
151       void setCDKEntryURChar (
152                      CDKENTRY *entry,
153                      chtype character);
154
155       void setCDKEntryValue (
156                      CDKENTRY *entry,
157                      const char *value);
158
159       void setCDKEntryVerticalChar (
160                      CDKENTRY *entry,
161                      chtype character);
162

DESCRIPTION

164       The Cdk entry widget creates a text-entry box with a label and an entry
165       field.  The following functions create or manipulate the Cdk entry  box
166       widget.
167

AVAILABLE FUNCTIONS

169       activateCDKEntry
170            activates  the  entry  widget  and lets the user interact with the
171            widget.
172
173            ·   The parameter entry is a pointer to a non-NULL entry widget.
174
175            ·   If the actions parameter is passed with a non-NULL value,  the
176                characters in the array will be injected into the widget.
177
178                To  activate  the  widget interactively pass in a NULL pointer
179                for actions.
180
181            If the character entered into this widget is RETURN  or  TAB  then
182            this  function  will  return a char * representing the information
183            typed into the widget and the widget data exitType will be set  to
184            vNORMAL.
185
186            If  the character entered was ESCAPE then the function will return
187            NULL pointer and the widget data exitType is set to vESCAPE_HIT.
188
189       cleanCDKEntry
190            clears the information from the field.
191
192       destroyCDKEntry
193            removes the widget from the screen and  frees  memory  the  object
194            used.
195
196       drawCDKEntry
197            draws the entry widget on the screen.
198
199            If the box parameter is true, the widget is drawn with a box.
200
201       eraseCDKEntry
202            removes  the  widget  from  the screen.  This does NOT destroy the
203            widget.
204
205       getCDKEntryBox
206            returns true if the widget will be drawn with a box around it.
207
208       getCDKEntryFillerChar
209            returns the character being used to draw unused space in the  wid‐
210            get.
211
212       getCDKEntryHiddenChar
213            returns  the  character  being  used  to draw the hidden character
214            type.
215
216       getCDKEntryMax
217            returns the maximum length of a string the widget will allow.
218
219       getCDKEntryMin
220            returns the minimum length of a string the widget will allow.
221
222       getCDKEntryValue
223            returns the current value of the widget.
224
225       injectCDKEntry
226            injects a single character into the widget.
227
228            ·   The parameter entry is a pointer to a non-NULL entry widget.
229
230            ·   The parameter character is the character to  inject  into  the
231                widget.
232
233            The  return  value  and side-effect (setting the widget data exit‐
234            Type) depend upon the injected character:
235
236            RETURN or TAB
237                   the function returns a char * representing the  information
238                   typed  into the widget.  The widget data exitType is set to
239                   vNORMAL.
240
241            ESCAPE the function returns a NULL pointer.  The widget data exit‐
242                   Type is set to vESCAPE_HIT.
243
244            Otherwise
245                   unless  modified  by  preprocessing,  postprocessing or key
246                   bindings, the function returns a NULL pointer.  The  widget
247                   data exitType is set to vEARLY_EXIT.
248
249       moveCDKEntry
250            moves the given widget to the given position.
251
252            ·   The  parameters xpos and ypos are the new position of the wid‐
253                get.
254
255                The parameter xpos may be an integer or one of the pre-defined
256                values TOP, BOTTOM, and CENTER.
257
258                The parameter ypos may be an integer or one of the pre-defined
259                values LEFT, RIGHT, and CENTER.
260
261            ·   The parameter relative states whether the xpos/ypos pair is  a
262                relative move or an absolute move.
263
264                For  example,  if  xpos  = 1 and ypos = 2 and relative = TRUE,
265                then the widget would move one row down and two columns right.
266                If the value of relative was FALSE, then the widget would move
267                to the position (1,2).
268
269                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
270                relative = TRUE.  (weird things may happen).
271
272            ·   The  final  parameter  refresh is a boolean value which states
273                whether the widget will get refreshed after the move.
274
275       newCDKEntry
276            creates a pointer to an entry widget.  Parameters:
277
278            ·   The screen parameter is the screen you wish this widget to  be
279                placed in.
280
281            ·   xpos controls the placement of the object along the horizontal
282                axis.  It may be an integer or one of the  pre-defined  values
283                LEFT, RIGHT, and CENTER.
284
285            ·   ypos  controls  the placement of the object along the vertical
286                axis.  It may be an integer or one of the  pre-defined  values
287                TOP, BOTTOM, and CENTER.
288
289            ·   title  is the string which will be displayed at the top of the
290                widget.  The title can be more than one line; just  provide  a
291                carriage return character at the line break.
292
293            ·   label  is  the  string which will be displayed in the label of
294                the entry field.
295
296            ·   fieldAttribute is the attribute of the  characters  which  are
297                typed in.
298
299            ·   filler  is  the character which is to be displayed in an empty
300                space in the entry field.
301
302            ·   displayType tells how the entry field will behave when a char‐
303                acter  is  entered  into  the  field.  See cdk_display (3) for
304                valid values for this field.
305
306            ·   fieldWidth denotes the width of the field:
307
308                ·   If a value of zero is provided, the field will be made  as
309                    wide as possible on the screen.
310
311                ·   If a negative value is given, then the field width will be
312                    the maximum width minus the value provided.
313
314            ·   minimumLength controls the number of characters which must  be
315                entered before the user can exit the entry field.
316
317            ·   maximumLength  sets  the maximum number of characters that can
318                be entered.
319
320            ·   box is true if the widget should be drawn with  a  box  around
321                it.
322
323            ·   shadow turns the shadow on around this widget.
324
325            If  the  widget  could  not  be  created  then  a  NULL pointer is
326            returned.
327
328       positionCDKEntry
329            allows the user to move the widget around the screen via the  cur‐
330            sor/keypad  keys.   The following key bindings can be used to move
331            the widget around the screen.  See cdk_position (3) for key  bind‐
332            ings.
333
334       setCDKEntry
335            lets  the  programmer modify certain elements of an existing entry
336            widget.
337
338            ·   The value parameter sets the value  of  the  contents  of  the
339                entry field.
340
341            ·   The  other  parameter  names  correspond to the same parameter
342                names listed in the newCDKEntry function.
343
344       setCDKEntryBackgroundAttrib
345            sets the background attribute of the widget.
346
347            The parameter attribute is a curses attribute, e.g., A_BOLD.
348
349       setCDKEntryBackgroundColor
350            sets the background color of the widget.
351
352            The parameter color is in the format of the  Cdk  format  strings.
353            See cdk_display (3).
354
355       setCDKEntryBox
356            sets whether the widget will be drawn with a box around it.
357
358       setCDKEntryBoxAttribute
359            function sets the attribute of the box.
360
361       setCDKEntryCB
362            allows the programmer to set a different widget input handler.
363
364            The parameter callbackFunction is of type ENTRYCB.
365
366            The default function is CDKEntryCallBack.
367
368       setCDKEntryFillerChar
369            sets the character to use when drawing unused space in the field.
370
371       setCDKEntryHiddenChar
372            sets the character to use when using a hidden character type.
373
374       setCDKEntryHighlight
375            sets the attribute of the entry field.
376
377       setCDKEntryHorizontalChar
378            sets  the  horizontal  drawing  character for the box to the given
379            character.
380
381       setCDKEntryLLChar
382            sets the lower left hand corner of the widget's box to  the  given
383            character.
384
385       setCDKEntryLRChar
386            sets  the lower right hand corner of the widget's box to the given
387            character.
388
389       setCDKEntryMax
390            sets the maximum length of the string that the widget will allow.
391
392       setCDKEntryMin
393            sets the minimum length of the string that the widget will allow.
394
395       setCDKEntryPostProcess
396            allows the user to have the widget call a function after  the  key
397            has been applied to the widget.
398
399            ·   The parameter function is the callback function.
400
401            ·   The parameter data points to data passed to the callback func‐
402                tion.
403
404            To learn more about post-processing see cdk_process (3).
405
406       setCDKEntryPreProcess
407            allows the user to have the widget call a function after a key  is
408            hit and before the key is applied to the widget.
409
410            ·   The parameter function is the callback function.
411
412            ·   The parameter data points to data passed to the callback func‐
413                tion.
414
415            To learn more about pre-processing see cdk_process (3).
416
417       setCDKEntryULChar
418            sets the upper left hand corner of the widget's box to  the  given
419            character.
420
421       setCDKEntryURChar
422            sets  the upper right hand corner of the widget's box to the given
423            character.
424
425       setCDKEntryValue
426            sets the current value of the widget.
427
428       setCDKEntryVerticalChar
429            sets the vertical drawing character for the box to the given char‐
430            acter.
431

KEY BINDINGS

433       When  the  widget  is  activated there are several default key bindings
434       which will help the user enter or manipulate the  information  quickly.
435       The  following  table outlines the keys and their actions for this wid‐
436       get.
437
438        Key           Action
439        ──────────────────────────────────────────────────────────────────────
440        Left Arrow    Moves the cursor to the left.
441        CTRL-B        Moves the cursor to the left.
442        Right Arrow   Moves the cursor to the right.
443        CTRL-F        Moves the cursor to the right.
444        Delete        Deletes the character at the cursor.
445        Backspace     Deletes the character before cursor, moves cursor left.
446        CTRL-V        Pastes whatever is in the paste buffer, into  the  wid‐
447                      get.
448        CTRL-X        Cuts  the  contents from the widget and saves a copy in
449                      the paste buffer.
450        CTRL-Y        Copies the contents of the widget into the  paste  buf‐
451                      fer.
452        CTRL-U        Erases the contents of the widget.
453        CTRL-A        Moves the cursor to the beginning of the entry field.
454        CTRL-E        Moves the cursor to the end of the entry field.
455        CTRL-T        Transposes  the  character  under  the  cursor with the
456                      character to the right.
457        Return        Exits the widget and returns a char * representing  the
458                      information  which  was  typed into the field.  It also
459                      sets the widget data exitType to vNORMAL.
460        Tab           Exits the widget and returns a char * representing  the
461                      information  which  was  typed into the field.  It also
462                      sets the widget data exitType to vNORMAL.
463        Escape        Exits the widget and returns a NULL pointer.   It  also
464                      sets the widget data exitType to vESCAPE_HIT.
465        Ctrl-L        Refreshes the screen.
466        ──────────────────────────────────────────────────────────────────────
467

SEE ALSO

469       cdk(3),      cdk_binding(3),      cdk_display(3),      cdk_position(3),
470       cdk_process(3), cdk_screen(3)
471
472
473
474                                                                  cdk_entry(3)
Impressum