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 const 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 **list);
54 int injectCDKScroll (
56 CDKSCROLL *scroll,
57 chtype input);
58 void insertCDKScrollItem (
60 CDKSCROLL *scroll,
61 const 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 const char *title,
78 CDK_CONST 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 CDK_CONST 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 const 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 void setCDKScrollHighlight (
121 CDKSCROLL *scroll,
122 chtype highlight);
123 void setCDKScrollHorizontalChar (
125 CDKSCROLL *scroll,
126 chtype character);
127 void setCDKScrollItems (
129 CDKSCROLL *scroll,
130 CDK_CONST char **itemList,
131 int listSize,
132 boolean numbers);
133 void setCDKScrollLLChar (
135 CDKSCROLL *scroll,
136 chtype character);
137 void setCDKScrollLRChar (
139 CDKSCROLL *scroll,
140 chtype character);
141 void setCDKScrollPosition (
143 CDKSCROLL *scroll,
144 intitem);
145 void setCDKScrollPostProcess (
147 CDKSCROLL *scroll,
148 PROCESSFN callback,
149 void * data);
150 void setCDKScrollPreProcess (
152 CDKSCROLL *scroll,
153 PROCESSFN callback,
154 void * data);
155 void setCDKScrollULChar (
157 CDKSCROLL *scroll,
158 chtype character);
159 void setCDKScrollURChar (
161 CDKSCROLL *scroll,
162 chtype character);
163 void setCDKScrollVerticalChar (
165 CDKSCROLL *scroll,
166 chtype character);
167
169 The Cdk scroll widget creates a scrolling list. The following are
170 functions which create or manipulate the Cdk scrolling list widget.
171
173 activateCDKScroll
174 activates the scroll widget and lets the user interact with the
175 widget.
176 · The parameter scroll points to a non-NULL scroll widget.
178 · If the actions parameter is passed with a non-NULL value, the
180 characters in the array will be injected into the widget.
181 To activate the widget interactively pass in a NULL pointer
183 for actions.
184 If the character entered into this widget is RETURN or TAB then
186 this function will return a value from 0 to the number of items-1,
187 representing the item selected. It will also set the widget data
188 exitType to vNORMAL.
189 If the character entered into this widget was ESCAPE, then the
191 widget will return a value of -1 and the widget data exitType will
192 be set to vESCAPE_HIT.
193 addCDKScrollItem
195 allows the user to add an item into an existing scrolling list.
196 · The scroll parameter points to the scrolling list to add the
198 item to.
199 · The parameter item is a char * representing the new item to
201 add. The item is always added to the end of the list.
202 deleteCDKScrollItem
204 allows the user to add an item into an existing scrolling list.
205 · The scroll parameter points to the scrolling list to add the
207 item to.
208 · The parameter f2position is an int which specifies which ele‐
210 ment to remove.
211 destroyCDKScroll
213 removes the widget from the screen and frees memory the object
214 used.
215 drawCDKScroll
217 draws the scroll widget on the screen. If the box option is true,
218 the widget is drawn with a box.
219 eraseCDKScroll
221 removes the widget from the screen. This does NOT destroy the
222 widget.
223 getCDKScrollBox
225 returns true if the widget will be drawn with a box around it.
226 getCDKScrollCurrent
228 returns the current item's index.
229 This is deprecated because the name is inconsistent with other
231 widgets: use getCDKScrollCurrentItem.
232 getCDKScrollCurrentItem
234 returns the current item's index in the scroller.
235 getCDKScrollHighlight
237 returns the attribute of the highlight bar.
238 getCDKScrollCurrentTop
240 returns the top line of the scroller, counting from zero.
241 getCDKScrollItems
243 optionally copies the scrolling-list items into the caller's list,
244 which must be large enough since this function does not allocate
245 it. If the list parameter is null, no copying is done. It
246 returns the list size whether or not the list parameter is null.
247 injectCDKScroll
249 injects a single character into the widget.
250 · The parameter scroll points to a non-NULL scroll widget.
252 · The parameter character is the character to inject into the
254 widget.
255 The return value and side-effect (setting the widget data exit‐
257 Type) depend upon the injected character:
258 RETURN or TAB
260 the function returns a value ranging from zero to one less
261 than the number of items, representing the item selected.
262 The widget data exitType is set to vNORMAL.
263 ESCAPE the function returns -1. The widget data exitType is set
265 to vESCAPE_HIT.
266 Otherwise
268 unless modified by preprocessing, postprocessing or key
269 bindings, the function returns -1. The widget data exit‐
270 Type is set to vEARLY_EXIT.
271 insertCDKScrollItem
273 allows the user to add an item into an existing scrolling list.
274 · The scroll parameter points to the scrolling list to add the
276 item to.
277 · The parameter item is a char * representing the new item to
279 add.
280 The item is always added before the current item in the list.
282 moveCDKScroll
284 moves the given widget to the given position.
285 · The parameters xpos and ypos are the new position of the wid‐
287 get.
288 The parameter xpos may be an integer or one of the pre-defined
290 values TOP, BOTTOM, and CENTER.
291 The parameter ypos may be an integer or one of the pre-defined
293 values LEFT, RIGHT, and CENTER.
294 · The parameter relative states whether the xpos/ypos pair is a
296 relative move or an absolute move.
297 For example, if xpos = 1 and ypos = 2 and relative = TRUE,
299 then the widget would move one row down and two columns right.
300 If the value of relative was FALSE, then the widget would move
301 to the position (1,2).
302 Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
304 relative = TRUE. (weird things may happen).
305 · The final parameter refresh is a boolean value which states
307 whether the widget will get refreshed after the move.
308 newCDKScroll
310 creates a scroll widget and returns a pointer to it. Parameters:
311 · The screen parameter is the screen you wish this widget to be
313 placed in.
314 · The parameter xpos controls the placement of the object along
316 the horizontal axis. This parameter may be an integer or one
317 of the pre-defined values LEFT, RIGHT, and CENTER.
318 · ypos controls the placement of the object along the vertical
320 axis. This parameter may be an integer value or one of the
321 pre-defined values TOP, BOTTOM, and CENTER.
322 · spos is where the scroll bar is to be placed. This may be one
324 of three values:
325 LEFT,
327 which puts the scroll bar on the left of the scrolling
328 list.
329 RIGHT
331 which puts the scroll bar on the right side of the list,
332 and
333 NONE which does not add a scroll bar.
335 · height and width control the height and width of the widget.
337 If you provide a value of zero for either of the height or the
339 width, the widget will be created with the full width and
340 height of the screen. If you provide a negative value, the
341 widget will be created the full height or width minus the
342 value provided.
343 · title is the string which will be displayed at the top of the
345 widget. The title can be more than one line; just provide a
346 carriage return character at the line break.
347 · itemList is the list of items to be displayed in the scrolling
349 list.
350 · items is the number of elements in the given list.
352 · numbers is true if you want the items in the list to have a
354 number attached to the front of the list items.
355 · highlight specifies the display attribute of the currently
357 selected item.
358 · box is true if the widget should be drawn with a box around
360 it.
361 · shadow is true to turn the shadow on around this widget.
363 If the widget could not be created then a NULL pointer is
365 returned.
366 positionCDKScroll
368 allows the user to move the widget around the screen via the cur‐
369 sor/keypad keys. See cdk_position (3) for key bindings.
370 setCDKScroll
372 lets the programmer modify certain elements of an existing scroll
373 widget.
374 The parameter names correspond to the same parameter names listed
376 in the newCDKScroll function.
377 setCDKScrollBackgroundAttrib
379 sets the background attribute of the widget.
380 The parameter attribute is a curses attribute, e.g., A_BOLD.
382 setCDKScrollBackgroundColor
384 sets the background color of the widget.
385 The parameter color is in the format of the Cdk format strings.
387 See cdk_display (3).
389 setCDKScrollBox
391 sets whether the widget will be drawn with a box around it.
392 setCDKScrollBoxAttribute
394 sets the attribute of the box.
395 setCDKScrollCurrent
397 sets the index for the current item.
398 setCDKScrollCurrentItem
400 set the current item number in the scroller.
401 setCDKScrollCurrentTop
403 set the top line number of the scroller.
404 setCDKScrollHighlight
406 sets the attribute of the highlight bar.
407 setCDKScrollHorizontalChar
409 sets the horizontal drawing character for the box to the given
410 character.
411 setCDKScrollItems
413 sets the contents of the scrolling list. The previous contents of
414 the scrolling list stored in the widget are freed.
415 setCDKScrollLLChar
417 sets the lower left hand corner of the widget's box to the given
418 character.
419 setCDKScrollLRChar
421 sets the lower right hand corner of the widget's box to the given
422 character.
423 setCDKScrollPosition
425 sets the current item in the widget to the given position.
426 setCDKScrollPostProcess
428 allows the user to have the widget call a function after the key
429 has been applied to the widget.
430 · The parameter function is the callback function.
432 · The parameter data points to data passed to the callback func‐
434 tion.
435 To learn more about post-processing see cdk_process [4m(3).
437 setCDKScrollPreProcess
439 allows the user to have the widget call a function after a key is
440 hit and before the key is applied to the widget.
441 · The parameter function is the callback function.
443 · The parameter data points to data passed to the callback func‐
445 tion.
446 To learn more about pre-processing see cdk_process [4m(3).
448 setCDKScrollULChar
450 sets the upper left hand corner of the widget's box to the given
451 character.
452 setCDKScrollURChar
454 sets the upper right hand corner of the widget's box to the given
455 character.
456 setCDKScrollVerticalChar
458 sets the vertical drawing character for the box to the given char‐
459 acter.
460
462 When the widget is activated there are several default key bindings
463 which will help the user enter or manipulate the information quickly.
464 The following table outlines the keys and their actions for this wid‐
465 get.
466 ┌─────────────────────────────────────────────────────────┐
468 │Key Action │
469 ├─────────────────────────────────────────────────────────┤
470 │Left Arrow Shift the list left one column. │
471 │Right Arrow Shift the list right one column. │
472 │Up Arrow Select the previous item in the list. │
473 │Down Arrow Select the next item in the list. │
474 ├─────────────────────────────────────────────────────────┤
475 │Prev Page │
476 │Ctrl-B Scroll one page backward. │
477 │Next Page │
478 │Ctrl-F Scroll one page forward. │
479 ├─────────────────────────────────────────────────────────┤
480 │1 │
481 │< │
482 │g │
483 │Home Move to the first element in the list. │
484 ├─────────────────────────────────────────────────────────┤
485 │> │
486 │G │
487 │End Move to the last element in the list. │
488 ├─────────────────────────────────────────────────────────┤
489 │$ Shift the list to the far right. │
490 │| Shift the list to the far left. │
491 ├─────────────────────────────────────────────────────────┤
492 │Return Exit the widget and return the index │
493 │ of the selected item. Also set the │
494 │ widget data exitType to vNORMAL. │
495 │Tab Exit the widget and return the index │
496 │ of the selected item. Also set the │
497 │ widget data exitType to vNORMAL. │
498 │Escape Exit the widget and return -1. Also │
499 │ set the widget data exitType to │
500 │ vESCAPE_HIT. │
501 │Ctrl-L Refreshes the screen. │
502 └─────────────────────────────────────────────────────────┘
504 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
505 cdk_scroll(3)