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 **itemList);
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       int getCDKScrollCurrentTop (
121                      CDKSCROLL *widget);
122
123       void setCDKScrollHighlight (
124                      CDKSCROLL *scroll,
125                      chtype highlight);
126
127       void setCDKScrollHorizontalChar (
128                      CDKSCROLL *scroll,
129                      chtype character);
130
131       void setCDKScrollItems (
132                      CDKSCROLL *scroll,
133                      CDK_CONST char **itemList,
134                      int listSize,
135                      boolean numbers);
136
137       void setCDKScrollLLChar (
138                      CDKSCROLL *scroll,
139                      chtype character);
140
141       void setCDKScrollLRChar (
142                      CDKSCROLL *scroll,
143                      chtype character);
144
145       void setCDKScrollPosition (
146                      CDKSCROLL *scroll,
147                      intitem);
148
149       void setCDKScrollPostProcess (
150                      CDKSCROLL *scroll,
151                      PROCESSFN callback,
152                      void * data);
153
154       void setCDKScrollPreProcess (
155                      CDKSCROLL *scroll,
156                      PROCESSFN callback,
157                      void * data);
158
159       void setCDKScrollULChar (
160                      CDKSCROLL *scroll,
161                      chtype character);
162
163       void setCDKScrollURChar (
164                      CDKSCROLL *scroll,
165                      chtype character);
166
167       void setCDKScrollVerticalChar (
168                      CDKSCROLL *scroll,
169                      chtype character);
170

DESCRIPTION

172       The  Cdk  scroll  widget  creates  a scrolling list.  The following are
173       functions which create or manipulate the Cdk scrolling list widget.
174

AVAILABLE FUNCTIONS

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
189       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
195       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
201       destroyCDKScroll
202            removes the widget from the screen and  frees  memory  the  object
203            used.
204
205       drawCDKScroll
206            draws the scroll widget on the screen.  If the box option is true,
207            the widget is drawn with a box.
208
209       eraseCDKScroll
210            removes the widget from the screen.  This  does  NOT  destroy  the
211            widget.
212
213       getCDKScrollBox
214            returns true if the widget will be drawn with a box around it.
215
216       getCDKScrollCurrent
217            returns the current item's index.
218
219       getCDKScrollCurrentItem
220            returns the current item number in the scroller.
221
222       getCDKScrollHighlight
223            returns the attribute of the highlight bar.
224
225       getCDKScrollCurrentTop
226            returns the top line of the scroller, counting from zero.
227
228       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
232       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
239            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
244            ESCAPE the function returns -1.  The widget data exitType  is  set
245                   to vESCAPE_HIT.
246
247            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
252       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
259       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
274       newCDKScroll
275            creates a scroll widget and returns a pointer to it.  Parameters:
276
277            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
283            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
287            spos is where the scroll bar is to be placed.  This may be one  of
288                 three values:
289
290                 LEFT,
291                      which  puts  the scroll bar on the left of the scrolling
292                      list.
293
294                 RIGHT
295                      which puts the scroll bar on the right side of the list,
296                      and
297
298                 NONE which does not add a scroll bar.
299
300            height and
301
302            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
309            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
314            itemList
315                 is the list of items to be displayed in the scrolling list.
316
317            items
318                 is the number of elements in the given list.
319
320            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
324            highlight
325                 specifies the display attribute  of  the  currently  selected
326                 item.
327
328            box  is true if the widget should be drawn with a box around it.
329
330            shadow
331                 is true to turn the shadow on around this widget.
332
333            If  the  widget  could  not  be  created  then  a  NULL pointer is
334            returned.
335
336       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
340       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
345       setCDKScrollBackgroundAttrib
346            sets  the  background  attribute  of  the  widget.   The parameter
347            attribute is a curses attribute, e.g., A_BOLD.
348
349       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
353       setCDKScrollBox
354            sets whether the widget will be drawn with a box around it.
355
356       setCDKScrollBoxAttribute
357            sets the attribute of the box.
358
359       setCDKScrollCurrent
360            sets the index for the current item.
361
362       setCDKScrollCurrentItem
363            set the current item number in the scroller.
364
365       setCDKScrollCurrentTop
366            set the top line number of the scroller.
367
368       setCDKScrollHighlight
369            sets the attribute of the highlight bar.
370
371       setCDKScrollHorizontalChar
372            sets  the  horizontal  drawing  character for the box to the given
373            character.
374
375       setCDKScrollItems
376            sets the contents of the scrolling list.
377
378       setCDKScrollLLChar
379            sets the lower left hand corner of the widget's box to  the  given
380            character.
381
382       setCDKScrollLRChar
383            sets  the lower right hand corner of the widget's box to the given
384            character.
385
386       setCDKScrollPosition
387            sets the current item in the widget to the given position.
388
389       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 (3).
395
396       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 (3).
402
403       setCDKScrollULChar
404            sets the upper left hand corner of the widget's box to  the  given
405            character.
406
407       setCDKScrollURChar
408            sets  the upper right hand corner of the widget's box to the given
409            character.
410
411       setCDKScrollVerticalChar
412            sets the vertical drawing character for the box to the given char‐
413            acter.
414

KEY BINDINGS

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
421             ┌─────────────────────────────────────────────────────────┐
422Key               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 │
454vESCAPE_HIT.                           │
455             │Ctrl-L            Refreshes the screen.                  │
456             └─────────────────────────────────────────────────────────┘

SEE ALSO

458       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
459
460
461
462                                                                 cdk_scroll(3)
Impressum