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 char * title,
61 char * label,
62 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 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 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 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. The parameter alphalist is a pointer to a non-NULL
159 alphalist widget. If the actions parameter is passed with a non-
160 NULL value, the characters in the array will be injected into the
161 widget. To activate the widget interactively pass in a NULL
162 pointer for actions. If the character entered into this widget is
163 RETURN then this function will return a char * of the information
164 which was typed in the field. If the TAB character is hit then
165 the widget will try to complete the word in the entry field. If
166 the widget is exited with the RETURN character then the widget
167 data exitType will be set to vNORMAL. If the widget was exited
168 with the ESCAPE key then the widget data exitType will be set to
169 vESCAPE_HIT and the widget returns NULL.
170 destroyCDKAlphalist
172 removes the widget from the screen and frees memory the object
173 used.
174 drawCDKAlphalist
176 draws the alphalist widget on the screen. If the box parameter is
177 true, the widget is drawn with a box.
178 eraseCDKAlphalist
180 removes the widget from the screen. This does NOT destroy the
181 widget.
182 getCDKAlphalistBox
184 returns true if the widget will be drawn with a box around it.
185 getCDKAlphalistContents
187 returns the contents of the alphalist.
188 getCDKAlphalistCurrentItem
190 returns the current position in the scroll-widget.
191 getCDKAlphalistFillerChar
193 returns the character being used as the filler character in the
194 entry field portion of the widget.
195 getCDKAlphalistHighlight
197 returns the attribute of the highlight bar of the scrolling list
198 portion of the widget.
199 injectCDKAlphalist
201 injects a single character into the widget (actually the entry
202 widget). The parameter alphalist is a pointer to a non-NULL
203 alphalist widget. The parameter character is the character to
204 inject into the widget. The return value and side-effect (setting
205 the widget data exitType) depend upon the injected character:
206 RETURN or TAB
208 the function returns the information in the entry field.
209 The widget data exitType is set to vNORMAL.
210 ESCAPE the function returns a NULL pointer. The widget data exit‐
212 Type is set to vESCAPE_HIT.
213 Otherwise
215 unless modified by preprocessing, postprocessing or key
216 bindings, the function returns a NULL pointer. The widget
217 data exitType is set to vEARLY_EXIT.
218 moveCDKAlphalist
220 moves the given widget to the given position. The parameters xpos
221 and ypos are the new position of the widget. The parameter xpos
222 may be an integer or one of the pre-defined values TOP, BOTTOM,
223 and CENTER. The parameter ypos may be an integer or one of the
224 pre-defined values LEFT, RIGHT, and CENTER. The parameter rela‐
225 tive states whether the xpos/ypos pair is a relative move or an
226 absolute move. For example, if xpos = 1 and ypos = 2 and relative
227 = TRUE, then the widget would move one row down and two columns
228 right. If the value of relative was FALSE then the widget would
229 move to the position (1,2). Do not use the values TOP, BOTTOM,
230 LEFT, RIGHT, or CENTER when relative = TRUE. (weird things may
231 happen). The final parameter refresh is a boolean value which
232 states whether the widget will get refreshed after the move.
233 newCDKAlphalist
235 creates a pointer to an alphalist widget. Parameters:
236 screen
238 is the screen you wish this widget to be placed in.
239 xpos controls the placement of the object along the horizontal
241 axis. This parameter can take an integer or one of the pre-
242 defined values LEFT, RIGHT, and CENTER.
243 ypos controls the placement of the object along the vertical axis.
245 This parameter may be an integer value or one of the pre-
246 defined values TOP, BOTTOM, and CENTER.
247 height and
249 width
251 control the height and width of the widget. If you provide a
252 value of zero for either of the height or the width, the wid‐
253 get will be created with the full width and height of the
254 screen. If you provide a negative value, the widget will be
255 created the full height or width minus the value provided.
256 title
258 is the string which will be displayed at the top of the
259 scrolling list. The title can be more than one line; just
260 provide a carriage return character at the line break.
261 label
263 is the string which will be displayed in the label of the
264 entry field.
265 list is the list of words which will be displayed in the scrolling
267 list. This list does not have to be sorted, this widget
268 automatically sorts the list (note that it modifies the call‐
269 er's copy of the list to do this).
270 listSize
272 tells the widget how large the word list is.
273 fillerCharacter
275 is the character which is to be displayed in an empty space
276 in the entry field.
277 highlight
279 is the attribute of the highlight bar in the scrolling list.
280 box is true if the widget should be drawn with a box around it.
282 shadow
284 is true to turn the shadow on around this widget.
285 If the widget could not be created then a NULL pointer is
287 returned.
288 positionCDKAlphalist
290 allows the user to move the widget around the screen via the cur‐
291 sor/keypad keys. See cdk_position (3) for key bindings.
292 setCDKAlphalist
294 lets the programmer modify certain elements of an existing alphal‐
295 ist widget. The parameter names correspond to the same parameter
296 names listed in the newCDKAlphalist function.
297 setCDKAlphalistBackgroundAttrib
299 sets the background attribute of the widget. The parameter
300 attribute is a curses attribute, e.g., A_BOLD.
301 setCDKAlphalistBackgroundColor
303 sets the background color of the widget. The parameter color is
304 in the format of the Cdk format strings. See cdk_display (3).
305 setCDKAlphalistBox
307 sets whether the widget will be drawn with a box around it.
308 setCDKAlphalistBoxAttribute
310 sets the attribute of the box.
311 setCDKAlphalistContents
313 sets the contents of the alphalist widget (note that it sorts the
314 caller's copy of the list).
315 setCDKAlphalistCurrentItem
317 set the current position in the scroll-widget.
318 setCDKAlphalistFillerChar
320 sets the character to use when drawing the entry field portion of
321 the widget.
322 setCDKAlphalistHighlight
324 sets the attribute of the highlight bar of the scrolling list por‐
325 tion of the widget.
326 setCDKAlphalistHorizontalChar
328 sets the horizontal drawing character for the box to the given
329 character.
330 setCDKAlphalistLLChar
332 sets the lower left hand corner of the widget's box to the given
333 character.
334 setCDKAlphalistLRChar
336 sets the lower right hand corner of the widget's box to the given
337 character.
338 setCDKAlphalistPostProcess
340 allows the user to have the widget call a function after the key
341 has been applied to the widget. The parameter function is the
342 callback function. The parameter data points to data passed to
343 the callback function. To learn more about post-processing see
344 cdk_process [4m(3).
345 setCDKAlphalistPreProcess
347 allows the user to have the widget call a function after a key is
348 hit and before the key is applied to the widget. The parameter
349 function is the callback function. The parameter data points to
350 data passed to the callback function. To learn more about pre-
351 processing see cdk_process [4m(3).
352 setCDKAlphalistULChar
354 sets the upper left hand corner of the widget's box to the given
355 character.
356 setCDKAlphalistURChar
358 sets the upper right hand corner of the widget's box to the given
359 character.
360 setCDKAlphalistVerticalChar
362 sets the vertical drawing character for the box to the given char‐
363 acter.
364
366 When the widget is activated there are several default key bindings
367 which will help the user enter or manipulate the information quickly.
368 Since this widget is built from both the scrolling list widget and the
369 entry field widget, the key bindings are the same for the respective
370 fields. The extra key bindings are listed below.
371 ┌────────────────┬─────────────────────────────────────┐
373 │Key │ Action │
374 ├────────────────┼─────────────────────────────────────┤
375 ├────────────────┼─────────────────────────────────────┤
376 │Up Arrow │ Scrolls the scrolling list up one │
377 │ │ line. │
378 ├────────────────┼─────────────────────────────────────┤
379 │Down Arrow │ Scrolls the scrolling list down one │
380 │ │ line. │
381 ├────────────────┼─────────────────────────────────────┤
382 │Page Up │ Scrolls the scrolling list up one │
383 │ │ page. │
384 ├────────────────┼─────────────────────────────────────┤
385 │CTRL-B │ Scrolls the scrolling list up one │
386 │ │ page. Page Down/Scrolls the │
387 │ │ scrolling list down one page. │
388 ├────────────────┼─────────────────────────────────────┤
389 │CTRL-F │ Scrolls the scrolling list down one │
390 │ │ page. │
391 ├────────────────┼─────────────────────────────────────┤
392 │Tab │ Tries to complete the word in the │
393 │ │ entry field. If the word segment │
394 │ │ is not unique then the widget will │
395 │ │ beep and present a list of close │
396 │ │ matches. │
397 ├────────────────┼─────────────────────────────────────┤
398 │Return │ Returns the word in the entry │
399 │ │ field. It also sets the widget │
400 │ │ data exitType to vNORMAL. │
401 ├────────────────┼─────────────────────────────────────┤
402 │Escape │ Exits the widget and returns a NULL │
403 │ │ pointer. It also sets the widget │
404 │ │ data exitType to vESCAPE_HIT. │
405 └────────────────┴─────────────────────────────────────┘
407 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
408
410 This widget is created from the scrolling list widget and the entry
411 field widget. This is a good example on how to build your own widgets
412 using the base widgets provided in this distribution.
413 cdk_alphalist(3)