1cdk_selection(3) Library Functions Manual cdk_selection(3)
2
6 cdk_selection - curses selection list widget.
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 int activateCDKSelection (
14 CDKSELECTION *selection,
15 chtype * actions);
16 void destroyCDKSelection (
18 CDKSELECTION *selection);
19 void drawCDKSelection (
21 CDKSELECTION *selection,
22 boolean box);
23 void eraseCDKSelection (
25 CDKSELECTION *selection);
26 boolean getCDKSelectionBox (
28 CDKSELECTION *selection);
29 int getCDKSelectionChoice (
31 CDKSELECTION *selection,
32 int index);
33 int *getCDKSelectionChoices (
35 CDKSELECTION *selection);
36 int getCDKSelectionCurrent (
38 CDKSELECTION *selection);
39 chtype getCDKSelectionHighlight (
41 CDKSELECTION *selection);
42 int getCDKSelectionItems (
44 CDKSELECTION *selection,
45 char **list);
46 int getCDKSelectionMode (
48 CDKSELECTION *selection,
49 int index);
50 int *getCDKSelectionModes (
52 CDKSELECTION *selection);
53 char *getCDKSelectionTitle (
55 CDKSELECTION *selection);
56 int injectCDKSelection (
58 CDKSELECTION *selection,
59 chtype input);
60 void moveCDKSelection (
62 CDKSELECTION *selection,
63 int xpos,
64 int ypos,
65 boolean relative,
66 boolean refresh);
67 CDKSELECTION *newCDKSelection (
69 CDKSCREEN *cdkscreen,
70 int xpos,
71 int ypos,
72 int spos,
73 int height,
74 int width,
75 const char *title,
76 CDK_CONST char **selectionList,
77 int selectionListLength,
78 CDK_CONST char **choiceList,
79 int choiceListLength,
80 chtype highlight,
81 boolean box,
82 boolean shadow);
83 void positionCDKSelection (
85 CDKSELECTION *selection);
86 void setCDKSelection (
88 CDKSELECTION *selection,
89 chtype highlight,
90 int *defChoices,
91 boolean box);
92 void setCDKSelectionBackgroundAttrib (
94 CDKSELECTION *selection,
95 chtype attribute);
96 void setCDKSelectionBackgroundColor (
98 CDKSELECTION *selection,
99 const char * color);
100 void setCDKSelectionBox (
102 CDKSELECTION *selection,
103 boolean boxWidget);
104 void setCDKSelectionBoxAttribute (
106 CDKSELECTION *selection,
107 chtype character);
108 void setCDKSelectionChoice (
110 CDKSELECTION *selection,
111 int index,
112 int choice);
113 void setCDKSelectionChoices (
115 CDKSELECTION *selection,
116 int *choices);
117 void setCDKSelectionCurrent (
119 CDKSELECTION *selection,
120 intindex);
121 void setCDKSelectionHighlight (
123 CDKSELECTION *selection,
124 chtype highlight);
125 void setCDKSelectionHorizontalChar (
127 CDKSELECTION *selection,
128 chtype character);
129 void setCDKSelectionItems (
131 CDKSELECTION *selection,
132 CDK_CONST char **list,
133 int listSize);
134 void setCDKSelectionLLChar (
136 CDKSELECTION *selection,
137 chtype character);
138 void setCDKSelectionLRChar (
140 CDKSELECTION *selection,
141 chtype character);
142 void setCDKSelectionMode (
144 CDKSELECTION *selection,
145 int index,
146 int mode);
147 void setCDKSelectionModes (
149 CDKSELECTION *selection,
150 int *modes);
151 void setCDKSelectionPostProcess (
153 CDKSELECTION *selection,
154 PROCESSFN callback,
155 void * data);
156 void setCDKSelectionPreProcess (
158 CDKSELECTION *selection,
159 PROCESSFN callback,
160 void * data);
161 void setCDKSelectionTitle (
163 CDKSELECTION *selection,
164 const char *title);
165 void setCDKSelectionULChar (
167 CDKSELECTION *selection,
168 chtype character);
169 void setCDKSelectionURChar (
171 CDKSELECTION *selection,
172 chtype character);
173 void setCDKSelectionVerticalChar (
175 CDKSELECTION *selection,
176 chtype character);
177
179 The Cdk selection widget creates a selection list. The following func‐
180 tions create or manipulate the Cdk selection list widget.
181
183 activateCDKSelection
184 activates the selection widget and lets the user interact with the
185 widget.
186 · The parameter selection is a pointer to a non-NULL selection
188 widget.
189 · If the actions parameter is passed with a non-NULL value, the
191 characters in the array will be injected into the widget.
192 To activate the widget interactively pass in a NULL pointer
194 for actions.
195 If the character entered into this widget is RETURN or TAB then
197 this function will return 1. It will also set the widget data
198 exitType to vNORMAL. If the character entered into this widget
199 was ESCAPE then the widget will return a value of -1 and the wid‐
200 get data exitType will be set to vESCAPE_HIT.
201 destroyCDKSelection
203 removes the widget from the screen and frees memory the object
204 used.
205 drawCDKSelection
207 draws the selection widget on the screen. If the box parameter is
208 true, the widget is drawn with a box.
209 eraseCDKSelection
211 removes the widget from the screen. This does NOT destroy the
212 widget.
213 getCDKSelectionBox
215 returns true if the widget will be drawn with a box around it.
216 getCDKSelectionChoice
218 returns the selection choice at the given index.
219 getCDKSelectionChoices
221 returns an array of the current selection choices for the widget.
222 getCDKSelectionCurrent
224 returns the current selection index.
225 getCDKSelectionHighlight
227 returns the attribute of the highlight bar.
228 getCDKSelectionItems
230 optionally copies the selection-list items into the caller's list,
231 which must be large enough since this function does not allocate
232 it. If the list parameter is null, no copying is done. It
233 returns the list size whether or not the list parameter is null.
234 getCDKSelectionMode
236 returns the selection mode at the given index.
237 getCDKSelectionModes
239 returns an array of the current modes for the widget.
240 getCDKSelectionTitle
242 returns the first line of the title of the selection widget. The
243 caller must free the returned value.
244 injectCDKSelection
246 injects a single character into the widget.
247 · The parameter selection is a pointer to a non-NULL selection
249 widget.
250 · The parameter character is the character to inject into the
252 widget.
253 The return value and side-effect (setting the widget data exit‐
255 Type) depend upon the injected character:
256 RETURN or TAB
258 the function returns 1. The widget data exitType is set to
259 vNORMAL.
260 ESCAPE the function returns -1. vESCAPE_HIT. The widget data
262 exitType is set to vESCAPE_HIT.
263 Otherwise
265 unless modified by preprocessing, postprocessing or key
266 bindings, the function returns -1. The widget data exit‐
267 Type is set to vEARLY_EXIT.
268 moveCDKSelection
270 moves the given widget to the given position.
271 · The parameters xpos and ypos are the new position of the wid‐
273 get.
274 · The parameter xpos may be an integer or one of the pre-defined
276 values TOP, BOTTOM, and CENTER.
277 · The parameter ypos may be an integer or one of the pre-defined
279 values LEFT, RIGHT, and CENTER.
280 · The parameter relative states whether the xpos/ypos pair is a
282 relative move or an absolute move.
283 For example, if xpos = 1 and ypos = 2 and relative = TRUE,
285 then the widget would move one row down and two columns right.
286 If the value of relative was FALSE, then the widget would move
287 to the position (1,2).
288 Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
290 relative = TRUE. (weird things may happen).
291 · The final parameter refresh is a boolean value which states
293 whether the widget will get refreshed after the move.
294 newCDKSelection
296 creates a selection widget and returns a pointer to it. Parame‐
297 ters:
298 screen
300 is the screen you wish this widget to be placed in.
301 xpos controls the placement of the object along the horizontal
303 axis. It may be an integer or one of the pre-defined values
304 LEFT, RIGHT, and CENTER.
305 ypos controls the placement of the object along the vertical axis.
307 It may be an integer or one of the pre-defined values TOP,
308 BOTTOM, and CENTER.
309 spos is where the scroll bar is to be placed. It may be one of
311 three values:
312 LEFT puts the scroll bar on the left of the scrolling list.
314 RIGHT puts the scroll bar on the right side of the list,
315 and
316 NONE does not add a scroll bar.
318 height and
320 width
322 control the height and width of the widget. If you provide a
323 value of zero for either of the height or the width, the wid‐
324 get will be created with the full width and height of the
325 screen. If you provide a negative value, the widget will be
326 created the full height or width minus the value provided.
327 title
329 is the string which to display at the top of the widget. The
330 title can be more than one line; just provide a carriage
331 return character at the line break.
332 selectionList
334 is the list of items to display in the selection list
335 selectionListLength
337 is the number of elements in the given list.
338 choiceList
340 is the list of choices that will be selected when the user
341 presses the space bar.
342 choiceListLength
344 is the length of this list.
345 highlight
347 specifies the display attribute of the currently selected
348 item.
349 box is true if the widget should be drawn with a box around it.
351 shadow
353 turns the shadow on or off around this widget.
354 If the widget could not be created then a NULL pointer is
356 returned.
357 positionCDKSelection
359 allows the user to move the widget around the screen via the cur‐
360 sor/keypad keys. See cdk_position (3) for key bindings.
361 setCDKSelection
363 lets the programmer modify certain elements of an existing selec‐
364 tion widget. The parameter names correspond to the same parameter
365 names listed in the newCDKSelection function.
366 setCDKSelectionBackgroundAttrib
368 sets the background attribute of the widget. The parameter
369 attribute is a curses attribute, e.g., A_BOLD.
370 setCDKSelectionBackgroundColor
372 sets the background color of the widget. The parameter color is
373 in the format of the Cdk format strings. See cdk_display (3).
374 setCDKSelectionBox
376 sets whether the widget will be drawn with a box around it.
377 setCDKSelectionBoxAttribute
379 sets the attribute of the box.
380 setCDKSelectionChoice
382 sets the selection choice value at the given index.
383 setCDKSelectionChoices
385 sets the selection choice values of the widget.
386 setCDKSelectionCurrent
388 sets the current selection index.
389 setCDKSelectionHighlight
391 sets the attribute of the highlight bar.
392 setCDKSelectionHorizontalChar
394 sets the horizontal drawing character for the box to the given
395 character.
396 setCDKSelectionItems
398 sets the selection list items. The previous selection list items
399 stored in the widget are freed.
400 setCDKSelectionLLChar
402 sets the lower left hand corner of the widget's box to the given
403 character.
404 setCDKSelectionLRChar
406 sets the lower right hand corner of the widget's box to the given
407 character.
408 setCDKSelectionMode
410 sets the selection mode at the given index.
411 setCDKSelectionModes
413 sets the selection mode of the elements of the widget. There are
414 two acceptable values for the modes:
415 0 which allows the user to change the selection value at the
417 given index; and
418 1 which sets the element to a read-only state.
420 setCDKSelectionPostProcess
422 allows the user to have the widget call a function after the key
423 has been applied to the widget. The parameter function is the
424 callback function. The parameter data points to data passed to
425 the callback function. To learn more about post-processing see
426 cdk_process [4m(3).
427 setCDKSelectionPreProcess
429 allows the user to have the widget call a function after a key is
430 hit and before the key is applied to the widget. The parameter
431 function is the callback function. The parameter data is a
432 pointer to void. To learn more about pre-processing see
433 cdk_process [4m(3).
434 setCDKSelectionTitle
436 set the selection list's title.
437 setCDKSelectionULChar
439 sets the upper left hand corner of the widget's box to the given
440 character.
441 setCDKSelectionURChar
443 sets the upper right hand corner of the widget's box to the given
444 character.
445 setCDKSelectionVerticalChar
447 sets the vertical drawing character for the box to the given char‐
448 acter.
449
451 When the widget is activated there are several default key bindings
452 which help the user enter or manipulate the information quickly:
453 ┌─────────────────────────────────────────────────────────┐
455 │Key Action │
456 ├─────────────────────────────────────────────────────────┤
457 │Left Arrow Shift the whole list left one column. │
458 │Right Arrow Shift the whole list right one column. │
459 │Up Arrow Select the previous item in the list. │
460 │Down Arrow Select the next item in the list. │
461 ├─────────────────────────────────────────────────────────┤
462 │Prev Page │
463 │Ctrl-B Scroll one page backward. │
464 ├─────────────────────────────────────────────────────────┤
465 │Next Page │
466 │Ctrl-F Scroll one page forward. │
467 ├─────────────────────────────────────────────────────────┤
468 │1 │
469 │< │
470 │g │
471 │Home Move to the first element in the list. │
472 ├─────────────────────────────────────────────────────────┤
473 │> │
474 │G │
475 │End Move to the last element in the list. │
476 ├─────────────────────────────────────────────────────────┤
477 │$ Shift the whole list to the far right. │
478 │| Shift the whole list to the far left. │
479 ├─────────────────────────────────────────────────────────┤
480 │Space Cycles to the next choice on the cur‐ │
481 │ rent item. │
482 │Return Exit the widget and return 1. Also │
483 │ set the widget data exitType to vNOR‐ │
484 │ MAL. │
485 │Tab Exit the widget and return 1. Also │
486 │ set the widget data exitType to vNOR‐ │
487 │ MAL. │
488 │Escape Exit the widget and return -1. Also │
489 │ set the widget data exitType to │
490 │ vESCAPE_HIT. │
491 │Ctrl-L Refreshes the screen. │
492 └─────────────────────────────────────────────────────────┘
494 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
495 cdk_selection(3)