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

NAME

6       cdk_itemlist - curses itemlist widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       int activateCDKItemlist (
14                      CDKITEMLIST *itemlist,
15                      chtype *actions);
16
17       void destroyCDKItemlist (
18                      CDKITEMLIST *itemlist);
19
20       void drawCDKItemlist (
21                      CDKITEMLIST *itemlist,
22                      boolean box);
23
24       void drawCDKItemlistField (
25                      CDKITEMLIST *itemlist,
26                      boolean highlight);
27
28       void eraseCDKItemlist (
29                      CDKITEMLIST *itemlist);
30
31       boolean getCDKItemlistBox (
32                      CDKITEMLIST *itemlist);
33
34       int getCDKItemlistCurrentItem (
35                      CDKITEMLIST *itemlist);
36
37       int getCDKItemlistDefaultItem (
38                      CDKITEMLIST *itemlist);
39
40       chtype **getCDKItemlistValues (
41                      CDKITEMLIST *itemlist,
42                      int *listSize);
43
44       int injectCDKItemlist (
45                      CDKITEMLIST *itemlist,
46                      chtype input);
47
48       void moveCDKItemlist (
49                      CDKITEMLIST *itemlist,
50                      int xpos,
51                      int ypos,
52                      boolean relative,
53                      boolean refresh);
54
55       CDKITEMLIST *newCDKItemlist (
56                      CDKSCREEN *cdkscreen,
57                      int xpos,
58                      int ypos,
59                      const char *title,
60                      const char *label,
61                      CDK_CONST char **itemList,
62                      int itemCount,
63                      int defaultItem,
64                      boolean box,
65                      boolean shadow);
66
67       void positionCDKItemlist (
68                      CDKITEMLIST *itemlist);
69
70       void setCDKItemlist (
71                      CDKITEMLIST *itemlist,
72                      CDK_CONST char **itemList,
73                      int itemCount,
74                      int currentSelection,
75                      boolean box);
76
77       void setCDKItemlistBackgroundAttrib (
78                      CDKITEMLIST *itemlist,
79                      chtypeattribute);
80
81       void setCDKItemlistBackgroundColor (
82                      CDKITEMLIST *itemlist,
83                      const char *color);
84
85       void setCDKItemlistBox (
86                      CDKITEMLIST *itemlist,
87                      boolean box);
88
89       void setCDKItemlistBoxAttribute (
90                      CDKITEMLIST *itemlist,
91                      chtype character);
92
93       void setCDKItemlistCurrentItem (
94                      CDKITEMLIST *itemlist,
95                      int currentItem);
96
97       void setCDKItemlistDefaultItem (
98                      CDKITEMLIST *itemlist,
99                      int defaultItem);
100
101       void setCDKItemlistHorizontalChar (
102                      CDKITEMLIST *itemlist,
103                      chtype character);
104
105       void setCDKItemlistLLChar (
106                      CDKITEMLIST *itemlist,
107                      chtype character);
108
109       void setCDKItemlistLRChar (
110                      CDKITEMLIST *itemlist,
111                      chtype character);
112
113       void setCDKItemlistPostProcess (
114                      CDKITEMLIST *itemlist,
115                      PROCESSFN callback,
116                      void *data);
117
118       void setCDKItemlistPreProcess (
119                      CDKITEMLIST *itemlist,
120                      PROCESSFN callback,
121                      void *data);
122
123       void setCDKItemlistULChar (
124                      CDKITEMLIST *itemlist,
125                      chtype character);
126
127       void setCDKItemlistURChar (
128                      CDKITEMLIST *itemlist,
129                      chtype character);
130
131       void setCDKItemlistValues (
132                      CDKITEMLIST *itemlist,
133                      CDK_CONST char **itemList,
134                      int itemCount);
135
136       void setCDKItemlistVerticalChar (
137                      CDKITEMLIST *itemlist,
138                      chtype character);
139

DESCRIPTION

141       The  Cdk itemlist widget creates a widget which allows a user to select
142       from a list of preset character strings such as the days of the week or
143       the  months  of the year.  The following functions create or manipulate
144       the Cdk itemlist widget.
145

AVAILABLE FUNCTIONS

