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.  The parameter radio is a pointer to a non-NULL radio wid‐
175            get.  If the actions parameter is passed with  a  non-NULL  value,
176            the  characters in the array will be injected into the widget.  To
177            activate the widget interactively  pass  in  a  NULL  pointer  for
178            actions.   If  the character entered into this widget is RETURN or
179            TAB then this function will return a value from 0 to the number of
180            items  -1,  representing  the item selected.  It will also set the
181            widget data exitType to vNORMAL.  If the  character  entered  into
182            this  widget  was ESCAPE then the widget will return a value of -1
183            and the widget data exitType will be set to vESCAPE_HIT.
184
185       destroyCDKRadio
186            removes the widget from the screen and  frees  memory  the  object
187            used.
188
189       drawCDKRadio
190            draws  the  radio  widget  on the screen.  If the box parameter is
191            true, the widget is drawn with a box.
192
193       eraseCDKRadio
194            removes the widget from the screen.  This  does  NOT  destroy  the
195            widget.
196
197       getCDKRadioBox
198            returns true if the widget will be drawn with a box around it.
199
200       getCDKRadioChoiceCharacter
201            returns  the  character being used to draw the selected element in
202            the list.
203
204       getCDKRadioCurrentItem
205            returns the index of the current item.
206
207       getCDKRadioHighlight
208            returns the attribute of the highlight bar.
209
210       getCDKRadioItems
211            copies the radio box items into the caller's list, which  must  be
212            large enough since this function does not allocate it.  It returns
213            the list size.
214
215       getCDKRadioLeftBrace
216            returns the character being used to draw the  left  brace  of  the
217            selection box.
218
219       getCDKRadioRightBrace
220            returns  the  character  being used to draw the right brace of the
221            selection box.
222
223       getCDKRadioSelectedItem,
224            returns the selected item of the widget.
225
226       injectCDKRadio
227            function injects a single character into the widget.  The  parame‐
228            ter  radio is a pointer to a non-NULL radio widget.  The parameter
229            character is the character to inject into the widget.  The  return
230            value  and  side-effect  (setting the widget data exitType) depend
231            upon the injected character:
232
233            RETURN or TAB
234                   the function returns a value ranging from zero to one  less
235                   than  the number of items, representing the items selected.
236                   The widget data exitType is set to vNORMAL.
237
238            ESCAPE the function returns -1.  The widget data exitType  is  set
239                   to vESCAPE_HIT.
240
241            Otherwise
242                   unless  modified  by  preprocessing,  postprocessing or key
243                   bindings, the function returns -1.  The widget  data  exit‐
244                   Type is set to vEARLY_EXIT.
245
246       moveCDKRadio
247            moves the given widget to the given position.  The parameters xpos
248            and ypos are the new position of the widget.  The  parameter  xpos
249            may  be  an  integer or one of the pre-defined values TOP, BOTTOM,
250            and CENTER.  The parameter ypos may be an integer or  one  of  the
251            pre-defined  values  LEFT, RIGHT, and CENTER.  The parameter rela‐
252            tive states whether the xpos/ypos pair is a relative  move  or  an
253            absolute move.  For example, if xpos = 1 and ypos = 2 and relative
254            = TRUE, then the widget would move one row down  and  two  columns
255            right.   If  the value of relative was FALSE then the widget would
256            move to the position (1,2).  Do not use the  values  TOP,  BOTTOM,
257            LEFT,  RIGHT,  or  CENTER when relative = TRUE.  (weird things may
258            happen).  The final parameter refresh is  a  boolean  value  which
259            states whether the widget will get refreshed after the move.
260
261       newCDKRadio
262            creates a radio widget and returns a pointer to it.  Parameters:
263
264            screen
265                 is the screen you wish this widget to be placed in.
266
267            xpos controls  the  placement  of  the object along the horizontal
268                 axis.  It may be an integer or one of the pre-defined  values
269                 LEFT, RIGHT, and CENTER.
270
271            ypos controls the placement of the object along the vertical axis.
272                 It may be an integer or one of the  pre-defined  values  TOP,
273                 BOTTOM, and CENTER.
274
275            spos tells  where the scroll bar is to be placed.  This may be one
276                 of three values:
277
278                 LEFT puts the scroll bar on the left of the scrolling list.
279
280                 RIGHT
281                      puts the scroll bar on the right side of the list, and
282
283                 NONE does not add a scroll bar.
284
285            height and
286                 width control the height and width of  the  widget.   If  you
287                 provide  a  value  of  zero  for  either of the height or the
288                 width, the widget will be created with  the  full  width  and
289                 height  of  the screen.  If you provide a negative value, the
290                 widget will be created the full height  or  width  minus  the
291                 value provided.
292
293            title
294                 is  the string which will be displayed at the top of the wid‐
295                 get.  The title can be more than one  line;  just  provide  a
296                 carriage return character at the line break.
297
298            radioList
299                 is the list of items to display in the radio list.
300
301            radioListLength
302                 is the number of elements in the given list.
303
304            choiceCharacter
305                 is the character to use to highlight the current selection.
306
307            highlight
308                 specifies  the  display  attribute  of the currently selected
309                 item.
310
311            defaultItem
312                 is the index in the list of the default selection.
313
314            box  is true if widget should be drawn with a box around it.
315
316            shadow
317                 turns the shadow on or off around this widget.
318
319            If the widget  could  not  be  created  then  a  NULL  pointer  is
320            returned.
321
322       positionCDKRadio
323            allows  the user to move the widget around the screen via the cur‐
324            sor/keypad keys.  See cdk_position (3) for key bindings.
325
326       setCDKRadio
327            lets the programmer modify certain elements of an  existing  radio
328            widget.   The  parameter  names  correspond  to the same parameter
329            names listed in the newCDKRadio function.
330
331       setCDKRadioBackgroundAttrib
332            sets the  background  attribute  of  the  widget.   The  parameter
333            attribute is a curses attribute, e.g., A_BOLD.
334
335       setCDKRadioBackgroundColor
336            sets  the  background color of the widget.  The parameter color is
337            in the format of the Cdk format strings.  See cdk_display (3).
338
339       setCDKRadioBox
340            sets whether the widget will be drawn with a box around it.
341
342       setCDKRadioBoxAttribute
343            function sets the attribute of the box.
344
345       setCDKRadioChoiceCharacter
346            sets the character to use to draw  the  selected  element  in  the
347            list.
348
349       setCDKRadioCurrentItem
350            sets the current item by its index in the list.
351
352       setCDKRadioHighlight
353            sets the attribute of the highlight bar.
354
355       setCDKRadioHorizontalChar
356            sets  the  horizontal  drawing  character for the box to the given
357            character.
358
359       setCDKRadioItems
360            set the radio list items and display the result.  The current item
361            is set to the beginning of the list.
362
363       setCDKRadioLLChar
364            sets  the  lower left hand corner of the widget's box to the given
365            character.
366
367       setCDKRadioLRChar
368            sets the lower right hand corner of the widget's box to the  given
369            character.
370
371       setCDKRadioLeftBrace
372            sets  the character to use to draw the left brace of the selection
373            box.
374
375       setCDKRadioPostProcess
376            allows the user to have the widget call a function after  the  key
377            has  been  applied  to  the widget.  The parameter function is the
378            callback function.  The parameter data points to  data  passed  to
379            the  callback  function.   To learn more about post-processing see
380            cdk_process (3).
381
382       setCDKRadioPreProcess
383            allows the user to have the widget call a function after a key  is
384            hit  and  before  the key is applied to the widget.  The parameter
385            function is the callback function.  The parameter data  points  to
386            data  passed  to  the callback function.  To learn more about pre-
387            processing see cdk_process (3).
388
389       setCDKRadioRightBrace
390            sets the character to use to draw the right brace of the selection
391            box.
392
393       setCDKRadioSelectedItem
394            sets the selected item.
395
396       setCDKRadioULChar
397            function  sets  the  upper left hand corner of the widget's box to
398            the given character.
399
400       setCDKRadioURChar
401            function sets the upper right hand corner of the widget's  box  to
402            the given character.
403
404       setCDKRadioVerticalChar
405            function  sets  the  vertical drawing character for the box to the
406            given character.
407

