1cdk_entry(3) Library Functions Manual cdk_entry(3)
2
3
4
6 cdk_entry - curses text-entry widget.
7
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
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
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 [4m(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 [4m(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
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
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)