1cdk_alphalist(3) Library Functions Manual cdk_alphalist(3)
2
6 cdk_alphalist - curses sorted list widget.
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 char *activateCDKAlphalist (
14 CDKALPHALIST *alphalist,
15 chtype *actions);
16 void destroyCDKAlphalist (
18 CDKALPHALIST *alphalist);
19 void drawCDKAlphalist (
21 CDKALPHALIST *alphalist,
22 boolean box);
23 void eraseCDKAlphalist (
25 CDKALPHALIST *alphalist);
26 boolean getCDKAlphalistBox (
28 CDKALPHALIST *alphalist);
29 char **getCDKAlphalistContents (
31 CDKALPHALIST *alphalist,
32 int *size);
33 int getCDKAlphalistCurrentItem (
35 CDKALPHALIST *widget);
36 chtype getCDKAlphalistFillerChar (
38 CDKALPHALIST *alphalist);
39 chtype getCDKAlphalistHighlight (
41 CDKALPHALIST *alphalist);
42 char *injectCDKAlphalist (
44 CDKALPHALIST *alphalist,
45 chtype input);
46 void moveCDKAlphalist (
48 CDKALPHALIST *alphalist,
49 int xpos,
50 int ypos,
51 boolean relative,
52 boolean refresh);
53 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 void positionCDKAlphalist (
70 CDKALPHALIST *alphalist);
71 void setCDKAlphalist (
73 CDKALPHALIST *alphalist,
74 CDK_CONST char ** list,
75 int listSize,
76 chtype fillerCharacter,
77 chtype highlight,
78 boolean box);
79 void setCDKAlphalistBackgroundAttrib (
81 CDKALPHALIST *alphalist,
82 chtype attribute);
83 void setCDKAlphalistBackgroundColor (
85 CDKALPHALIST *alphalist,
86 const char * color);
87 void setCDKAlphalistBox (
89 CDKALPHALIST *alphalist,
90 boolean box);
91 void setCDKAlphalistBoxAttribute (
93 CDKALPHALIST *alphalist,
94 chtype character);
95 void setCDKAlphalistContents (
97 CDKALPHALIST *alphalist,
98 CDK_CONST char ** list,
99 int listSize);
100 void setCDKAlphalistCurrentItem (
102 CDKALPHALIST *widget,
103 int item);
104 void setCDKAlphalistFillerChar (
106 CDKALPHALIST *alphalist,
107 chtype fillerCharacter);
108 void setCDKAlphalistHighlight (
110 CDKALPHALIST *alphalist,
111 chtype highlight);
112 void setCDKAlphalistHorizontalChar (
114 CDKALPHALIST *alphalist,
115 chtype character);
116 void setCDKAlphalistLLChar (
118 CDKALPHALIST *alphalist,
119 chtype character);
120 void setCDKAlphalistLRChar (
122 CDKALPHALIST *alphalist,
123 chtype character);
124 void setCDKAlphalistPostProcess (
126 CDKALPHALIST *alphalist,
127 PROCESSFN callback,
128 void * data);
129 void setCDKAlphalistPreProcess (
131 CDKALPHALIST *alphalist,
132 PROCESSFN callback,
133 void * data);
134 void setCDKAlphalistULChar (
136 CDKALPHALIST *alphalist,
137 chtype character);
138 void setCDKAlphalistURChar (
140 CDKALPHALIST *alphalist,
141 chtype character);
142 void setCDKAlphalistVerticalChar (
144 CDKALPHALIST *alphalist,
145 chtype character);
146
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
156 activateCDKAlphalist
157 activates the alphalist widget and lets the user interact with the
158 widget.
159 · The parameter alphalist is a pointer to a non-NULL alphalist
161 widget.
162 · If the actions parameter is passed with a non-NULL value, the
164 characters in the array will be injected into the widget.
165 To activate the widget interactively pass in a NULL pointer
167 for actions.
168 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 If the TAB character is hit then the widget will try to complete
174 the word in the entry field.
175 If the widget is exited with the RETURN character then the widget
177 data exitType will be set to vNORMAL.
178 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 destroyCDKAlphalist
183 removes the widget from the screen and frees memory the object
184 used.
185 drawCDKAlphalist
187 draws the alphalist widget on the screen.
188 If the box parameter is true, the widget is drawn with a box.
190 eraseCDKAlphalist
192 removes the widget from the screen. This does NOT destroy the
193 widget.
194 getCDKAlphalistBox
196 returns true if the widget will be drawn with a box around it.
197 getCDKAlphalistContents
199 returns the contents of the alphalist.
200 getCDKAlphalistCurrentItem
202 returns the current position in the scroll-widget.
203 getCDKAlphalistFillerChar
205 returns the character being used as the filler character in the
206 entry field portion of the widget.
207 getCDKAlphalistHighlight
209 returns the attribute of the highlight bar of the scrolling list
210 portion of the widget.
211 injectCDKAlphalist
213 injects a single character into the widget (actually the entry
214 widget).
215 · The parameter alphalist is a pointer to a non-NULL alphalist
217 widget.
218 · The parameter character is the character to inject into the
220 widget.
221 The return value and side-effect (setting the widget data exit‐
223 Type) depend upon the injected character:
224 RETURN or TAB
226 the function returns the information in the entry field.
227 The widget data exitType is set to vNORMAL.
228 ESCAPE the function returns a NULL pointer. The widget data exit‐
230 Type is set to vESCAPE_HIT.
231 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 moveCDKAlphalist
238 moves the given widget to the given position.
239 · The parameters xpos and ypos are the new position of the wid‐
241 get.
242 The parameter xpos may be an integer or one of the pre-defined
244 values TOP, BOTTOM, and CENTER.
245 The parameter ypos may be an integer, or one of the pre-
247 defined values LEFT, RIGHT, and CENTER.
248 · The parameter relative states whether the xpos/ypos pair is a
250 relative move or an absolute move.
251 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 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 newCDKAlphalist
263 creates a pointer to an alphalist widget. Parameters:
264 · screen is the screen you wish this widget to be placed
266 in.
267 · 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 · 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 · 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 · 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 · label is the string which will be displayed in the label
289 of the entry field.
290 · 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 · listSize tells the widget how large the word list is.
297 · fillerCharacter is the character which is to be displayed
299 in an empty space in the entry field.
300 · highlight is the attribute of the highlight bar in the
302 scrolling list.
303 · box is true if the widget should be drawn with a box
305 around it.
306 · shadow is true to turn the shadow on around this widget.
308 If the widget could not be created then a NULL pointer is
310 returned.
311 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 setCDKAlphalist
317 lets the programmer modify certain elements of an existing
318 alphalist widget.
319 The parameter names correspond to the same parameter names
321 listed in the newCDKAlphalist function.
322 setCDKAlphalistBackgroundAttrib
324 sets the background attribute of the widget.
325 The parameter attribute is a curses attribute, e.g., A_BOLD.
327 setCDKAlphalistBackgroundColor
329 sets the background color of the widget.
330 The parameter color is in the format of the Cdk format
332 strings. See cdk_display (3).
333 setCDKAlphalistBox
335 sets whether the widget will be drawn with a box around it.
336 setCDKAlphalistBoxAttribute
338 sets the attribute of the box.
339 setCDKAlphalistContents
341 sets the contents of the alphalist widget (note that it sorts
342 the caller's copy of the list).
343 setCDKAlphalistCurrentItem
345 set the current position in the scroll-widget.
346 setCDKAlphalistFillerChar
348 sets the character to use when drawing the entry field por‐
349 tion of the widget.
350 setCDKAlphalistHighlight
352 sets the attribute of the highlight bar of the scrolling list
353 portion of the widget.
354 setCDKAlphalistHorizontalChar
356 sets the horizontal drawing character for the box to the
357 given character.
358 setCDKAlphalistLLChar
360 sets the lower left hand corner of the widget's box to the
361 given character.
362 setCDKAlphalistLRChar
364 sets the lower right hand corner of the widget's box to the
365 given character.
366 setCDKAlphalistPostProcess
368 allows the user to have the widget call a function after the
369 key has been applied to the widget.
370 · The parameter function is the callback function.
372 · The parameter data points to data passed to the callback
374 function.
375 To learn more about post-processing see cdk_process [4m(3).
377 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 · The parameter function is the callback function.
383 · The parameter data points to data passed to the callback
385 function.
386 To learn more about pre-processing see cdk_process [4m(3).
388 setCDKAlphalistULChar
390 sets the upper left hand corner of the widget's box to the
391 given character.
392 setCDKAlphalistURChar
394 sets the upper right hand corner of the widget's box to the
395 given character.
396 setCDKAlphalistVerticalChar
398 sets the vertical drawing character for the box to the given
399 character.
400
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 ┌────────────────┬─────────────────────────────────────┐
409 │Key │ 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 └────────────────┴─────────────────────────────────────┘
443 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
444
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 cdk_alphalist(3)