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

NAME

6       cdk_selection - curses selection list widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       int activateCDKSelection (
14                      CDKSELECTION *selection,
15                      chtype * actions);
16
17       void destroyCDKSelection (
18                      CDKSELECTION *selection);
19
20       void drawCDKSelection (
21                      CDKSELECTION *selection,
22                      boolean box);
23
24       void eraseCDKSelection (
25                      CDKSELECTION *selection);
26
27       boolean getCDKSelectionBox (
28                      CDKSELECTION *selection);
29
30       int getCDKSelectionChoice (
31                      CDKSELECTION *selection,
32                      int index);
33
34       int *getCDKSelectionChoices (
35                      CDKSELECTION *selection);
36
37       int getCDKSelectionCurrent (
38                      CDKSELECTION *selection);
39
40       chtype getCDKSelectionHighlight (
41                      CDKSELECTION *selection);
42
43       int getCDKSelectionItems (
44                      CDKSELECTION *selection,
45                      char **list);
46
47       int getCDKSelectionMode (
48                      CDKSELECTION *selection,
49                      int index);
50
51       int *getCDKSelectionModes (
52                      CDKSELECTION *selection);
53
54       char *getCDKSelectionTitle (
55                      CDKSELECTION *selection);
56
57       int injectCDKSelection (
58                      CDKSELECTION *selection,
59                      chtype input);
60
61       void moveCDKSelection (
62                      CDKSELECTION *selection,
63                      int xpos,
64                      int ypos,
65                      boolean relative,
66                      boolean refresh);
67
68       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
84       void positionCDKSelection (
85                      CDKSELECTION *selection);
86
87       void setCDKSelection (
88                      CDKSELECTION *selection,
89                      chtype highlight,
90                      int *defChoices,
91                      boolean box);
92
93       void setCDKSelectionBackgroundAttrib (
94                      CDKSELECTION *selection,
95                      chtype attribute);
96
97       void setCDKSelectionBackgroundColor (
98                      CDKSELECTION *selection,
99                      const char * color);
100
101       void setCDKSelectionBox (
102                      CDKSELECTION *selection,
103                      boolean boxWidget);
104
105       void setCDKSelectionBoxAttribute (
106                      CDKSELECTION *selection,
107                      chtype character);
108
109       void setCDKSelectionChoice (
110                      CDKSELECTION *selection,
111                      int index,
112                      int choice);
113
114       void setCDKSelectionChoices (
115                      CDKSELECTION *selection,
116                      int *choices);
117
118       void setCDKSelectionCurrent (
119                      CDKSELECTION *selection,
120                      intindex);
121
122       void setCDKSelectionHighlight (
123                      CDKSELECTION *selection,
124                      chtype highlight);
125
126       void setCDKSelectionHorizontalChar (
127                      CDKSELECTION *selection,
128                      chtype character);
129
130       void setCDKSelectionItems (
131                      CDKSELECTION *selection,
132                      CDK_CONST char **list,
133                      int listSize);
134
135       void setCDKSelectionLLChar (
136                      CDKSELECTION *selection,
137                      chtype character);
138
139       void setCDKSelectionLRChar (
140                      CDKSELECTION *selection,
141                      chtype character);
142
143       void setCDKSelectionMode (
144                      CDKSELECTION *selection,
145                      int index,
146                      int mode);
147
148       void setCDKSelectionModes (
149                      CDKSELECTION *selection,
150                      int *modes);
151
152       void setCDKSelectionPostProcess (
153                      CDKSELECTION *selection,
154                      PROCESSFN callback,
155                      void * data);
156
157       void setCDKSelectionPreProcess (
158                      CDKSELECTION *selection,
159                      PROCESSFN callback,
160                      void * data);
161
162       void setCDKSelectionTitle (
163                      CDKSELECTION *selection,
164                      const char *title);
165
166       void setCDKSelectionULChar (
167                      CDKSELECTION *selection,
168                      chtype character);
169
170       void setCDKSelectionURChar (
171                      CDKSELECTION *selection,
172                      chtype character);
173
174       void setCDKSelectionVerticalChar (
175                      CDKSELECTION *selection,
176                      chtype character);
177

DESCRIPTION

179       The Cdk selection widget creates a selection list.  The following func‐
180       tions create or manipulate the Cdk selection list widget.
181

AVAILABLE FUNCTIONS

