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

KEY BINDINGS

336       When the widget is activated there are  several  default  key  bindings
337       which  will  help the user enter or manipulate the information quickly.
338       The following table outlines the keys and their actions for  this  wid‐
339       get.
340
341             ┌──────────────────────────────────────────────────────────┐
342Key               Action                                  
343             ├──────────────────────────────────────────────────────────┤
344             │Left Arrow                                                │
345             │Down Arrow                                                │
346             │-                                                         │
347             │p                 Shift the list one column to the left.  │
348             ├──────────────────────────────────────────────────────────┤
349             │Right Arrow                                               │
350             │Up Arrow                                                  │
351             │Space                                                     │
352             │+                                                         │
353             │n                 Shift the list one column to the right. │
354             ├──────────────────────────────────────────────────────────┤
355             │d                                                         │
356             │D                 Display the default item.               │
357             ├──────────────────────────────────────────────────────────┤
358             │0                 Display the first item in the list.     │
359             │$                 Display the last item in the list.      │
360             ├──────────────────────────────────────────────────────────┤
361             │Return            Exit  the  widget and return an integer │
362             │                  representing  the  current   selection. │
363             │                  Also  set  the  widget data exitType to │
364vNORMAL.                                │
365             │Tab               Exit the widget and return  an  integer │
366             │                  representing   the  current  selection. │
367             │                  Also set the widget  data  exitType  to │
368vNORMAL.                                │
369             │Escape            Exit  the  widget  and return -1.  Also │
370             │                  set  the  widget   data   exitType   to │
371vESCAPE_HIT.                            │
372             │Ctrl-L            Refreshes the screen.                   │
373             └──────────────────────────────────────────────────────────┘

SEE ALSO

375       cdk(3),      cdk_binding(3),      cdk_display(3),      cdk_position(3),
376       cdk_process(3), cdk_screen(3)
377
378
379
380                                                               cdk_itemlist(3)
Impressum