147       activateCDKItemlist
148            activates the itemlist widget and lets the user interact with  the
149            widget.
150
151            ·   The  parameter  itemlist  is  a pointer to a non-NULL itemlist
152                widget.
153
154            ·   If the actions parameter is passed with a non-NULL value,  the
155                characters in the array will be injected into the widget.
156
157                To  activate  the  widget interactively pass in a NULL pointer
158                for actions.
159
160                If the character entered into this widget  is  RETURN  or  TAB
161                then this function will return a value from 0 to the number of
162                buttons -1, representing the button selected.   It  will  also
163                set the widget data exitType to vNORMAL.
164
165                If  the character entered into this widget was ESCAPE then the
166                widget will return a -1 and the widget data exitType  will  be
167                set to vESCAPE_HIT.
168
169       destroyCDKItemlist
170            removes  the  widget  from  the screen and frees memory the object
171            used.
172
173       drawCDKItemlist
174            draws the itemlist widget on the screen.  The box option  is  true
175            if the widget is drawn with a box.
176
177       drawCDKItemlistField
178            draws the contents of the field.
179
180       eraseCDKItemlist
181            removes  the  widget  from  the screen.  This does NOT destroy the
182            widget.
183
184       getCDKItemlistBox
185            returns true if the widget will be drawn with a box around it.
186
187       getCDKItemlistCurrentItem
188            returns the index of the currently displayed item in the widget.
189
190       getCDKItemlistDefaultItem
191            returns the index of the default item in the widget.
192
193       getCDKItemlistValues
194            returns the list of pointers to the  items.   The  parameter  size
195            points to a location which receives the item count.
196
197       injectCDKItemlist
198            injects a single character into the widget.
199
200            ·   The  parameter  itemlist  is  a pointer to a non-NULL itemlist
201                widget.
202
203            ·   The parameter character is the character to  inject  into  the
204                widget.   The return value and side-effect (setting the widget
205                data exitType) depend upon the injected character:
206
207                RETURN or TAB
208                       the function returns a value ranging from zero  to  one
209                       less  than the number of buttons, representing the but‐
210                       ton selected.  The widget data exitType is set to vNOR‐
211                       MAL.
212
213                ESCAPE the  function  returns -1.  The widget data exitType is
214                       set to vESCAPE_HIT.
215
216                Otherwise
217                       unless modified by preprocessing, postprocessing or key
218                       bindings,  the  function  returns  -1.  The widget data
219                       exitType is set to vEARLY_EXIT.
220
221       moveCDKItemlist
222            moves the given widget to the given position.
223
224            ·   The parameters xpos and ypos are the new position of the  wid‐
225                get.
226
227            ·   The parameter xpos may be an integer or one of the pre-defined
228                values TOP, BOTTOM, and CENTER.
229
230            ·   The parameter ypos may be an integer or one of the pre-defined
231                values LEFT, RIGHT, and CENTER.
232
233            ·   The  parameter relative states whether the xpos/ypos pair is a
234                relative move or an absolute move.
235
236                For example, if xpos = 1 and ypos = 2  and  relative  =  TRUE,
237                then the widget would move one row down and two columns right.
238                If the value of relative was FALSE, then the widget would move
239                to the position (1,2).
240
241                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
242                relative = TRUE.  (weird things may happen).
243
244            ·   The final parameter refresh is a boolean  value  which  states
245                whether the widget will get refreshed after the move.
246
247       newCDKItemlist
248            creates a pointer to an itemlist widget.  Parameters:
249
250            screen
251                 is the screen you wish this widget to be placed in.
252
253            xpos controls  the  placement  of  the object along the horizontal
254                 axis.  It may be an integer or one of the pre-defined  values
255                 LEFT, RIGHT, and CENTER.
256
257            ypos controls the placement of the object along the vertical axis.
258                 It may be an integer or one of the  pre-defined  values  TOP,
259                 BOTTOM, and CENTER.
260
261            title
262                 is  the string which will be displayed at the top of the wid‐
263                 get.  The title can be more than one  line;  just  provide  a
264                 carriage return character at the line break.
265
266            label
267                 is the string to use as the label of the itemlist field.
268
269            itemList
270                 is  the  list  of  the strings which will be displayed in the
271                 widget.
272
273            itemCount
274                 is the number of elements in the list.
275
276            defaultItem
277                 is the index of the default item for the list.
278
279            box  is true if widget should be drawn with a box around it.
280
281            shadow
282                 turns the shadow on or off around this widget.
283
284            If the widget  could  not  be  created  then  a  NULL  pointer  is
285            returned.
286
287       positionCDKItemlist
288            allows  the user to move the widget around the screen via the cur‐
289            sor/keypad keys.  See cdk_position (3) for key bindings.
290
291       setCDKItemlist
292            lets the programmer modify certain elements of an  existing  item‐
293            list widget.  The parameter names correspond to the same parameter
294            names listed in the newCDKItemlist function.
295
296       setCDKItemlistBackgroundAttrib
297            the  background  color  attribute  the  widget.    The   parameter
298            attribute is a curses attribute, e.g., A_BOLD.
299
300       setCDKItemlistBackgroundColor
301            sets  the  background color of the widget.  The parameter color is
302            in the format of the Cdk format strings.  See cdk_display (3).
303
304       setCDKItemlistBox
305            sets whether the widget will be drawn with a box around it.
306
307       setCDKItemlistBoxAttribute
308            sets the attribute of the box.
309
310       setCDKItemlistCurrentItem
311            sets the currently displayed item in the widget.
312
313       setCDKItemlistDefaultItem
314            sets the default item in the widget.
315
316       setCDKItemlistHorizontalChar
317            sets the horizontal drawing character for the  box  to  the  given
318            character.
319
320       setCDKItemlistLLChar
321            sets  the  lower left hand corner of the widget's box to the given
322            character.
323
324       setCDKItemlistLRChar
325            sets the lower right hand corner of the widget's box to the  given
326            character.
327
328       setCDKItemlistPostProcess
329            allows  the  user to have the widget call a function after the key
330            has been applied to the widget.
331
332            ·   The parameter function is the callback function.
333
334            ·   The parameter data points to data passed to the callback func‐
335                tion.
336
337                To learn more about post-processing see cdk_process (3).
338
339       setCDKItemlistPreProcess
340            allows  the user to have the widget call a function after a key is
341            hit and before the key is applied to the widget.
342
343            ·   The parameter function is the callback function.
344
345            ·   The parameter data points to data passed to the callback func‐
346                tion.
347
348                To learn more about pre-processing see cdk_process (3).
349
350       setCDKItemlistULChar
351            sets  the  upper left hand corner of the widget's box to the given
352            character.
353
354       setCDKItemlistURChar
355            sets the upper right hand corner of the widget's box to the  given
356            character.
357
358       setCDKItemlistValues
359            sets  the  contents  of  the list from an array of string pointers
360            item whose final index is given by count.  If  defaultItem  is  in
361            the range 0..count, that sets the default item value for the list.
362
363       setCDKItemlistVerticalChar
364            sets the vertical drawing character for the box to the given char‐
365            acter.
366

