1cdk_itemlist(3) Library Functions Manual cdk_itemlist(3)
2
6 cdk_itemlist - curses itemlist widget.
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 int activateCDKItemlist (
14 CDKITEMLIST *itemlist,
15 chtype *actions);
16 void destroyCDKItemlist (
18 CDKITEMLIST *itemlist);
19 void drawCDKItemlist (
21 CDKITEMLIST *itemlist,
22 boolean box);
23 void drawCDKItemlistField (
25 CDKITEMLIST *itemlist,
26 boolean highlight);
27 void eraseCDKItemlist (
29 CDKITEMLIST *itemlist);
30 boolean getCDKItemlistBox (
32 CDKITEMLIST *itemlist);
33 int getCDKItemlistCurrentItem (
35 CDKITEMLIST *itemlist);
36 int getCDKItemlistDefaultItem (
38 CDKITEMLIST *itemlist);
39 chtype **getCDKItemlistValues (
41 CDKITEMLIST *itemlist,
42 int *listSize);
43 int injectCDKItemlist (
45 CDKITEMLIST *itemlist,
46 chtype input);
47 void moveCDKItemlist (
49 CDKITEMLIST *itemlist,
50 int xpos,
51 int ypos,
52 boolean relative,
53 boolean refresh);
54 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 void positionCDKItemlist (
68 CDKITEMLIST *itemlist);
69 void setCDKItemlist (
71 CDKITEMLIST *itemlist,
72 CDK_CONST char **itemList,
73 int itemCount,
74 int currentSelection,
75 boolean box);
76 void setCDKItemlistBackgroundAttrib (
78 CDKITEMLIST *itemlist,
79 chtypeattribute);
80 void setCDKItemlistBackgroundColor (
82 CDKITEMLIST *itemlist,
83 const char *color);
84 void setCDKItemlistBox (
86 CDKITEMLIST *itemlist,
87 boolean box);
88 void setCDKItemlistBoxAttribute (
90 CDKITEMLIST *itemlist,
91 chtype character);
92 void setCDKItemlistCurrentItem (
94 CDKITEMLIST *itemlist,
95 int currentItem);
96 void setCDKItemlistDefaultItem (
98 CDKITEMLIST *itemlist,
99 int defaultItem);
100 void setCDKItemlistHorizontalChar (
102 CDKITEMLIST *itemlist,
103 chtype character);
104 void setCDKItemlistLLChar (
106 CDKITEMLIST *itemlist,
107 chtype character);
108 void setCDKItemlistLRChar (
110 CDKITEMLIST *itemlist,
111 chtype character);
112 void setCDKItemlistPostProcess (
114 CDKITEMLIST *itemlist,
115 PROCESSFN callback,
116 void *data);
117 void setCDKItemlistPreProcess (
119 CDKITEMLIST *itemlist,
120 PROCESSFN callback,
121 void *data);
122 void setCDKItemlistULChar (
124 CDKITEMLIST *itemlist,
125 chtype character);
126 void setCDKItemlistURChar (
128 CDKITEMLIST *itemlist,
129 chtype character);
130 void setCDKItemlistValues (
132 CDKITEMLIST *itemlist,
133 CDK_CONST char **itemList,
134 int itemCount);
135 void setCDKItemlistVerticalChar (
137 CDKITEMLIST *itemlist,
138 chtype character);
139
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
147 activateCDKItemlist
148 activates the itemlist widget and lets the user interact with the
149 widget.
150 · The parameter itemlist is a pointer to a non-NULL itemlist
152 widget.
153 · If the actions parameter is passed with a non-NULL value, the
155 characters in the array will be injected into the widget.
156 To activate the widget interactively pass in a NULL pointer
158 for actions.
159 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 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 destroyCDKItemlist
170 removes the widget from the screen and frees memory the object
171 used.
172 drawCDKItemlist
174 draws the itemlist widget on the screen. The box option is true
175 if the widget is drawn with a box.
176 drawCDKItemlistField
178 draws the contents of the field.
179 eraseCDKItemlist
181 removes the widget from the screen. This does NOT destroy the
182 widget.
183 getCDKItemlistBox
185 returns true if the widget will be drawn with a box around it.
186 getCDKItemlistCurrentItem
188 returns the index of the currently displayed item in the widget.
189 getCDKItemlistDefaultItem
191 returns the index of the default item in the widget.
192 getCDKItemlistValues
194 returns the list of pointers to the items. The parameter size
195 points to a location which receives the item count.
196 injectCDKItemlist
198 injects a single character into the widget.
199 · The parameter itemlist is a pointer to a non-NULL itemlist
201 widget.
202 · 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 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 ESCAPE the function returns -1. The widget data exitType is
214 set to vESCAPE_HIT.
215 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 moveCDKItemlist
222 moves the given widget to the given position.
223 · The parameters xpos and ypos are the new position of the wid‐
225 get.
226 · The parameter xpos may be an integer or one of the pre-defined
228 values TOP, BOTTOM, and CENTER.
229 · The parameter ypos may be an integer or one of the pre-defined
231 values LEFT, RIGHT, and CENTER.
232 · The parameter relative states whether the xpos/ypos pair is a
234 relative move or an absolute move.
235 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 Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
242 relative = TRUE. (weird things may happen).
243 · The final parameter refresh is a boolean value which states
245 whether the widget will get refreshed after the move.
246 newCDKItemlist
248 creates a pointer to an itemlist widget. Parameters:
249 screen
251 is the screen you wish this widget to be placed in.
252 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 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 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 label
267 is the string to use as the label of the itemlist field.
268 itemList
270 is the list of the strings which will be displayed in the
271 widget.
272 itemCount
274 is the number of elements in the list.
275 defaultItem
277 is the index of the default item for the list.
278 box is true if widget should be drawn with a box around it.
280 shadow
282 turns the shadow on or off around this widget.
283 If the widget could not be created then a NULL pointer is
285 returned.
286 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 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 setCDKItemlistBackgroundAttrib
297 the background color attribute the widget. The parameter
298 attribute is a curses attribute, e.g., A_BOLD.
299 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 setCDKItemlistBox
305 sets whether the widget will be drawn with a box around it.
306 setCDKItemlistBoxAttribute
308 sets the attribute of the box.
309 setCDKItemlistCurrentItem
311 sets the currently displayed item in the widget.
312 setCDKItemlistDefaultItem
314 sets the default item in the widget.
315 setCDKItemlistHorizontalChar
317 sets the horizontal drawing character for the box to the given
318 character.
319 setCDKItemlistLLChar
321 sets the lower left hand corner of the widget's box to the given
322 character.
323 setCDKItemlistLRChar
325 sets the lower right hand corner of the widget's box to the given
326 character.
327 setCDKItemlistPostProcess
329 allows the user to have the widget call a function after the key
330 has been applied to the widget.
331 · The parameter function is the callback function.
333 · The parameter data points to data passed to the callback func‐
335 tion.
336 To learn more about post-processing see cdk_process [4m(3).
338 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 · The parameter function is the callback function.
344 · The parameter data points to data passed to the callback func‐
346 tion.
347 To learn more about pre-processing see cdk_process [4m(3).
349 setCDKItemlistULChar
351 sets the upper left hand corner of the widget's box to the given
352 character.
353 setCDKItemlistURChar
355 sets the upper right hand corner of the widget's box to the given
356 character.
357 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 setCDKItemlistVerticalChar
364 sets the vertical drawing character for the box to the given char‐
365 acter.
366
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 ┌──────────────────────────────────────────────────────────┐
374 │Key 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 │
396 │ vNORMAL. │
397 │Tab Exit the widget and return an integer │
398 │ representing the current selection. │
399 │ Also set the widget data exitType to │
400 │ vNORMAL. │
401 │Escape Exit the widget and return -1. Also │
402 │ set the widget data exitType to │
403 │ vESCAPE_HIT. │
404 │Ctrl-L Refreshes the screen. │
405 └──────────────────────────────────────────────────────────┘
407 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3),
408 cdk_process(3), cdk_screen(3)
409 cdk_itemlist(3)