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. 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 destroyCDKItemlist
161 removes the widget from the screen and frees memory the object
162 used.
163 drawCDKItemlist
165 draws the itemlist widget on the screen. The box option is true
166 if the widget is drawn with a box.
167 drawCDKItemlistField
169 draws the contents of the field.
170 eraseCDKItemlist
172 removes the widget from the screen. This does NOT destroy the
173 widget.
174 getCDKItemlistBox
176 returns true if the widget will be drawn with a box around it.
177 getCDKItemlistCurrentItem
179 returns the index of the currently displayed item in the widget.
180 getCDKItemlistDefaultItem
182 returns the index of the default item in the widget.
183 getCDKItemlistValues
185 returns the list of pointers to the items. The parameter size
186 points to a location which receives the item count.
187 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 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 ESCAPE the function returns -1. The widget data exitType is set
201 to vESCAPE_HIT.
202 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 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 newCDKItemlist
224 creates a pointer to an itemlist widget. Parameters:
225 screen
227 is the screen you wish this widget to be placed in.
228 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 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 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 label
243 is the string to use as the label of the itemlist field.
244 itemList
246 is the list of the strings which will be displayed in the
247 widget.
248 itemCount
250 is the number of elements in the list.
251 defaultItem
253 is the index of the default item for the list.
254 box is true if widget should be drawn with a box around it.
256 shadow
258 turns the shadow on or off around this widget.
259 If the widget could not be created then a NULL pointer is
261 returned.
262 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 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 setCDKItemlistBackgroundAttrib
273 the background color attribute the widget. The parameter
274 attribute is a curses attribute, e.g., A_BOLD.
275 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 setCDKItemlistBox
281 sets whether the widget will be drawn with a box around it.
282 setCDKItemlistBoxAttribute
284 sets the attribute of the box.
285 setCDKItemlistCurrentItem
287 sets the currently displayed item in the widget.
288 setCDKItemlistDefaultItem
290 sets the default item in the widget.
291 setCDKItemlistHorizontalChar
293 sets the horizontal drawing character for the box to the given
294 character.
295 setCDKItemlistLLChar
297 sets the lower left hand corner of the widget's box to the given
298 character.
299 setCDKItemlistLRChar
301 sets the lower right hand corner of the widget's box to the given
302 character.
303 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 [4m(3).
310 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 [4m(3).
317 setCDKItemlistULChar
319 sets the upper left hand corner of the widget's box to the given
320 character.
321 setCDKItemlistURChar
323 sets the upper right hand corner of the widget's box to the given
324 character.
325 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 setCDKItemlistVerticalChar
332 sets the vertical drawing character for the box to the given char‐
333 acter.
334
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 ┌──────────────────────────────────────────────────────────┐
342 │Key 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 │
364 │ vNORMAL. │
365 │Tab Exit the widget and return an integer │
366 │ representing the current selection. │
367 │ Also set the widget data exitType to │
368 │ vNORMAL. │
369 │Escape Exit the widget and return -1. Also │
370 │ set the widget data exitType to │
371 │ vESCAPE_HIT. │
372 │Ctrl-L Refreshes the screen. │
373 └──────────────────────────────────────────────────────────┘
375 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3),
376 cdk_process(3), cdk_screen(3)
377 cdk_itemlist(3)