1cdk_scroll(3)              Library Functions Manual              cdk_scroll(3)
2
3
4

NAME

6       cdk_scroll - curses scrolling list widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       int activateCDKScroll (
14                      CDKSCROLL *scroll,
15                      chtype * actions);
16
17       void addCDKScrollItem (
18                      CDKSCROLL *scroll,
19                      const char *item);
20
21       void deleteCDKScrollItem (
22                      CDKSCROLL *scroll,
23                      int position);
24
25       void destroyCDKScroll (
26                      CDKSCROLL *scroll);
27
28       void drawCDKScroll (
29                      CDKSCROLL *scroll,
30                      boolean box);
31
32       void eraseCDKScroll (
33                      CDKSCROLL *scroll);
34
35       boolean getCDKScrollBox (
36                      CDKSCROLL *scroll);
37
38       int getCDKScrollCurrent(
39                      CDKSCROLL *scroll);
40
41       int getCDKScrollCurrentItem (
42                      CDKSCROLL *widget);
43
44       chtype getCDKScrollHighlight (
45                      CDKSCROLL *scroll,
46                      chtype highlight);
47
48       int getCDKScrollCurrentTop (
49                      CDKSCROLL *widget);
50
51       int getCDKScrollItems (
52                      CDKSCROLL *scroll,
53                      char **list);
54
55       int injectCDKScroll (
56                      CDKSCROLL *scroll,
57                      chtype input);
58
59       void insertCDKScrollItem (
60                      CDKSCROLL *scroll,
61                      const char *item);
62
63       void moveCDKScroll (
64                      CDKSCROLL *scroll,
65                      int xpos,
66                      int ypos,
67                      boolean relative,
68                      boolean refresh);
69
70       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
85       void positionCDKScroll (
86                      CDKSCROLL *scroll);
87
88       void setCDKScroll (
89                      CDKSCROLL *scroll,
90                      CDK_CONST char **itemList,
91                      int items,
92                      boolean numbers,
93                      chtype highlight,
94                      boolean box);
95
96       void setCDKScrollBackgroundAttrib (
97                      CDKSCROLL *scroll,
98                      chtype attribute);
99
100       void setCDKScrollBackgroundColor (
101                      CDKSCROLL *scroll,
102                      const char * color);
103
104       void setCDKScrollBox (
105                      CDKSCROLL *scroll,
106                      boolean box);
107
108       void setCDKScrollBoxAttribute (
109                      CDKSCROLL *scroll,
110                      chtype character);
111
112       void setCDKScrollCurrent(
113                      CDKSCROLL *scroll,
114                      intitem);
115
116       void setCDKScrollCurrentItem (
117                      CDKSCROLL *widget,
118                      intitem);
119
120       void setCDKScrollHighlight (
121                      CDKSCROLL *scroll,
122                      chtype highlight);
123
124       void setCDKScrollHorizontalChar (
125                      CDKSCROLL *scroll,
126                      chtype character);
127
128       void setCDKScrollItems (
129                      CDKSCROLL *scroll,
130                      CDK_CONST char **itemList,
131                      int listSize,
132                      boolean numbers);
133
134       void setCDKScrollLLChar (
135                      CDKSCROLL *scroll,
136                      chtype character);
137
138       void setCDKScrollLRChar (
139                      CDKSCROLL *scroll,
140                      chtype character);
141
142       void setCDKScrollPosition (
143                      CDKSCROLL *scroll,
144                      intitem);
145
146       void setCDKScrollPostProcess (
147                      CDKSCROLL *scroll,
148                      PROCESSFN callback,
149                      void * data);
150
151       void setCDKScrollPreProcess (
152                      CDKSCROLL *scroll,
153                      PROCESSFN callback,
154                      void * data);
155
156       void setCDKScrollULChar (
157                      CDKSCROLL *scroll,
158                      chtype character);
159
160       void setCDKScrollURChar (
161                      CDKSCROLL *scroll,
162                      chtype character);
163
164       void setCDKScrollVerticalChar (
165                      CDKSCROLL *scroll,
166                      chtype character);
167

DESCRIPTION

169       The  Cdk  scroll  widget  creates  a scrolling list.  The following are
170       functions which create or manipulate the Cdk scrolling list widget.
171

AVAILABLE FUNCTIONS