KEY BINDINGS

409       When the widget is activated there are  several  default  key  bindings
410       which  will  help the user enter or manipulate the information quickly.
411       The following table outlines the keys and their actions for  this  wid‐
412       get.
413
414           ┌─────────────────────────────────────────────────────────────┐
415Key               Action                                     
416           ├─────────────────────────────────────────────────────────────┤
417           │Left Arrow        Shifts the whole list left one character.  │
418           │Right Arrow       Shifts the whole list right one character. │
419           │Up Arrow          Selects the next item up in the list.      │
420           │Down Arrow        Selects the next item down in the list.    │
421           ├─────────────────────────────────────────────────────────────┤
422           │Prev Page                                                    │
423           │Ctrl-B            Scroll one page backward.                  │
424           ├─────────────────────────────────────────────────────────────┤
425           │Next Page                                                    │
426           │Ctrl-F            Scroll one page forward.                   │
427           ├─────────────────────────────────────────────────────────────┤
428           │1                                                            │
429           │<                                                            │
430           │g                                                            │
431           │Home              Move to the first element in the list.     │
432           ├─────────────────────────────────────────────────────────────┤
433           │>                                                            │
434           │G                                                            │
435           │End               Move to the last element in the list.      │
436           ├─────────────────────────────────────────────────────────────┤
437           │$                 Shifts the whole list to the far right.    │
438           │|                 Shifts the whole list to the far left.     │
439           ├─────────────────────────────────────────────────────────────┤
440           │Space             Selects or deselects the current choice.   │
441           │Return            Exits  the widget and returns the index of │
442           │                  the selected item.   This  also  sets  the │
443           │                  widget data exitType to vNORMAL.           │
444           │Tab               Exit  the  widget  and return the index of │
445           │                  the selected item.  Set  the  widget  data │
446exitType to vNORMAL.                       │
447           │Escape            Exit  the  widget  and return -1.  Set the │
448           │                  widget data exitType to vESCAPE_HIT.       │
449           │Ctrl-L            Refreshes the screen.                      │
450           ├─────────────────────────────────────────────────────────────┤
451           └─────────────────────────────────────────────────────────────┘

SEE ALSO

453       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
454
455
456
457                                                                  cdk_radio(3)
Impressum