1cdk_entry(3) Library Functions Manual cdk_entry(3)
2
6 cdk_entry - curses text-entry widget.
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 char *activateCDKEntry (
14 CDKENTRY *entry,
15 chtype *actions);
16 void cleanCDKEntry (
18 CDKENTRY *entry);
19 void destroyCDKEntry (
21 CDKENTRY *entry);
22 void drawCDKEntry (
24 CDKENTRY *entry,
25 boolean box);
26 void eraseCDKEntry (
28 CDKENTRY *entry);
29 boolean getCDKEntryBox (
31 CDKENTRY *entry);
32 chtype getCDKEntryFillerChar (
34 CDKENTRY *entry);
35 chtype getCDKEntryHiddenChar (
37 CDKENTRY *entry);
38 int getCDKEntryMax (
40 CDKENTRY *entry);
41 int getCDKEntryMin (
43 CDKENTRY *entry);
44 char *getCDKEntryValue (
46 CDKENTRY *entry);
47 int injectCDKEntry (
49 CDKENTRY *entry,
50 chtype input);
51 void moveCDKEntry (
53 CDKENTRY *entry,
54 int xpos,
55 int ypos,
56 boolean relative,
57 boolean refresh);
58 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 void positionCDKEntry (
75 CDKENTRY *entry);
76 void setCDKEntry (
78 CDKENTRY *entry,
79 const char *value,
80 int minimumLength,
81 int maximumLength,
82 boolean box);
83 void setCDKEntryBackgroundAttrib (
85 CDKENTRY *entry,
86 chtype attribute);
87 void setCDKEntryBackgroundColor (
89 CDKENTRY *entry,
90 const char * color);
91 void setCDKEntryBox (
93 CDKENTRY *entry,
94 boolean box);
95 void setCDKEntryBoxAttribute (
97 CDKENTRY *entry,
98 chtype character);
99 void setCDKEntryCB (
101 CDKENTRY *entry,
102 ENTRYCB callBackFunction);
103 void setCDKEntryFillerChar (
105 CDKENTRY *entry,
106 chtype character);
107 void setCDKEntryHiddenChar (
109 CDKENTRY *entry,
110 chtype character);
111 void setCDKEntryHighlight (
113 CDKENTRY *entry,
114 chtype highlight,
115 boolean cursor);
116 void setCDKEntryHorizontalChar (
118 CDKENTRY *entry,
119 chtype character);
120 void setCDKEntryLLChar (
122 CDKENTRY *entry,
123 chtype character);
124 void setCDKEntryLRChar (
126 CDKENTRY *entry,
127 chtype character);
128 void setCDKEntryMax (
130 CDKENTRY *entry,
131 int maximum);
132 void setCDKEntryMin (
134 CDKENTRY *entry,
135 int minimum);
136 void setCDKEntryPostProcess (
138 CDKENTRY *entry,
139 PROCESSFN callback,
140 void * data);
141 void setCDKEntryPreProcess (
143 CDKENTRY *entry,
144 PROCESSFN callback,
145 void * data);
146 void setCDKEntryULChar (
148 CDKENTRY *entry,
149 chtype character);
150 void setCDKEntryURChar (
152 CDKENTRY *entry,
153 chtype character);
154 void setCDKEntryValue (
156 CDKENTRY *entry,
157 const char *value);
158 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 · The parameter entry is a pointer to a non-NULL entry widget.
174 · If the actions parameter is passed with a non-NULL value, the
176 characters in the array will be injected into the widget.
177 To activate the widget interactively pass in a NULL pointer
179 for actions.
180 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 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 cleanCDKEntry
190 clears the information from the field.
191 destroyCDKEntry
193 removes the widget from the screen and frees memory the object
194 used.
195 drawCDKEntry
197 draws the entry widget on the screen.
198 If the box parameter is true, the widget is drawn with a box.
200 eraseCDKEntry
202 removes the widget from the screen. This does NOT destroy the
203 widget.
204 getCDKEntryBox
206 returns true if the widget will be drawn with a box around it.
207 getCDKEntryFillerChar
209 returns the character being used to draw unused space in the wid‐
210 get.
211 getCDKEntryHiddenChar
213 returns the character being used to draw the hidden character
214 type.
215 getCDKEntryMax
217 returns the maximum length of a string the widget will allow.
218 getCDKEntryMin
220 returns the minimum length of a string the widget will allow.
221 getCDKEntryValue
223 returns the current value of the widget.
224 injectCDKEntry
226 injects a single character into the widget.
227 · The parameter entry is a pointer to a non-NULL entry widget.
229 · The parameter character is the character to inject into the
231 widget.
232 The return value and side-effect (setting the widget data exit‐
234 Type) depend upon the injected character:
235 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 ESCAPE the function returns a NULL pointer. The widget data exit‐
242 Type is set to vESCAPE_HIT.
243 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 moveCDKEntry
250 moves the given widget to the given position.
251 · The parameters xpos and ypos are the new position of the wid‐
253 get.
254 The parameter xpos may be an integer or one of the pre-defined
256 values TOP, BOTTOM, and CENTER.
257 The parameter ypos may be an integer or one of the pre-defined
259 values LEFT, RIGHT, and CENTER.
260 · The parameter relative states whether the xpos/ypos pair is a
262 relative move or an absolute move.
263 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 Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
270 relative = TRUE. (weird things may happen).
271 · The final parameter refresh is a boolean value which states
273 whether the widget will get refreshed after the move.
274 newCDKEntry
276 creates a pointer to an entry widget. Parameters:
277 · The screen parameter is the screen you wish this widget to be
279 placed in.
280 · 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 · 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 · 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 · label is the string which will be displayed in the label of
294 the entry field.
295 · fieldAttribute is the attribute of the characters which are
297 typed in.
298 · filler is the character which is to be displayed in an empty
300 space in the entry field.
301 · 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 · fieldWidth denotes the width of the field:
307 · If a value of zero is provided, the field will be made as
309 wide as possible on the screen.
310 · If a negative value is given, then the field width will be
312 the maximum width minus the value provided.
313 · minimumLength controls the number of characters which must be
315 entered before the user can exit the entry field.
316 · maximumLength sets the maximum number of characters that can
318 be entered.
319 · box is true if the widget should be drawn with a box around
321 it.
322 · shadow turns the shadow on around this widget.
324 If the widget could not be created then a NULL pointer is
326 returned.
327 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 setCDKEntry
335 lets the programmer modify certain elements of an existing entry
336 widget.
337 · The value parameter sets the value of the contents of the
339 entry field.
340 · The other parameter names correspond to the same parameter
342 names listed in the newCDKEntry function.
343 setCDKEntryBackgroundAttrib
345 sets the background attribute of the widget.
346 The parameter attribute is a curses attribute, e.g., A_BOLD.
348 setCDKEntryBackgroundColor
350 sets the background color of the widget.
351 The parameter color is in the format of the Cdk format strings.
353 See cdk_display (3).
354 setCDKEntryBox
356 sets whether the widget will be drawn with a box around it.
357 setCDKEntryBoxAttribute
359 function sets the attribute of the box.
360 setCDKEntryCB
362 allows the programmer to set a different widget input handler.
363 The parameter callbackFunction is of type ENTRYCB.
365 The default function is CDKEntryCallBack.
367 setCDKEntryFillerChar
369 sets the character to use when drawing unused space in the field.
370 setCDKEntryHiddenChar
372 sets the character to use when using a hidden character type.
373 setCDKEntryHighlight
375 sets the attribute of the entry field.
376 setCDKEntryHorizontalChar
378 sets the horizontal drawing character for the box to the given
379 character.
380 setCDKEntryLLChar
382 sets the lower left hand corner of the widget's box to the given
383 character.
384 setCDKEntryLRChar
386 sets the lower right hand corner of the widget's box to the given
387 character.
388 setCDKEntryMax
390 sets the maximum length of the string that the widget will allow.
391 setCDKEntryMin
393 sets the minimum length of the string that the widget will allow.
394 setCDKEntryPostProcess
396 allows the user to have the widget call a function after the key
397 has been applied to the widget.
398 · The parameter function is the callback function.
400 · The parameter data points to data passed to the callback func‐
402 tion.
403 To learn more about post-processing see cdk_process [4m(3).
405 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 · The parameter function is the callback function.
411 · The parameter data points to data passed to the callback func‐
413 tion.
414 To learn more about pre-processing see cdk_process [4m(3).
416 setCDKEntryULChar
418 sets the upper left hand corner of the widget's box to the given
419 character.
420 setCDKEntryURChar
422 sets the upper right hand corner of the widget's box to the given
423 character.
424 setCDKEntryValue
426 sets the current value of the widget.
427 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 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 cdk_entry(3)