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

NAME

6       cdk_radio - curses radio list widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       int activateCDKRadio (
14                      CDKRADIO *radio,
15                      chtype *actions);
16
17       void destroyCDKRadio (
18                      CDKRADIO *radio);
19
20       void drawCDKRadio (
21                      CDKRADIO *radio,
22                      boolean box);
23
24       void eraseCDKRadio (
25                      CDKRADIO *radio);
26
27       boolean getCDKRadioBox (
28                      CDKRADIO *radio);
29
30       chtype getCDKRadioChoiceCharacter (
31                      CDKRADIO *radio);
32
33       int getCDKRadioCurrentItem (
34                      CDKRADIO *radio);
35
36       chtype getCDKRadioHighlight (
37                      CDKRADIO *radio);
38
39       int getCDKRadioItems (
40                      CDKRADIO *radio,
41                      char **list);
42
43       chtype getCDKRadioLeftBrace (
44                      CDKRADIO *radio);
45
46       chtype getCDKRadioRightBrace (
47                      CDKRADIO *radio);
48
49       int getCDKRadioSelectedItem (
50                      CDKRADIO *radio);
51
52       int injectCDKRadio (
53                      CDKRADIO *radio,
54                      chtype input);
55
56       void moveCDKRadio (
57                      CDKRADIO *radio,
58                      int xpos,
59                      int ypos,
60                      boolean relative,
61                      boolean refresh);
62
63       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
79       void positionCDKRadio (
80                      CDKRADIO *radio);
81
82       void setCDKRadio (
83                      CDKRADIO *radio,
84                      chtype highlight,
85                      chtype choiceCharacter,
86                      boolean box);
87
88       void setCDKRadioBackgroundAttrib (
89                      CDKRADIO *radio,
90                      chtype attribute);
91
92       void setCDKRadioBackgroundColor (
93                      CDKRADIO *radio,
94                      const char * color);
95
96       void setCDKRadioBox (
97                      CDKRADIO *radio,
98                      boolean box);
99
100       void setCDKRadioBoxAttribute (
101                      CDKRADIO *radio,
102                      chtype character);
103
104       void setCDKRadioChoiceCharacter (
105                      CDKRADIO *radio,
106                      chtype character);
107
108       void setCDKRadioCurrentItem (
109                      CDKRADIO *radio,
110                      intindex);
111
112       void setCDKRadioHighlight (
113                      CDKRADIO *radio,
114                      chtype highlight);
115
116       void setCDKRadioHorizontalChar (
117                      CDKRADIO *radio,
118                      chtype character);
119
120       void setCDKRadioItems (
121                      CDKRADIO *radio,
122                      CDK_CONST char **list,
123                      int listSize);
124
125       void setCDKRadioLLChar (
126                      CDKRADIO *radio,
127                      chtype character);
128
129       void setCDKRadioLRChar (
130                      CDKRADIO *radio,
131                      chtype character);
132
133       void setCDKRadioLeftBrace (
134                      CDKRADIO *radio,
135                      chtype character);
136
137       void setCDKRadioPostProcess (
138                      CDKRADIO *radio,
139                      PROCESSFN callback,
140                      void * data);
141
142       void setCDKRadioPreProcess (
143                      CDKRADIO *radio,
144                      PROCESSFN callback,
145                      void * data);
146
147       void setCDKRadioRightBrace (
148                      CDKRADIO *radio,
149                      chtype character);
150
151       void setCDKRadioSelectedItem (
152                      CDKRADIO *radio,
153                      int item);
154
155       void setCDKRadioULChar (
156                      CDKRADIO *radio,
157                      chtype character);
158
159       void setCDKRadioURChar (
160                      CDKRADIO *radio,
161                      chtype character);
162
163       void setCDKRadioVerticalChar (
164                      CDKRADIO *radio,
165                      chtype character);
166

DESCRIPTION

168       The Cdk radio widget creates a radio list.  The following are functions
169       which create or manipulate the Cdk radio box widget.
170

AVAILABLE FUNCTIONS

