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.
186
187            ·   The  parameter  selection is a pointer to a non-NULL selection
188                widget.
189
190            ·   If the actions parameter is passed with a non-NULL value,  the
191                characters in the array will be injected into the widget.
192
193                To  activate  the  widget interactively pass in a NULL pointer
194                for actions.
195
196            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
202       destroyCDKSelection
203            removes the widget from the screen and  frees  memory  the  object
204            used.
205
206       drawCDKSelection
207            draws the selection widget on the screen.  If the box parameter is
208            true, the widget is drawn with a box.
209
210       eraseCDKSelection
211            removes the widget from the screen.  This  does  NOT  destroy  the
212            widget.
213
214       getCDKSelectionBox
215            returns true if the widget will be drawn with a box around it.
216
217       getCDKSelectionChoice
218            returns the selection choice at the given index.
219
220       getCDKSelectionChoices
221            returns an array of the current selection choices for the widget.
222
223       getCDKSelectionCurrent
224            returns the current selection index.
225
226       getCDKSelectionHighlight
227            returns the attribute of the highlight bar.
228
229       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
235       getCDKSelectionMode
236            returns the selection mode at the given index.
237
238       getCDKSelectionModes
239            returns an array of the current modes for the widget.
240
241       getCDKSelectionTitle
242            returns the first line of the title of the selection widget.   The
243            caller must free the returned value.
244
245       injectCDKSelection
246            injects a single character into the widget.
247
248            ·   The  parameter  selection is a pointer to a non-NULL selection
249                widget.
250
251            ·   The parameter character is the character to  inject  into  the
252                widget.
253
254            The  return  value  and side-effect (setting the widget data exit‐
255            Type) depend upon the injected character:
256
257            RETURN or TAB
258                   the function returns 1.  The widget data exitType is set to
259                   vNORMAL.
260
261            ESCAPE the  function  returns  -1.   vESCAPE_HIT.  The widget data
262                   exitType is set to vESCAPE_HIT.
263
264            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
269       moveCDKSelection
270            moves the given widget to the given position.
271
272            ·   The parameters xpos and ypos are the new position of the  wid‐
273                get.
274
275            ·   The parameter xpos may be an integer or one of the pre-defined
276                values TOP, BOTTOM, and CENTER.
277
278            ·   The parameter ypos may be an integer or one of the pre-defined
279                values LEFT, RIGHT, and CENTER.
280
281            ·   The  parameter relative states whether the xpos/ypos pair is a
282                relative move or an absolute move.
283
284                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
289                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
290                relative = TRUE.  (weird things may happen).
291
292            ·   The final parameter refresh is a boolean  value  which  states
293                whether the widget will get refreshed after the move.
294
295       newCDKSelection
296            creates  a  selection widget and returns a pointer to it.  Parame‐
297            ters:
298
299            screen
300                 is the screen you wish this widget to be placed in.
301
302            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
306            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
310            spos is where the scroll bar is to be placed.  It may  be  one  of
311                 three values:
312
313                 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
317                 NONE does not add a scroll bar.
318
319            height and
320
321            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
328            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
333            selectionList
334                 is the list of items to display in the selection list
335
336            selectionListLength
337                 is the number of elements in the given list.
338
339            choiceList
340                 is  the  list  of choices that will be selected when the user
341                 presses the space bar.
342
343            choiceListLength
344                 is the length of this list.
345
346            highlight
347                 specifies the display attribute  of  the  currently  selected
348                 item.
349
350            box  is true if the widget should be drawn with a box around it.
351
352            shadow
353                 turns the shadow on or off around this widget.
354
355            If  the  widget  could  not  be  created  then  a  NULL pointer is
356            returned.
357
358       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
362       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
367       setCDKSelectionBackgroundAttrib
368            sets  the  background  attribute  of  the  widget.   The parameter
369            attribute is a curses attribute, e.g., A_BOLD.
370
371       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
375       setCDKSelectionBox
376            sets whether the widget will be drawn with a box around it.
377
378       setCDKSelectionBoxAttribute
379            sets the attribute of the box.
380
381       setCDKSelectionChoice
382            sets the selection choice value at the given index.
383
384       setCDKSelectionChoices
385            sets the selection choice values of the widget.
386
387       setCDKSelectionCurrent
388            sets the current selection index.
389
390       setCDKSelectionHighlight
391            sets the attribute of the highlight bar.
392
393       setCDKSelectionHorizontalChar
394            sets  the  horizontal  drawing  character for the box to the given
395            character.
396
397       setCDKSelectionItems
398            sets the selection list items.  The previous selection list  items
399            stored in the widget are freed.
400
401       setCDKSelectionLLChar
402            sets  the  lower left hand corner of the widget's box to the given
403            character.
404
405       setCDKSelectionLRChar
406            sets the lower right hand corner of the widget's box to the  given
407            character.
408
409       setCDKSelectionMode
410            sets the selection mode at the given index.
411
412       setCDKSelectionModes
413            sets  the selection mode of the elements of the widget.  There are
414            two acceptable values for the modes:
415
416            0  which allows the user to change  the  selection  value  at  the
417               given index; and
418
419            1  which sets the element to a read-only state.
420
421       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 (3).
427
428       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 (3).
434
435       setCDKSelectionTitle
436            set the selection list's title.
437
438       setCDKSelectionULChar
439            sets  the  upper left hand corner of the widget's box to the given
440            character.
441
442       setCDKSelectionURChar
443            sets the upper right hand corner of the widget's box to the  given
444            character.
445
446       setCDKSelectionVerticalChar
447            sets the vertical drawing character for the box to the given char‐
448            acter.
449

KEY BINDINGS

451       When the widget is activated there are  several  default  key  bindings
452       which help the user enter or manipulate the information quickly:
453
454             ┌─────────────────────────────────────────────────────────┐
455Key               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‐
484MAL.                                   │
485             │Tab               Exit the widget and  return  1.   Also │
486             │                  set  the widget data exitType to vNOR‐
487MAL.                                   │
488             │Escape            Exit the widget and return  -1.   Also │
489             │                  set   the   widget  data  exitType  to │
490vESCAPE_HIT.                           │
491             │Ctrl-L            Refreshes the screen.                  │
492             └─────────────────────────────────────────────────────────┘

SEE ALSO

494       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
495
496
497
498                                                              cdk_selection(3)
Impressum