173       activateCDKScroll
174            activates the scroll widget and lets the user  interact  with  the
175            widget.
176
177            ·   The parameter scroll points to a non-NULL scroll widget.
178
179            ·   If  the actions parameter is passed with a non-NULL value, the
180                characters in the array will be injected into the widget.
181
182                To activate the widget interactively pass in  a  NULL  pointer
183                for actions.
184
185            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
190            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
194       addCDKScrollItem
195            allows the user to add an item into an existing scrolling list.
196
197            ·   The scroll parameter points to the scrolling list to  add  the
198                item to.
199
200            ·   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
203       deleteCDKScrollItem
204            allows the user to add an item into an existing scrolling list.
205
206            ·   The scroll parameter points to the scrolling list to  add  the
207                item to.
208
209            ·   The  parameter f2position is an int which specifies which ele‐
210                ment to remove.
211
212       destroyCDKScroll
213            removes the widget from the screen and  frees  memory  the  object
214            used.
215
216       drawCDKScroll
217            draws the scroll widget on the screen.  If the box option is true,
218            the widget is drawn with a box.
219
220       eraseCDKScroll
221            removes the widget from the screen.  This  does  NOT  destroy  the
222            widget.
223
224       getCDKScrollBox
225            returns true if the widget will be drawn with a box around it.
226
227       getCDKScrollCurrent
228            returns the current item's index.
229
230            This  is  deprecated  because  the name is inconsistent with other
231            widgets: use getCDKScrollCurrentItem.
232
233       getCDKScrollCurrentItem
234            returns the current item's index in the scroller.
235
236       getCDKScrollHighlight
237            returns the attribute of the highlight bar.
238
239       getCDKScrollCurrentTop
240            returns the top line of the scroller, counting from zero.
241
242       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
248       injectCDKScroll
249            injects a single character into the widget.
250
251            ·   The parameter scroll points to a non-NULL scroll widget.
252
253            ·   The  parameter  character  is the character to inject into the
254                widget.
255
256            The return value and side-effect (setting the  widget  data  exit‐
257            Type) depend upon the injected character:
258
259            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
264            ESCAPE the  function  returns -1.  The widget data exitType is set
265                   to vESCAPE_HIT.
266
267            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
272       insertCDKScrollItem
273            allows the user to add an item into an existing scrolling list.
274
275            ·   The scroll parameter points to the scrolling list to  add  the
276                item to.
277
278            ·   The  parameter  item  is a char * representing the new item to
279                add.
280
281            The item is always added before the current item in the list.
282
283       moveCDKScroll
284            moves the given widget to the given position.
285
286            ·   The parameters xpos and ypos are the new position of the  wid‐
287                get.
288
289                The parameter xpos may be an integer or one of the pre-defined
290                values TOP, BOTTOM, and CENTER.
291
292                The parameter ypos may be an integer or one of the pre-defined
293                values LEFT, RIGHT, and CENTER.
294
295            ·   The  parameter relative states whether the xpos/ypos pair is a
296                relative move or an absolute move.
297
298                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
303                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
304                relative = TRUE.  (weird things may happen).
305
306            ·   The final parameter refresh is a boolean  value  which  states
307                whether the widget will get refreshed after the move.
308
309       newCDKScroll
310            creates a scroll widget and returns a pointer to it.  Parameters:
311
312            ·   The  screen parameter is the screen you wish this widget to be
313                placed in.
314
315            ·   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
319            ·   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
323            ·   spos is where the scroll bar is to be placed.  This may be one
324                of three values:
325
326                LEFT,
327                     which  puts  the  scroll bar on the left of the scrolling
328                     list.
329
330                RIGHT
331                     which puts the scroll bar on the right side of the  list,
332                     and
333
334                NONE which does not add a scroll bar.
335
336            ·   height and width control the height and width of the widget.
337
338                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
344            ·   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
348            ·   itemList is the list of items to be displayed in the scrolling
349                list.
350
351            ·   items is the number of elements in the given list.
352
353            ·   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
356            ·   highlight  specifies  the  display  attribute of the currently
357                selected item.
358
359            ·   box is true if the widget should be drawn with  a  box  around
360                it.
361
362            ·   shadow is true to turn the shadow on around this widget.
363
364            If  the  widget  could  not  be  created  then  a  NULL pointer is
365            returned.
366
367       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
371       setCDKScroll
372            lets  the programmer modify certain elements of an existing scroll
373            widget.
374
375            The parameter names correspond to the same parameter names  listed
376            in the newCDKScroll function.
377
378       setCDKScrollBackgroundAttrib
379            sets the background attribute of the widget.
380
381            The parameter attribute is a curses attribute, e.g., A_BOLD.
382
383       setCDKScrollBackgroundColor
384            sets the background color of the widget.
385
386            The parameter color is in the format of the Cdk format strings.
387
388            See cdk_display (3).
389
390       setCDKScrollBox
391            sets whether the widget will be drawn with a box around it.
392
393       setCDKScrollBoxAttribute
394            sets the attribute of the box.
395
396       setCDKScrollCurrent
397            sets the index for the current item.
398
399       setCDKScrollCurrentItem
400            set the current item number in the scroller.
401
402       setCDKScrollCurrentTop
403            set the top line number of the scroller.
404
405       setCDKScrollHighlight
406            sets the attribute of the highlight bar.
407
408       setCDKScrollHorizontalChar
409            sets  the  horizontal  drawing  character for the box to the given
410            character.
411
412       setCDKScrollItems
413            sets the contents of the scrolling list.  The previous contents of
414            the scrolling list stored in the widget are freed.
415
416       setCDKScrollLLChar
417            sets  the  lower left hand corner of the widget's box to the given
418            character.
419
420       setCDKScrollLRChar
421            sets the lower right hand corner of the widget's box to the  given
422            character.
423
424       setCDKScrollPosition
425            sets the current item in the widget to the given position.
426
427       setCDKScrollPostProcess
428            allows  the  user to have the widget call a function after the key
429            has been applied to the widget.
430
431            ·   The parameter function is the callback function.
432
433            ·   The parameter data points to data passed to the callback func‐
434                tion.
435
436            To learn more about post-processing see cdk_process (3).
437
438       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
442            ·   The parameter function is the callback function.
443
444            ·   The parameter data points to data passed to the callback func‐
445                tion.
446
447            To learn more about pre-processing see cdk_process (3).
448
449       setCDKScrollULChar
450            sets  the  upper left hand corner of the widget's box to the given
451            character.
452
453       setCDKScrollURChar
454            sets the upper right hand corner of the widget's box to the  given
455            character.
456
457       setCDKScrollVerticalChar
458            sets the vertical drawing character for the box to the given char‐
459            acter.
460

KEY BINDINGS

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
467             ┌─────────────────────────────────────────────────────────┐
468Key               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 │
500vESCAPE_HIT.                           │
501             │Ctrl-L            Refreshes the screen.                  │
502             └─────────────────────────────────────────────────────────┘

SEE ALSO

504       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
505
506
507
508                                                                 cdk_scroll(3)
Impressum