183       activateCDKSelection
184            activates the selection widget and lets the user interact with the
185            widget.  The parameter selection is a pointer to a non-NULL selec‐
186            tion widget.  If the actions parameter is passed with  a  non-NULL
187            value,  the characters in the array will be injected into the wid‐
188            get.  To activate the widget interactively pass in a NULL  pointer
189            for  actions.  If the character entered into this widget is RETURN
190            or TAB then this function will return 1.  Itm will  also  set  the
191            widget  data  exitType  to vNORMAL.  If the character entered into
192            this widget was ESCAPE then the widget will return a value  of  -1
193            and the widget data exitType will be set to vESCAPE_HIT.
194
195       destroyCDKSelection
196            removes  the  widget  from  the screen and frees memory the object
197            used.
198
199       drawCDKSelection
200            draws the selection widget on the screen.  If the box parameter is
201            true, the widget is drawn with a box.
202
203       eraseCDKSelection
204            removes  the  widget  from  the screen.  This does NOT destroy the
205            widget.
206
207       getCDKSelectionBox
208            returns true if the widget will be drawn with a box around it.
209
210       getCDKSelectionChoice
211            returns the selection choice at the given index.
212
213       getCDKSelectionChoices
214            returns an array of the current selection choices for the widget.
215
216       getCDKSelectionCurrent
217            returns the current selection index.
218
219       getCDKSelectionHighlight
220            returns the attribute of the highlight bar.
221
222       getCDKSelectionItems
223            copies the  selection-list  items  into  the  caller's  array  and
224            returns the number of items in the list.
225
226       getCDKSelectionMode
227            returns the selection mode at the given index.
228
229       getCDKSelectionModes
230            returns an array of the current modes for the widget.
231
232       getCDKSelectionTitle
233            returns  the first line of the title of the selection widget.  The
234            caller must free the returned value.
235
236       injectCDKSelection
237            injects a single character into the widget.  The parameter  selec‐
238            tion  is  a pointer to a non-NULL selection widget.  The parameter
239            character is the character to inject into the widget.  The  return
240            value  and  side-effect  (setting the widget data exitType) depend
241            upon the injected character:
242
243            RETURN or TAB
244                   the function returns 1.  The widget data exitType is set to
245                   vNORMAL.
246
247            ESCAPE the  function  returns  -1.   vESCAPE_HIT.  The widget data
248                   exitType is set to vESCAPE_HIT.
249
250            Otherwise
251                   unless modified by  preprocessing,  postprocessing  or  key
252                   bindings,  the  function returns -1.  The widget data exit‐
253                   Type is set to vEARLY_EXIT.
254
255       moveCDKSelection
256            moves the given widget to the given position.  The parameters xpos
257            and  ypos  are the new position of the widget.  The parameter xpos
258            may be an integer or one of the pre-defined  values  TOP,  BOTTOM,
259            and  CENTER.   The  parameter ypos may be an integer or one of the
260            pre-defined values LEFT, RIGHT, and CENTER.  The  parameter  rela‐
261            tive  states  whether  the xpos/ypos pair is a relative move or an
262            absolute move.  For example, if xpos = 1 and ypos = 2 and relative
263            =  TRUE,  then  the widget would move one row down and two columns
264            right.  If the value of relative was FALSE then the  widget  would
265            move  to  the  position (1,2).  Do not use the values TOP, BOTTOM,
266            LEFT, RIGHT, or CENTER when relative = TRUE.   (weird  things  may
267            happen).   The  final  parameter  refresh is a boolean value which
268            states whether the widget will get refreshed after the move.
269
270       newCDKSelection
271            creates a selection widget and returns a pointer to  it.   Parame‐
272            ters:
273
274            screen
275                 is the screen you wish this widget to be placed in.
276
277            xpos controls  the  placement  of  the object along the horizontal
278                 axis.  It may be an integer or one of the pre-defined  values
279                 LEFT, RIGHT, and CENTER.
280
281            ypos controls the placement of the object along the vertical axis.
282                 It may be an integer or one of the  pre-defined  values  TOP,
283                 BOTTOM, and CENTER.
284
285            spos is  where  the  scroll bar is to be placed.  It may be one of
286                 three values:
287
288                 LEFT puts the scroll bar on the left of the  scrolling  list.
289                      RIGHT puts the scroll bar on the right side of the list,
290                      and
291
292                 NONE does not add a scroll bar.
293
294            height and
295
296            width
297                 control the height and width of the widget.  If you provide a
298                 value of zero for either of the height or the width, the wid‐
299                 get will be created with the full width  and  height  of  the
300                 screen.   If you provide a negative value, the widget will be
301                 created the full height or width minus the value provided.
302
303            title
304                 is the string which to display at the top of the widget.  The
305                 title  can  be  more  than  one line; just provide a carriage
306                 return character at the line break.
307
308            selectionList
309                 is the list of items to display in the selection list
310
311            selectionListLength
312                 is the number of elements in the given list.
313
314            choiceList
315                 is the list of choices that will be selected  when  the  user
316                 presses the space bar.
317
318            choiceListLength
319                 is the length of this list.
320
321            highlight
322                 specifies  the  display  attribute  of the currently selected
323                 item.
324
325            box  is true if the widget should be drawn with a box around it.
326
327            shadow
328                 turns the shadow on or off around this widget.
329
330            If the widget  could  not  be  created  then  a  NULL  pointer  is
331            returned.
332
333       positionCDKSelection
334            allows  the user to move the widget around the screen via the cur‐
335            sor/keypad keys.  See cdk_position (3) for key bindings.
336
337       setCDKSelection
338            lets the programmer modify certain elements of an existing  selec‐
339            tion widget.  The parameter names correspond to the same parameter
340            names listed in the newCDKSelection function.
341
342       setCDKSelectionBackgroundAttrib
343            sets the  background  attribute  of  the  widget.   The  parameter
344            attribute is a curses attribute, e.g., A_BOLD.
345
346       setCDKSelectionBackgroundColor
347            sets  the  background color of the widget.  The parameter color is
348            in the format of the Cdk format strings.  See cdk_display (3).
349
350       setCDKSelectionBox
351            sets whether the widget will be drawn with a box around it.
352
353       setCDKSelectionBoxAttribute
354            sets the attribute of the box.
355
356       setCDKSelectionChoice
357            sets the selection choice value at the given index.
358
359       setCDKSelectionChoices
360            sets the selection choice values of the widget.
361
362       setCDKSelectionCurrent
363            sets the current selection index.
364
365       setCDKSelectionHighlight
366            sets the attribute of the highlight bar.
367
368       setCDKSelectionHorizontalChar
369            sets the horizontal drawing character for the  box  to  the  given
370            character.
371
372       setCDKSelectionItems
373            sets the selection list items.
374
375       setCDKSelectionLLChar
376            sets  the  lower left hand corner of the widget's box to the given
377            character.
378
379       setCDKSelectionLRChar
380            sets the lower right hand corner of the widget's box to the  given
381            character.
382
383       setCDKSelectionMode
384            sets the selection mode at the given index.
385
386       setCDKSelectionModes
387            sets  the selection mode of the elements of the widget.  There are
388            two acceptable values for the modes: 0 which allows  the  user  to
389            change  the  selection  value at the given index; and 1 which sets
390            the element to a read-only state.
391
392       setCDKSelectionPostProcess
393            allows the user to have the widget call a function after  the  key
394            has  been  applied  to  the widget.  The parameter function is the
395            callback function.  The parameter data points to  data  passed  to
396            the  callback  function.   To learn more about post-processing see
397            cdk_process (3).
398
399       setCDKSelectionPreProcess
400            allows the user to have the widget call a function after a key  is
401            hit  and  before  the key is applied to the widget.  The parameter
402            function is the  callback  function.   The  parameter  data  is  a
403            pointer   to   void.   To  learn  more  about  pre-processing  see
404            cdk_process (3).
405
406       setCDKSelectionTitle
407            set the selection list's title.
408
409       setCDKSelectionULChar
410            sets the upper left hand corner of the widget's box to  the  given
411            character.
412
413       setCDKSelectionURChar
414            sets  the upper right hand corner of the widget's box to the given
415            character.
416
417       setCDKSelectionVerticalChar
418            sets the vertical drawing character for the box to the given char‐
419            acter.
420