KEY BINDINGS

368       When the widget is activated there are  several  default  key  bindings
369       which  will  help the user enter or manipulate the information quickly.
370       The following table outlines the keys and their actions for  this  wid‐
371       get.
372
373             ┌──────────────────────────────────────────────────────────┐
374Key               Action                                  
375             ├──────────────────────────────────────────────────────────┤
376             │Left Arrow                                                │
377             │Down Arrow                                                │
378             │-                                                         │
379             │p                 Shift the list one column to the left.  │
380             ├──────────────────────────────────────────────────────────┤
381             │Right Arrow                                               │
382             │Up Arrow                                                  │
383             │Space                                                     │
384             │+                                                         │
385             │n                 Shift the list one column to the right. │
386             ├──────────────────────────────────────────────────────────┤
387             │d                                                         │
388             │D                 Display the default item.               │
389             ├──────────────────────────────────────────────────────────┤
390             │0                 Display the first item in the list.     │
391             │$                 Display the last item in the list.      │
392             ├──────────────────────────────────────────────────────────┤
393             │Return            Exit  the  widget and return an integer │
394             │                  representing  the  current   selection. │
395             │                  Also  set  the  widget data exitType to │
396vNORMAL.                                │
397             │Tab               Exit the widget and return  an  integer │
398             │                  representing   the  current  selection. │
399             │                  Also set the widget  data  exitType  to │
400vNORMAL.                                │
401             │Escape            Exit  the  widget  and return -1.  Also │
402             │                  set  the  widget   data   exitType   to │
403vESCAPE_HIT.                            │
404             │Ctrl-L            Refreshes the screen.                   │
405             └──────────────────────────────────────────────────────────┘

SEE ALSO

407       cdk(3),      cdk_binding(3),      cdk_display(3),      cdk_position(3),
408       cdk_process(3), cdk_screen(3)
409
410
411
412                                                               cdk_itemlist(3)
Impressum