172       activateCDKRadio
173            activates the radio widget and lets the  user  interact  with  the
174            widget.
175
176            ·   The parameter radio is a pointer to a non-NULL radio widget.
177
178            ·   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
183            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
188            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
192       destroyCDKRadio
193            removes  the  widget  from  the screen and frees memory the object
194            used.
195
196       drawCDKRadio
197            draws the radio widget on the screen.
198
199            If the box parameter is true, the widget is drawn with a box.
200
201       eraseCDKRadio
202            removes the widget from the screen.  This  does  NOT  destroy  the
203            widget.
204
205       getCDKRadioBox
206            returns true if the widget will be drawn with a box around it.
207
208       getCDKRadioChoiceCharacter
209            returns  the  character being used to draw the selected element in
210            the list.
211
212       getCDKRadioCurrentItem
213            returns the index of the current item.
214
215       getCDKRadioHighlight
216            returns the attribute of the highlight bar.
217
218       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
224       getCDKRadioLeftBrace
225            returns  the  character  being  used to draw the left brace of the
226            selection box.
227
228       getCDKRadioRightBrace
229            returns the character being used to draw the right  brace  of  the
230            selection box.
231
232       getCDKRadioSelectedItem,
233            returns the selected item of the widget.
234
235       injectCDKRadio
236            function injects a single character into the widget.
237
238            ·   The parameter radio is a pointer to a non-NULL radio widget.
239
240            ·   The  parameter  character  is the character to inject into the
241                widget.
242
243            The return value and side-effect (setting the  widget  data  exit‐
244            Type) depend upon the injected character:
245
246            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
251            ESCAPE the  function  returns -1.  The widget data exitType is set
252                   to vESCAPE_HIT.
253
254            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
259       moveCDKRadio
260            moves the given widget to the given position.
261
262            ·   The parameters xpos and ypos are the new position of the  wid‐
263                get.
264
265                The parameter xpos may be an integer or one of the pre-defined
266                values TOP, BOTTOM, and CENTER.
267
268                The parameter ypos may be an integer or one of the pre-defined
269                values LEFT, RIGHT, and CENTER.
270
271            ·   The  parameter relative states whether the xpos/ypos pair is a
272                relative move or an absolute move.
273
274                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
279                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
280                relative = TRUE.  (weird things may happen).
281
282            ·   The final parameter refresh is a boolean  value  which  states
283                whether the widget will get refreshed after the move.
284
285       newCDKRadio
286            creates a radio widget and returns a pointer to it.  Parameters:
287
288            screen
289                 is the screen you wish this widget to be placed in.
290
291            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
295            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
299            spos tells  where the scroll bar is to be placed.  This may be one
300                 of three values:
301
302                 LEFT puts the scroll bar on the left of the scrolling list.
303
304                 RIGHT
305                      puts the scroll bar on the right side of the list, and
306
307                 NONE does not add a scroll bar.
308
309            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
317            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
322            radioList
323                 is the list of items to display in the radio list.
324
325            radioListLength
326                 is the number of elements in the given list.
327
328            choiceCharacter
329                 is the character to use to highlight the current selection.
330
331            highlight
332                 specifies  the  display  attribute  of the currently selected
333                 item.
334
335            defaultItem
336                 is the index in the list of the default selection.
337
338            box  is true if widget should be drawn with a box around it.
339
340            shadow
341                 turns the shadow on or off around this widget.
342
343            If the widget  could  not  be  created  then  a  NULL  pointer  is
344            returned.
345
346       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
350       setCDKRadio
351            lets the programmer modify certain elements of an  existing  radio
352            widget.
353
354            The  parameter names correspond to the same parameter names listed
355            in the newCDKRadio function.
356
357       setCDKRadioBackgroundAttrib
358            sets the background attribute of the widget.
359
360            The parameter attribute is a curses attribute, e.g., A_BOLD.
361
362       setCDKRadioBackgroundColor
363            sets the background color of the widget.
364
365            The parameter color is in the format of the Cdk format strings.
366
367            See cdk_display (3).
368
369       setCDKRadioBox
370            sets whether the widget will be drawn with a box around it.
371
372       setCDKRadioBoxAttribute
373            function sets the attribute of the box.
374
375       setCDKRadioChoiceCharacter
376            sets the character to use to draw  the  selected  element  in  the
377            list.
378
379       setCDKRadioCurrentItem
380            sets the current item by its index in the list.
381
382       setCDKRadioHighlight
383            sets the attribute of the highlight bar.
384
385       setCDKRadioHorizontalChar
386            sets  the  horizontal  drawing  character for the box to the given
387            character.
388
389       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
394       setCDKRadioLLChar
395            sets the lower left hand corner of the widget's box to  the  given
396            character.
397
398       setCDKRadioLRChar
399            sets  the lower right hand corner of the widget's box to the given
400            character.
401
402       setCDKRadioLeftBrace
403            sets the character to use to draw the left brace of the  selection
404            box.
405
406       setCDKRadioPostProcess
407            allows  the  user to have the widget call a function after the key
408            has been 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 post-processing see cdk_process (3).
416
417       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
421            ·   The parameter function is the callback function.
422
423            ·   The parameter data points to data passed to the callback func‐
424                tion.
425
426            To learn more about pre-processing see cdk_process (3).
427
428       setCDKRadioRightBrace
429            sets the character to use to draw the right brace of the selection
430            box.
431
432       setCDKRadioSelectedItem
433            sets the selected item.
434
435       setCDKRadioULChar
436            function sets the upper left hand corner of the  widget's  box  to
437            the given character.
438
439       setCDKRadioURChar
440            function  sets  the upper right hand corner of the widget's box to
441            the given character.
442
443       setCDKRadioVerticalChar
444            function sets the vertical drawing character for the  box  to  the
445            given character.
446

KEY BINDINGS

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
453           ┌─────────────────────────────────────────────────────────────┐
454Key               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 │
485exitType 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           └─────────────────────────────────────────────────────────────┘

SEE ALSO

492       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
493
494
495
496                                                                  cdk_radio(3)
Impressum