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

NAME

6       cdk_alphalist - curses sorted list widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       char *activateCDKAlphalist (
14                      CDKALPHALIST *alphalist,
15                      chtype *actions);
16
17       void destroyCDKAlphalist (
18                      CDKALPHALIST *alphalist);
19
20       void drawCDKAlphalist (
21                      CDKALPHALIST *alphalist,
22                      boolean box);
23
24       void eraseCDKAlphalist (
25                      CDKALPHALIST *alphalist);
26
27       boolean getCDKAlphalistBox (
28                      CDKALPHALIST *alphalist);
29
30       char **getCDKAlphalistContents (
31                      CDKALPHALIST *alphalist,
32                      int *size);
33
34       int getCDKAlphalistCurrentItem (
35                      CDKALPHALIST *widget);
36
37       chtype getCDKAlphalistFillerChar (
38                      CDKALPHALIST *alphalist);
39
40       chtype getCDKAlphalistHighlight (
41                      CDKALPHALIST *alphalist);
42
43       char *injectCDKAlphalist (
44                      CDKALPHALIST *alphalist,
45                      chtype input);
46
47       void moveCDKAlphalist (
48                      CDKALPHALIST *alphalist,
49                      int xpos,
50                      int ypos,
51                      boolean relative,
52                      boolean refresh);
53
54       CDKALPHALIST *newCDKAlphalist (
55                      CDKSCREEN *cdkscreen,
56                      int xpos,
57                      int ypos,
58                      int height,
59                      int width,
60                      const char * title,
61                      const char * label,
62                      CDK_CONST char ** list,
63                      int listSize,
64                      chtype fillerCharacter,
65                      chtype highlight,
66                      boolean box,
67                      boolean shadow);
68
69       void positionCDKAlphalist (
70                      CDKALPHALIST *alphalist);
71
72       void setCDKAlphalist (
73                      CDKALPHALIST *alphalist,
74                      CDK_CONST char ** list,
75                      int listSize,
76                      chtype fillerCharacter,
77                      chtype highlight,
78                      boolean box);
79
80       void setCDKAlphalistBackgroundAttrib (
81                      CDKALPHALIST *alphalist,
82                      chtype attribute);
83
84       void setCDKAlphalistBackgroundColor (
85                      CDKALPHALIST *alphalist,
86                      const char * color);
87
88       void setCDKAlphalistBox (
89                      CDKALPHALIST *alphalist,
90                      boolean box);
91
92       void setCDKAlphalistBoxAttribute (
93                      CDKALPHALIST *alphalist,
94                      chtype character);
95
96       void setCDKAlphalistContents (
97                      CDKALPHALIST *alphalist,
98                      CDK_CONST char ** list,
99                      int listSize);
100
101       void setCDKAlphalistCurrentItem (
102                      CDKALPHALIST *widget,
103                      int item);
104
105       void setCDKAlphalistFillerChar (
106                      CDKALPHALIST *alphalist,
107                      chtype fillerCharacter);
108
109       void setCDKAlphalistHighlight (
110                      CDKALPHALIST *alphalist,
111                      chtype highlight);
112
113       void setCDKAlphalistHorizontalChar (
114                      CDKALPHALIST *alphalist,
115                      chtype character);
116
117       void setCDKAlphalistLLChar (
118                      CDKALPHALIST *alphalist,
119                      chtype character);
120
121       void setCDKAlphalistLRChar (
122                      CDKALPHALIST *alphalist,
123                      chtype character);
124
125       void setCDKAlphalistPostProcess (
126                      CDKALPHALIST *alphalist,
127                      PROCESSFN callback,
128                      void * data);
129
130       void setCDKAlphalistPreProcess (
131                      CDKALPHALIST *alphalist,
132                      PROCESSFN callback,
133                      void * data);
134
135       void setCDKAlphalistULChar (
136                      CDKALPHALIST *alphalist,
137                      chtype character);
138
139       void setCDKAlphalistURChar (
140                      CDKALPHALIST *alphalist,
141                      chtype character);
142
143       void setCDKAlphalistVerticalChar (
144                      CDKALPHALIST *alphalist,
145                      chtype character);
146

DESCRIPTION

148       The Cdk alphalist allows a user to select from a list of alphabetically
149       sorted words.  The user can use the arrow keys to traverse through  the
150       list  or  type in the beginning of the word and the list will automati‐
151       cally adjust itself in the correct place in the scrolling  list.   This
152       widget, like the file selector widget, is a compound widget of both the
153       entry field widget and the scrolling list widget.
154

AVAILABLE FUNCTIONS

