1cdk_radio(3) Library Functions Manual cdk_radio(3)
2
6 cdk_radio - curses radio list widget.
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 int activateCDKRadio (
14 CDKRADIO *radio,
15 chtype *actions);
16 void destroyCDKRadio (
18 CDKRADIO *radio);
19 void drawCDKRadio (
21 CDKRADIO *radio,
22 boolean box);
23 void eraseCDKRadio (
25 CDKRADIO *radio);
26 boolean getCDKRadioBox (
28 CDKRADIO *radio);
29 chtype getCDKRadioChoiceCharacter (
31 CDKRADIO *radio);
32 int getCDKRadioCurrentItem (
34 CDKRADIO *radio);
35 chtype getCDKRadioHighlight (
37 CDKRADIO *radio);
38 int getCDKRadioItems (
40 CDKRADIO *radio,
41 char **list);
42 chtype getCDKRadioLeftBrace (
44 CDKRADIO *radio);
45 chtype getCDKRadioRightBrace (
47 CDKRADIO *radio);
48 int getCDKRadioSelectedItem (
50 CDKRADIO *radio);
51 int injectCDKRadio (
53 CDKRADIO *radio,
54 chtype input);
55 void moveCDKRadio (
57 CDKRADIO *radio,
58 int xpos,
59 int ypos,
60 boolean relative,
61 boolean refresh);
62 CDKRADIO *newCDKRadio (
64 CDKSCREEN *cdkscreen,
65 int xpos,
66 int ypos,
67 int spos,
68 int height,
69 int width,
70 const char *title,
71 CDK_CONST char **radioList,
72 int radioListLength,
73 chtype choiceCharacter,
74 int defaultItem,
75 chtype highlight,
76 boolean box,
77 boolean shadow);
78 void positionCDKRadio (
80 CDKRADIO *radio);
81 void setCDKRadio (
83 CDKRADIO *radio,
84 chtype highlight,
85 chtype choiceCharacter,
86 boolean box);
87 void setCDKRadioBackgroundAttrib (
89 CDKRADIO *radio,
90 chtype attribute);
91 void setCDKRadioBackgroundColor (
93 CDKRADIO *radio,
94 const char * color);
95 void setCDKRadioBox (
97 CDKRADIO *radio,
98 boolean box);
99 void setCDKRadioBoxAttribute (
101 CDKRADIO *radio,
102 chtype character);
103 void setCDKRadioChoiceCharacter (
105 CDKRADIO *radio,
106 chtype character);
107 void setCDKRadioCurrentItem (
109 CDKRADIO *radio,
110 intindex);
111 void setCDKRadioHighlight (
113 CDKRADIO *radio,
114 chtype highlight);
115 void setCDKRadioHorizontalChar (
117 CDKRADIO *radio,
118 chtype character);
119 void setCDKRadioItems (
121 CDKRADIO *radio,
122 CDK_CONST char **list,
123 int listSize);
124 void setCDKRadioLLChar (
126 CDKRADIO *radio,
127 chtype character);
128 void setCDKRadioLRChar (
130 CDKRADIO *radio,
131 chtype character);
132 void setCDKRadioLeftBrace (
134 CDKRADIO *radio,
135 chtype character);
136 void setCDKRadioPostProcess (
138 CDKRADIO *radio,
139 PROCESSFN callback,
140 void * data);
141 void setCDKRadioPreProcess (
143 CDKRADIO *radio,
144 PROCESSFN callback,
145 void * data);
146 void setCDKRadioRightBrace (
148 CDKRADIO *radio,
149 chtype character);
150 void setCDKRadioSelectedItem (
152 CDKRADIO *radio,
153 int item);
154 void setCDKRadioULChar (
156 CDKRADIO *radio,
157 chtype character);
158 void setCDKRadioURChar (
160 CDKRADIO *radio,
161 chtype character);
162 void setCDKRadioVerticalChar (
164 CDKRADIO *radio,
165 chtype character);
166
168 The Cdk radio widget creates a radio list. The following are functions
169 which create or manipulate the Cdk radio box widget.
170
172 activateCDKRadio
173 activates the radio widget and lets the user interact with the
174 widget.
175 · The parameter radio is a pointer to a non-NULL radio widget.
177 · If the actions parameter is passed with a non-NULL value, the
179 characters in the array will be injected into the widget. IP
180 To activate the widget interactively pass in a NULL pointer
181 for actions.
182 If the character entered into this widget is RETURN or TAB then
184 this function will return a value from 0 to the number of items
185 -1, representing the item selected. It will also set the widget
186 data exitType to vNORMAL.
187 If the character entered into this widget was ESCAPE then the wid‐
189 get will return a value of -1 and the widget data exitType will be
190 set to vESCAPE_HIT.
191 destroyCDKRadio
193 removes the widget from the screen and frees memory the object
194 used.
195 drawCDKRadio
197 draws the radio widget on the screen.
198 If the box parameter is true, the widget is drawn with a box.
200 eraseCDKRadio
202 removes the widget from the screen. This does NOT destroy the
203 widget.
204 getCDKRadioBox
206 returns true if the widget will be drawn with a box around it.
207 getCDKRadioChoiceCharacter
209 returns the character being used to draw the selected element in
210 the list.
211 getCDKRadioCurrentItem
213 returns the index of the current item.
214 getCDKRadioHighlight
216 returns the attribute of the highlight bar.
217 getCDKRadioItems
219 optionally copies the radio-box items into the caller's list,
220 which must be large enough since this function does not allocate
221 it. If the list parameter is null, no copying is done. It
222 returns the list size whether or not the list parameter is null.
223 getCDKRadioLeftBrace
225 returns the character being used to draw the left brace of the
226 selection box.
227 getCDKRadioRightBrace
229 returns the character being used to draw the right brace of the
230 selection box.
231 getCDKRadioSelectedItem,
233 returns the selected item of the widget.
234 injectCDKRadio
236 function injects a single character into the widget.
237 · The parameter radio is a pointer to a non-NULL radio widget.
239 · The parameter character is the character to inject into the
241 widget.
242 The return value and side-effect (setting the widget data exit‐
244 Type) depend upon the injected character:
245 RETURN or TAB
247 the function returns a value ranging from zero to one less
248 than the number of items, representing the items selected.
249 The widget data exitType is set to vNORMAL.
250 ESCAPE the function returns -1. The widget data exitType is set
252 to vESCAPE_HIT.
253 Otherwise
255 unless modified by preprocessing, postprocessing or key
256 bindings, the function returns -1. The widget data exit‐
257 Type is set to vEARLY_EXIT.
258 moveCDKRadio
260 moves the given widget to the given position.
261 · The parameters xpos and ypos are the new position of the wid‐
263 get.
264 The parameter xpos may be an integer or one of the pre-defined
266 values TOP, BOTTOM, and CENTER.
267 The parameter ypos may be an integer or one of the pre-defined
269 values LEFT, RIGHT, and CENTER.
270 · The parameter relative states whether the xpos/ypos pair is a
272 relative move or an absolute move.
273 For example, if xpos = 1 and ypos = 2 and relative = TRUE,
275 then the widget would move one row down and two columns right.
276 If the value of relative was FALSE, then the widget would move
277 to the position (1,2).
278 Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
280 relative = TRUE. (weird things may happen).
281 · The final parameter refresh is a boolean value which states
283 whether the widget will get refreshed after the move.
284 newCDKRadio
286 creates a radio widget and returns a pointer to it. Parameters:
287 screen
289 is the screen you wish this widget to be placed in.
290 xpos controls the placement of the object along the horizontal
292 axis. It may be an integer or one of the pre-defined values
293 LEFT, RIGHT, and CENTER.
294 ypos controls the placement of the object along the vertical axis.
296 It may be an integer or one of the pre-defined values TOP,
297 BOTTOM, and CENTER.
298 spos tells where the scroll bar is to be placed. This may be one
300 of three values:
301 LEFT puts the scroll bar on the left of the scrolling list.
303 RIGHT
305 puts the scroll bar on the right side of the list, and
306 NONE does not add a scroll bar.
308 height and
310 width control the height and width of the widget. If you
311 provide a value of zero for either of the height or the
312 width, the widget will be created with the full width and
313 height of the screen. If you provide a negative value, the
314 widget will be created the full height or width minus the
315 value provided.
316 title
318 is the string which will be displayed at the top of the wid‐
319 get. The title can be more than one line; just provide a
320 carriage return character at the line break.
321 radioList
323 is the list of items to display in the radio list.
324 radioListLength
326 is the number of elements in the given list.
327 choiceCharacter
329 is the character to use to highlight the current selection.
330 highlight
332 specifies the display attribute of the currently selected
333 item.
334 defaultItem
336 is the index in the list of the default selection.
337 box is true if widget should be drawn with a box around it.
339 shadow
341 turns the shadow on or off around this widget.
342 If the widget could not be created then a NULL pointer is
344 returned.
345 positionCDKRadio
347 allows the user to move the widget around the screen via the cur‐
348 sor/keypad keys. See cdk_position (3) for key bindings.
349 setCDKRadio
351 lets the programmer modify certain elements of an existing radio
352 widget.
353 The parameter names correspond to the same parameter names listed
355 in the newCDKRadio function.
356 setCDKRadioBackgroundAttrib
358 sets the background attribute of the widget.
359 The parameter attribute is a curses attribute, e.g., A_BOLD.
361 setCDKRadioBackgroundColor
363 sets the background color of the widget.
364 The parameter color is in the format of the Cdk format strings.
366 See cdk_display (3).
368 setCDKRadioBox
370 sets whether the widget will be drawn with a box around it.
371 setCDKRadioBoxAttribute
373 function sets the attribute of the box.
374 setCDKRadioChoiceCharacter
376 sets the character to use to draw the selected element in the
377 list.
378 setCDKRadioCurrentItem
380 sets the current item by its index in the list.
381 setCDKRadioHighlight
383 sets the attribute of the highlight bar.
384 setCDKRadioHorizontalChar
386 sets the horizontal drawing character for the box to the given
387 character.
388 setCDKRadioItems
390 set the radio list items and display the result. The current item
391 is set to the beginning of the list. The previous radio list
392 items stored in the widget are freed.
393 setCDKRadioLLChar
395 sets the lower left hand corner of the widget's box to the given
396 character.
397 setCDKRadioLRChar
399 sets the lower right hand corner of the widget's box to the given
400 character.
401 setCDKRadioLeftBrace
403 sets the character to use to draw the left brace of the selection
404 box.
405 setCDKRadioPostProcess
407 allows the user to have the widget call a function after the key
408 has been 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 post-processing see cdk_process [4m(3).
416 setCDKRadioPreProcess
418 allows the user to have the widget call a function after a key is
419 hit and before the key is applied to the widget.
420 · The parameter function is the callback function.
422 · The parameter data points to data passed to the callback func‐
424 tion.
425 To learn more about pre-processing see cdk_process [4m(3).
427 setCDKRadioRightBrace
429 sets the character to use to draw the right brace of the selection
430 box.
431 setCDKRadioSelectedItem
433 sets the selected item.
434 setCDKRadioULChar
436 function sets the upper left hand corner of the widget's box to
437 the given character.
438 setCDKRadioURChar
440 function sets the upper right hand corner of the widget's box to
441 the given character.
442 setCDKRadioVerticalChar
444 function sets the vertical drawing character for the box to the
445 given character.
446
448 When the widget is activated there are several default key bindings
449 which will help the user enter or manipulate the information quickly.
450 The following table outlines the keys and their actions for this wid‐
451 get.
452 ┌─────────────────────────────────────────────────────────────┐
454 │Key Action │
455 ├─────────────────────────────────────────────────────────────┤
456 │Left Arrow Shifts the whole list left one character. │
457 │Right Arrow Shifts the whole list right one character. │
458 │Up Arrow Selects the next item up in the list. │
459 │Down Arrow Selects the next item down in the list. │
460 ├─────────────────────────────────────────────────────────────┤
461 │Prev Page │
462 │Ctrl-B Scroll one page backward. │
463 ├─────────────────────────────────────────────────────────────┤
464 │Next Page │
465 │Ctrl-F Scroll one page forward. │
466 ├─────────────────────────────────────────────────────────────┤
467 │1 │
468 │< │
469 │g │
470 │Home Move to the first element in the list. │
471 ├─────────────────────────────────────────────────────────────┤
472 │> │
473 │G │
474 │End Move to the last element in the list. │
475 ├─────────────────────────────────────────────────────────────┤
476 │$ Shifts the whole list to the far right. │
477 │| Shifts the whole list to the far left. │
478 ├─────────────────────────────────────────────────────────────┤
479 │Space Selects or deselects the current choice. │
480 │Return Exits the widget and returns the index of │
481 │ the selected item. This also sets the │
482 │ widget data exitType to vNORMAL. │
483 │Tab Exit the widget and return the index of │
484 │ the selected item. Set the widget data │
485 │ exitType to vNORMAL. │
486 │Escape Exit the widget and return -1. Set the │
487 │ widget data exitType to vESCAPE_HIT. │
488 │Ctrl-L Refreshes the screen. │
489 ├─────────────────────────────────────────────────────────────┤
490 └─────────────────────────────────────────────────────────────┘
492 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
493 cdk_radio(3)