1cdk_scroll(3) Library Functions Manual cdk_scroll(3)
2
6 cdk_scroll - curses scrolling list widget.
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 int activateCDKScroll (
14 CDKSCROLL *scroll,
15 chtype * actions);
16 void addCDKScrollItem (
18 CDKSCROLL *scroll,
19 char *item);
20 void deleteCDKScrollItem (
22 CDKSCROLL *scroll,
23 int position);
24 void destroyCDKScroll (
26 CDKSCROLL *scroll);
27 void drawCDKScroll (
29 CDKSCROLL *scroll,
30 boolean box);
31 void eraseCDKScroll (
33 CDKSCROLL *scroll);
34 boolean getCDKScrollBox (
36 CDKSCROLL *scroll);
37 int getCDKScrollCurrent(
39 CDKSCROLL *scroll);
40 int getCDKScrollCurrentItem (
42 CDKSCROLL *widget);
43 chtype getCDKScrollHighlight (
45 CDKSCROLL *scroll,
46 chtype highlight);
47 int getCDKScrollCurrentTop (
49 CDKSCROLL *widget);
50 int getCDKScrollItems (
52 CDKSCROLL *scroll,
53 char **itemList);
54 int injectCDKScroll (
56 CDKSCROLL *scroll,
57 chtype input);
58 void insertCDKScrollItem (
60 CDKSCROLL *scroll,
61 char *item);
62 void moveCDKScroll (
64 CDKSCROLL *scroll,
65 int xpos,
66 int ypos,
67 boolean relative,
68 boolean refresh);
69 CDKSCROLL *newCDKScroll (
71 CDKSCREEN *cdkscreen,
72 int xpos,
73 int ypos,
74 int spos,
75 int height,
76 int width,
77 char *title,
78 char **itemList,
79 int items,
80 boolean numbers,
81 chtype highlight,
82 boolean box,
83 boolean shadow);
84 void positionCDKScroll (
86 CDKSCROLL *scroll);
87 void setCDKScroll (
89 CDKSCROLL *scroll,
90 char **itemList,
91 int items,
92 boolean numbers,
93 chtype highlight,
94 boolean box);
95 void setCDKScrollBackgroundAttrib (
97 CDKSCROLL *scroll,
98 chtype attribute);
99 void setCDKScrollBackgroundColor (
101 CDKSCROLL *scroll,
102 char * color);
103 void setCDKScrollBox (
105 CDKSCROLL *scroll,
106 boolean box);
107 void setCDKScrollBoxAttribute (
109 CDKSCROLL *scroll,
110 chtype character);
111 void setCDKScrollCurrent(
113 CDKSCROLL *scroll,
114 intitem);
115 void setCDKScrollCurrentItem (
117 CDKSCROLL *widget,
118 intitem);
119 int getCDKScrollCurrentTop (
121 CDKSCROLL *widget);
122 void setCDKScrollHighlight (
124 CDKSCROLL *scroll,
125 chtype highlight);
126 void setCDKScrollHorizontalChar (
128 CDKSCROLL *scroll,
129 chtype character);
130 void setCDKScrollItems (
132 CDKSCROLL *scroll,
133 char **itemList,
134 int listSize,
135 boolean numbers);
136 void setCDKScrollLLChar (
138 CDKSCROLL *scroll,
139 chtype character);
140 void setCDKScrollLRChar (
142 CDKSCROLL *scroll,
143 chtype character);
144 void setCDKScrollPosition (
146 CDKSCROLL *scroll,
147 intitem);
148 void setCDKScrollPostProcess (
150 CDKSCROLL *scroll,
151 PROCESSFN callback,
152 void * data);
153 void setCDKScrollPreProcess (
155 CDKSCROLL *scroll,
156 PROCESSFN callback,
157 void * data);
158 void setCDKScrollULChar (
160 CDKSCROLL *scroll,
161 chtype character);
162 void setCDKScrollURChar (
164 CDKSCROLL *scroll,
165 chtype character);
166 void setCDKScrollVerticalChar (
168 CDKSCROLL *scroll,
169 chtype character);
170
172 The Cdk scroll widget creates a scrolling list. The following are
173 functions which create or manipulate the Cdk scrolling list widget.
174
176 activateCDKScroll
177 activates the scroll widget and lets the user interact with the
178 widget. The parameter scroll points to a non-NULL scroll widget.
179 If the actions parameter is passed with a non-NULL value, the
180 characters in the array will be injected into the widget. To
181 activate the widget interactively pass in a NULL pointer for
182 actions. If the character entered into this widget is RETURN or
183 TAB then this function will return a value from 0 to the number of
184 items-1, representing the item selected. It will also set the
185 widget data exitType to vNORMAL. If the character entered into
186 this widget was ESCAPE then the widget will return a value of -1
187 and the widget data exitType will be set to vESCAPE_HIT.
188 addCDKScrollItem
190 allows the user to add an item into an existing scrolling list.
191 The scroll parameter points to the scrolling list to add the item
192 to. The parameter item is a char * representing the new item to
193 add. The item is always added to the end of the list.
194 deleteCDKScrollItem
196 allows the user to add an item into an existing scrolling list.
197 The scroll parameter points to the scrolling list to add the item
198 to. The parameter f2position is an int which specifies which ele‐
199 ment to remove.
200 destroyCDKScroll
202 removes the widget from the screen and frees memory the object
203 used.
204 drawCDKScroll
206 draws the scroll widget on the screen. If the box option is true,
207 the widget is drawn with a box.
208 eraseCDKScroll
210 removes the widget from the screen. This does NOT destroy the
211 widget.
212 getCDKScrollBox
214 returns true if the widget will be drawn with a box around it.
215 getCDKScrollCurrent
217 returns the current item's index.
218 getCDKScrollCurrentItem
220 returns the current item number in the scroller.
221 getCDKScrollHighlight
223 returns the attribute of the highlight bar.
224 getCDKScrollCurrentTop
226 returns the top line of the scroller, counting from zero.
227 getCDKScrollItems
229 fills the parameter itemList with the contents of the scrolling
230 list. It returns the number of elements in the scrolling list.
231 injectCDKScroll
233 injects a single character into the widget. The parameter scroll
234 points to a non-NULL scroll widget. The parameter character is
235 the character to inject into the widget. The return value and
236 side-effect (setting the widget data exitType) depend upon the
237 injected character:
238 RETURN or TAB
240 the function returns a value ranging from zero to one less
241 than the number of items, representing the item selected.
242 The widget data exitType is set to vNORMAL.
243 ESCAPE the function returns -1. The widget data exitType is set
245 to vESCAPE_HIT.
246 Otherwise
248 unless modified by preprocessing, postprocessing or key
249 bindings, the function returns -1. The widget data exit‐
250 Type is set to vEARLY_EXIT.
251 insertCDKScrollItem
253 allows the user to add an item into an existing scrolling list.
254 The scroll parameter points to the scrolling list to add the item
255 to. The parameter item is a char * representing the new item to
256 add. The item is always added before the current item in the
257 list.
258 moveCDKScroll
260 moves the given widget to the given position. The parameters xpos
261 and ypos are the new position of the widget. The parameter xpos
262 may be an integer or one of the pre-defined values TOP, BOTTOM,
263 and CENTER. The parameter ypos may be an integer or one of the
264 pre-defined values LEFT, RIGHT, and CENTER. The parameter rela‐
265 tive states whether the xpos/ypos pair is a relative move or an
266 absolute move. For example, if xpos = 1 and ypos = 2 and relative
267 = TRUE, then the widget would move one row down and two columns
268 right. If the value of relative was FALSE then the widget would
269 move to the position (1,2). Do not use the values TOP, BOTTOM,
270 LEFT, RIGHT, or CENTER when relative = TRUE. (weird things may
271 happen). The final parameter refresh is a boolean value which
272 states whether the widget will get refreshed after the move.
273 newCDKScroll
275 creates a scroll widget and returns a pointer to it. Parameters:
276 screen
278 parameter is the screen you wish this widget to be placed in.
279 The parameter xpos controls the placement of the object along
280 the horizontal axis. This parameter may be an integer or one
281 of the pre-defined values LEFT, RIGHT, and CENTER.
282 ypos controls the placement of the object along the vertical axis.
284 This parameter may be an integer value or one of the pre-
285 defined values TOP, BOTTOM, and CENTER.
286 spos is where the scroll bar is to be placed. This may be one of
288 three values:
289 LEFT,
291 which puts the scroll bar on the left of the scrolling
292 list.
293 RIGHT
295 which puts the scroll bar on the right side of the list,
296 and
297 NONE which does not add a scroll bar.
299 height and
301 width
303 control the height and width of the widget. If you provide a
304 value of zero for either of the height or the width, the wid‐
305 get will be created with the full width and height of the
306 screen. If you provide a negative value, the widget will be
307 created the full height or width minus the value provided.
308 title
310 is the string which will be displayed at the top of the wid‐
311 get. The title can be more than one line; just provide a
312 carriage return character at the line break.
313 itemList
315 is the list of items to be displayed in the scrolling list.
316 items
318 is the number of elements in the given list.
319 numbers
321 is true if you want the items in the list to have a number
322 attached to the front of the list items.
323 highlight
325 specifies the display attribute of the currently selected
326 item.
327 box is true if the widget should be drawn with a box around it.
329 shadow
331 is true to turn the shadow on around this widget.
332 If the widget could not be created then a NULL pointer is
334 returned.
335 positionCDKScroll
337 allows the user to move the widget around the screen via the cur‐
338 sor/keypad keys. See cdk_position (3) for key bindings.
339 setCDKScroll
341 lets the programmer modify certain elements of an existing scroll
342 widget. The parameter names correspond to the same parameter
343 names listed in the newCDKScroll function.
344 setCDKScrollBackgroundAttrib
346 sets the background attribute of the widget. The parameter
347 attribute is a curses attribute, e.g., A_BOLD.
348 setCDKScrollBackgroundColor
350 sets the background color of the widget. The parameter color is
351 in the format of the Cdk format strings. See cdk_display (3).
352 setCDKScrollBox
354 sets whether the widget will be drawn with a box around it.
355 setCDKScrollBoxAttribute
357 sets the attribute of the box.
358 setCDKScrollCurrent
360 sets the index for the current item.
361 setCDKScrollCurrentItem
363 set the current item number in the scroller.
364 setCDKScrollCurrentTop
366 set the top line number of the scroller.
367 setCDKScrollHighlight
369 sets the attribute of the highlight bar.
370 setCDKScrollHorizontalChar
372 sets the horizontal drawing character for the box to the given
373 character.
374 setCDKScrollItems
376 sets the contents of the scrolling list.
377 setCDKScrollLLChar
379 sets the lower left hand corner of the widget's box to the given
380 character.
381 setCDKScrollLRChar
383 sets the lower right hand corner of the widget's box to the given
384 character.
385 setCDKScrollPosition
387 sets the current item in the widget to the given position.
388 setCDKScrollPostProcess
390 allows the user to have the widget call a function after the key
391 has been applied to the widget. The parameter function is the
392 callback function. The parameter data points to data passed to
393 the callback function. To learn more about post-processing see
394 cdk_process [4m(3).
395 setCDKScrollPreProcess
397 allows the user to have the widget call a function after a key is
398 hit and before the key is applied to the widget. The parameter
399 function is the callback function. The parameter data points to
400 data passed to the callback function. To learn more about pre-
401 processing see cdk_process [4m(3).
402 setCDKScrollULChar
404 sets the upper left hand corner of the widget's box to the given
405 character.
406 setCDKScrollURChar
408 sets the upper right hand corner of the widget's box to the given
409 character.
410 setCDKScrollVerticalChar
412 sets the vertical drawing character for the box to the given char‐
413 acter.
414
416 When the widget is activated there are several default key bindings
417 which will help the user enter or manipulate the information quickly.
418 The following table outlines the keys and their actions for this wid‐
419 get.
420 ┌─────────────────────────────────────────────────────────┐
422 │Key Action │
423 ├─────────────────────────────────────────────────────────┤
424 │Left Arrow Shift the list left one column. │
425 │Right Arrow Shift the list right one column. │
426 │Up Arrow Select the previous item in the list. │
427 │Down Arrow Select the next item in the list. │
428 ├─────────────────────────────────────────────────────────┤
429 │Prev Page │
430 │Ctrl-B Scroll one page backward. │
431 │Next Page │
432 │Ctrl-F Scroll one page forward. │
433 ├─────────────────────────────────────────────────────────┤
434 │1 │
435 │< │
436 │g │
437 │Home Move to the first element in the list. │
438 ├─────────────────────────────────────────────────────────┤
439 │> │
440 │G │
441 │End Move to the last element in the list. │
442 ├─────────────────────────────────────────────────────────┤
443 │$ Shift the list to the far right. │
444 │| Shift the list to the far left. │
445 ├─────────────────────────────────────────────────────────┤
446 │Return Exit the widget and return the index │
447 │ of the selected item. Also set the │
448 │ widget data exitType to vNORMAL. │
449 │Tab Exit the widget and return the index │
450 │ of the selected item. Also set the │
451 │ widget data exitType to vNORMAL. │
452 │Escape Exit the widget and return -1. Also │
453 │ set the widget data exitType to │
454 │ vESCAPE_HIT. │
455 │Ctrl-L Refreshes the screen. │
456 └─────────────────────────────────────────────────────────┘
458 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
459 cdk_scroll(3)