KEY BINDINGS

422       When  the  widget  is  activated there are several default key bindings
423       which help the user enter or manipulate the information quickly:
424
425             ┌─────────────────────────────────────────────────────────┐
426Key               Action                                 
427             ├─────────────────────────────────────────────────────────┤
428             │Left Arrow        Shift the whole list left one column.  │
429             │Right Arrow       Shift the whole list right one column. │
430             │Up Arrow          Select the previous item in the list.  │
431             │Down Arrow        Select the next item in the list.      │
432             ├─────────────────────────────────────────────────────────┤
433             │Prev Page                                                │
434             │Ctrl-B            Scroll one page backward.              │
435             ├─────────────────────────────────────────────────────────┤
436             │Next Page                                                │
437             │Ctrl-F            Scroll one page forward.               │
438             ├─────────────────────────────────────────────────────────┤
439             │1                                                        │
440             │<                                                        │
441             │g                                                        │
442             │Home              Move to the first element in the list. │
443             ├─────────────────────────────────────────────────────────┤
444             │>                                                        │
445             │G                                                        │
446             │End               Move to the last element in the list.  │
447             ├─────────────────────────────────────────────────────────┤
448             │$                 Shift the whole list to the far right. │
449             │|                 Shift the whole list to the far left.  │
450             ├─────────────────────────────────────────────────────────┤
451             │Space             Cycles to the next choice on the  cur‐ │
452             │                  rent item.                             │
453             │Return            Exit  the  widget  and return 1.  Also │
454             │                  set the widget data exitType to  vNOR‐
455MAL.                                   │
456             │Tab               Exit  the  widget  and return 1.  Also │
457             │                  set the widget data exitType to  vNOR‐
458MAL.                                   │
459             │Escape            Exit  the  widget and return -1.  Also │
460             │                  set  the  widget  data   exitType   to │
461vESCAPE_HIT.                           │
462             │Ctrl-L            Refreshes the screen.                  │
463             └─────────────────────────────────────────────────────────┘

SEE ALSO

465       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
466
467
468
469                                                              cdk_selection(3)
Impressum