156       activateCDKAlphalist
157            activates the alphalist widget and lets the user interact with the
158            widget.
159
160            ·   The  parameter  alphalist is a pointer to a non-NULL alphalist
161                widget.
162
163            ·   If the actions parameter is passed with a non-NULL value,  the
164                characters in the array will be injected into the widget.
165
166                To  activate  the  widget interactively pass in a NULL pointer
167                for actions.
168
169            If the character entered into this  widget  is  RETURN  then  this
170            function  will  return a char * of the information which was typed
171            in the field.
172
173            If the TAB character is hit then the widget will try  to  complete
174            the word in the entry field.
175
176            If  the widget is exited with the RETURN character then the widget
177            data exitType will be set to vNORMAL.
178
179            If the widget was exited with the ESCAPE key then the widget  data
180            exitType will be set to vESCAPE_HIT and the widget returns NULL.
181
182       destroyCDKAlphalist
183            removes  the  widget  from  the screen and frees memory the object
184            used.
185
186       drawCDKAlphalist
187            draws the alphalist widget on the screen.
188
189            If the box parameter is true, the widget is drawn with a box.
190
191       eraseCDKAlphalist
192            removes the widget from the screen.  This  does  NOT  destroy  the
193            widget.
194
195       getCDKAlphalistBox
196            returns true if the widget will be drawn with a box around it.
197
198       getCDKAlphalistContents
199            returns the contents of the alphalist.
200
201       getCDKAlphalistCurrentItem
202            returns the current position in the scroll-widget.
203
204       getCDKAlphalistFillerChar
205            returns  the  character  being used as the filler character in the
206            entry field portion of the widget.
207
208       getCDKAlphalistHighlight
209            returns the attribute of the highlight bar of the  scrolling  list
210            portion of the widget.
211
212       injectCDKAlphalist
213            injects  a  single  character  into the widget (actually the entry
214            widget).
215
216            ·   The parameter alphalist is a pointer to a  non-NULL  alphalist
217                widget.
218
219            ·   The  parameter  character  is the character to inject into the
220                widget.
221
222            The return value and side-effect (setting the  widget  data  exit‐
223            Type) depend upon the injected character:
224
225            RETURN or TAB
226                   the  function  returns  the information in the entry field.
227                   The widget data exitType is set to vNORMAL.
228
229            ESCAPE the function returns a NULL pointer.  The widget data exit‐
230                   Type is set to vESCAPE_HIT.
231
232            Otherwise
233                   unless  modified  by  preprocessing,  postprocessing or key
234                   bindings, the function returns a NULL pointer.  The  widget
235                   data exitType is set to vEARLY_EXIT.
236
237       moveCDKAlphalist
238            moves the given widget to the given position.
239
240            ·   The  parameters xpos and ypos are the new position of the wid‐
241                get.
242
243                The parameter xpos may be an integer or one of the pre-defined
244                values TOP, BOTTOM, and CENTER.
245
246                The  parameter  ypos  may  be  an  integer, or one of the pre-
247                defined values LEFT, RIGHT, and CENTER.
248
249            ·   The parameter relative states whether the xpos/ypos pair is  a
250                relative move or an absolute move.
251
252                For  example,  if  xpos  = 1 and ypos = 2 and relative = TRUE,
253                then the widget would move one row down and two columns right.
254                If the value of relative was FALSE, then the widget would move
255                to the position (1,2).
256
257                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
258                relative = TRUE.  (weird things may happen).  The final param‐
259                eter refresh is a boolean value which states whether the  wid‐
260                get will get refreshed after the move.
261
262            newCDKAlphalist
263                 creates a pointer to an alphalist widget.  Parameters:
264
265                 ·   screen  is  the  screen you wish this widget to be placed
266                     in.
267
268                 ·   xpos controls the placement of the object along the hori‐
269                     zontal  axis.   This parameter can take an integer or one
270                     of the pre-defined values LEFT, RIGHT, and CENTER.
271
272                 ·   ypos controls the placement of the object along the  ver‐
273                     tical  axis.   This parameter may be an integer value, or
274                     one of the pre-defined values TOP, BOTTOM, and CENTER.
275
276                 ·   height and width control the height and width of the wid‐
277                     get.   If  you  provide a value of zero for either of the
278                     height or the width, the widget will be created with  the
279                     full  width  and  height of the screen.  If you provide a
280                     negative value, the  widget  will  be  created  the  full
281                     height or width minus the value provided.
282
283                 ·   title is the string which will be displayed at the top of
284                     the scrolling list.  The title can be more than one line;
285                     just  provide  a  carriage  return  character at the line
286                     break.
287
288                 ·   label is the string which will be displayed in the  label
289                     of the entry field.
290
291                 ·   list  is the list of words which will be displayed in the
292                     scrolling list.  This list does not have  to  be  sorted,
293                     this  widget  automatically  sorts the list (note that it
294                     modifies the caller's copy of the list to do this).
295
296                 ·   listSize tells the widget how large the word list is.
297
298                 ·   fillerCharacter is the character which is to be displayed
299                     in an empty space in the entry field.
300
301                 ·   highlight  is  the  attribute of the highlight bar in the
302                     scrolling list.
303
304                 ·   box is true if the widget should  be  drawn  with  a  box
305                     around it.
306
307                 ·   shadow is true to turn the shadow on around this widget.
308
309                 If  the  widget  could  not be created then a NULL pointer is
310                 returned.
311
312            positionCDKAlphalist
313                 allows the user to move the widget around the screen via  the
314                 cursor/keypad keys.  See cdk_position (3) for key bindings.
315
316            setCDKAlphalist
317                 lets  the  programmer  modify certain elements of an existing
318                 alphalist widget.
319
320                 The parameter names correspond to the  same  parameter  names
321                 listed in the newCDKAlphalist function.
322
323            setCDKAlphalistBackgroundAttrib
324                 sets the background attribute of the widget.
325
326                 The parameter attribute is a curses attribute, e.g., A_BOLD.
327
328            setCDKAlphalistBackgroundColor
329                 sets the background color of the widget.
330
331                 The  parameter  color  is  in  the  format  of the Cdk format
332                 strings.  See cdk_display (3).
333
334            setCDKAlphalistBox
335                 sets whether the widget will be drawn with a box around it.
336
337            setCDKAlphalistBoxAttribute
338                 sets the attribute of the box.
339
340            setCDKAlphalistContents
341                 sets the contents of the alphalist widget (note that it sorts
342                 the caller's copy of the list).
343
344            setCDKAlphalistCurrentItem
345                 set the current position in the scroll-widget.
346
347            setCDKAlphalistFillerChar
348                 sets  the  character to use when drawing the entry field por‐
349                 tion of the widget.
350
351            setCDKAlphalistHighlight
352                 sets the attribute of the highlight bar of the scrolling list
353                 portion of the widget.
354
355            setCDKAlphalistHorizontalChar
356                 sets  the  horizontal  drawing  character  for the box to the
357                 given character.
358
359            setCDKAlphalistLLChar
360                 sets the lower left hand corner of the widget's  box  to  the
361                 given character.
362
363            setCDKAlphalistLRChar
364                 sets  the  lower right hand corner of the widget's box to the
365                 given character.
366
367            setCDKAlphalistPostProcess
368                 allows the user to have the widget call a function after  the
369                 key has been applied to the widget.
370
371                 ·   The parameter function is the callback function.
372
373                 ·   The  parameter data points to data passed to the callback
374                     function.
375
376                 To learn more about post-processing see cdk_process (3).
377
378            setCDKAlphalistPreProcess
379                 allows the user to have the widget call a  function  after  a
380                 key is hit and before the key is applied to the widget.
381
382                 ·   The parameter function is the callback function.
383
384                 ·   The  parameter data points to data passed to the callback
385                     function.
386
387                 To learn more about pre-processing see cdk_process (3).
388
389            setCDKAlphalistULChar
390                 sets the upper left hand corner of the widget's  box  to  the
391                 given character.
392
393            setCDKAlphalistURChar
394                 sets  the  upper right hand corner of the widget's box to the
395                 given character.
396
397            setCDKAlphalistVerticalChar
398                 sets the vertical drawing character for the box to the  given
399                 character.
400

KEY BINDINGS

402       When  the  widget  is  activated there are several default key bindings
403       which will help the user enter or manipulate the  information  quickly.
404       Since  this widget is built from both the scrolling list widget and the
405       entry field widget, the key bindings are the same  for  the  respective
406       fields.  The extra key bindings are listed below.
407
408               ┌────────────────┬─────────────────────────────────────┐
409Key             Action                              
410               ├────────────────┼─────────────────────────────────────┤
411               ├────────────────┼─────────────────────────────────────┤
412               │Up Arrow        │ Scrolls  the  scrolling list up one │
413               │                │ line.                               │
414               ├────────────────┼─────────────────────────────────────┤
415               │Down Arrow      │ Scrolls the scrolling list down one │
416               │                │ line.                               │
417               ├────────────────┼─────────────────────────────────────┤
418               │Page Up         │ Scrolls  the  scrolling list up one │
419               │                │ page.                               │
420               ├────────────────┼─────────────────────────────────────┤
421               │CTRL-B          │ Scrolls the scrolling list  up  one │
422               │                │ page.     Page   Down/Scrolls   the │
423               │                │ scrolling list down one page.       │
424               ├────────────────┼─────────────────────────────────────┤
425               │CTRL-F          │ Scrolls the scrolling list down one │
426               │                │ page.                               │
427               ├────────────────┼─────────────────────────────────────┤
428               │Tab             │ Tries  to  complete the word in the │
429               │                │ entry field.  If the  word  segment │
430               │                │ is  not unique then the widget will │
431               │                │ beep and present a  list  of  close │
432               │                │ matches.                            │
433               ├────────────────┼─────────────────────────────────────┤
434               │Return          │ Returns   the  word  in  the  entry │
435               │                │ field.  It  also  sets  the  widget │
436               │                │ data exitType to vNORMAL.           │
437               ├────────────────┼─────────────────────────────────────┤
438               │Escape          │ Exits the widget and returns a NULL
439               │                │ pointer.  It also sets  the  widget │
440               │                │ data exitType to vESCAPE_HIT.       │
441               └────────────────┴─────────────────────────────────────┘

SEE ALSO

443       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
444

NOTES

446       This  widget  is  created  from the scrolling list widget and the entry
447       field widget.  This is a good example on how to build your own  widgets
448       using the base widgets provided in this distribution.
449
450
451
452                                                              cdk_alphalist(3)
Impressum