1cdk_dialog(3) Library Functions Manual cdk_dialog(3)
2
6 cdk_dialog - curses dialog widget
7
9 cc [ flag ... ] file ... -lcdk [ library ... ]
10 #include <cdk.h>
12 int activateCDKDialog (
14 CDKDIALOG *dialog,
15 chtype * actions);
16 void destroyCDKDialog (
18 CDKDIALOG *dialog);
19 void drawCDKDialog (
21 CDKDIALOG *dialog,
22 boolean box);
23 void drawCDKDialogButtons (
25 CDKDIALOG *dialog);
26 void eraseCDKDialog (
28 CDKDIALOG *dialog);
29 boolean getCDKDialog (
31 CDKDIALOG *dialog);
32 boolean getCDKDialogBox (
34 CDKDIALOG *dialog);
35 chtype getCDKDialogHighlight (
37 CDKDIALOG *dialog);
38 boolean getCDKDialogSeparator (
40 CDKDIALOG *dialog);
41 int injectCDKDialog (
43 CDKDIALOG *dialog,
44 chtype input);
45 void moveCDKDialog (
47 CDKDIALOG *dialog,
48 int xpos,
49 int ypos,
50 boolean relative,
51 boolean refresh);
52 CDKDIALOG *newCDKDialog (
54 CDKSCREEN *cdkscreen,
55 int xpos,
56 int ypos,
57 CDK_CONST char ** message,
58 int rows,
59 CDK_CONST char ** buttons,
60 int buttonCount,
61 chtype highlight,
62 boolean separator,
63 boolean box,
64 boolean shadow);
65 void positionCDKDialog (
67 CDKDIALOG *dialog);
68 void setCDKDialogBox (
70 CDKDIALOG *dialog,
71 boolean boxWidget);
72 void setCDKDialog (
74 CDKDIALOG *dialog,
75 chtype highlight,
76 boolean separator,
77 boolean box);
78 void setCDKDialogBackgroundAttrib (
80 CDKDIALOG *dialog,
81 chtype attribute);
82 void setCDKDialogBackgroundColor (
84 CDKDIALOG *dialog,
85 const char * color);
86 void setCDKDialogBox (
88 CDKDIALOG *dialog,
89 boolean box);
90 void setCDKDialogBoxAttribute (
92 CDKDIALOG *dialog,
93 chtype character);
94 void setCDKDialogHighlight (
96 CDKDIALOG *dialog,
97 chtype highlight);
98 void setCDKDialogHorizontalChar (
100 CDKDIALOG *dialog,
101 chtype character);
102 void setCDKDialogLLChar (
104 CDKDIALOG *dialog,
105 chtype character);
106 void setCDKDialogLRChar (
108 CDKDIALOG *dialog,
109 chtype character);
110 void setCDKDialogPostProcess (
112 CDKDIALOG *dialog,
113 PROCESSFN callback,
114 void * data);
115 void setCDKDialogPreProcess (
117 CDKDIALOG *dialog,
118 PROCESSFN callback,
119 void * data);
120 void setCDKDialogSeparator (
122 CDKDIALOG *dialog,
123 boolean separator);
124 void setCDKDialogULChar (
126 CDKDIALOG *dialog,
127 chtype character);
128 void setCDKDialogURChar (
130 CDKDIALOG *dialog,
131 chtype character);
132 void setCDKDialogVerticalChar (
134 CDKDIALOG *dialog,
135 chtype character);
136
138 The Cdk dialog widget creates a dialog box with a message and a varied
139 number of buttons to choose from. The following functions create or
140 manipulate the Cdk dialog box widget.
141
143 activateCDKDialog
144 activates the dialog widget and lets the user interact with the
145 widget.
146 · The parameter dialog is a pointer to a non-NULL dialog widget.
148 · If the actions parameter is passed with a non-NULL value, the
150 characters in the array will be injected into the widget.
151 To activate the widget interactively pass in a NULL pointer
153 for actions.
154 If the character entered into this widget is RETURN or TAB then
156 this function will return a value from 0 to the number of buttons
157 -1, representing the button selected. It also sets the widget
158 data exitType to vNORMAL.
159 If the character entered into this widget was ESCAPE, then the
161 widget returns a value of -1 and the widget data exitType will be
162 set to vESCAPE_HIT.
163 destroyCDKDialog
165 removes the widget from the screen and frees memory the object
166 used.
167 drawCDKDialog
169 draws the dialog widget on the screen.
170 If the box parameter is true, the widget is drawn with a box.
172 drawCDKDialogButtons
174 draws the dialog buttons and the separation line.
175 eraseCDKDialog
177 removes the widget from the screen. This does NOT destroy the
178 widget.
179 getCDKDialog
181 returns true if the list will be drawn with a box around it.
182 getCDKDialogBox
184 returns true if the dialog will be drawn with a box around it.
185 getCDKDialogHighlight
187 returns the highlight attribute of the widget.
188 getCDKDialogSeparator
190 returns the state of the separator flag.
191 injectCDKDialog
193 injects a single character into the widget.
194 · The parameter dialog is a pointer to a non-NULL dialog widget.
196 · The parameter character is the character to inject into the
198 widget.
199 The return value and side-effect (setting the widget data exit‐
201 Type) depend upon the injected character:
202 RETURN or TAB
204 the function returns a value from zero to one less than the
205 number of buttons, representing the button selected. The
206 widget data exitType is set to vNORMAL.
207 ESCAPE the function returns -1. The widget data exitType is set
209 to vESCAPE_HIT.
210 Otherwise
212 unless modified by preprocessing, postprocessing or key
213 bindings, the function returns -1. The widget data exit‐
214 Type is set to vEARLY_EXIT.
215 moveCDKDialog
217 moves the given widget to the given position.
218 · The parameters xpos and ypos are the new position of the wid‐
220 get.
221 The parameter xpos may be an integer or one of the pre-defined
223 values TOP, BOTTOM, and CENTER.
224 The parameter ypos may be an integer or one of the pre-defined
226 values LEFT, RIGHT, and CENTER.
227 The parameter relative states whether the xpos/ypos pair is a
229 relative move or an absolute move.
230 For example, if xpos = 1 and ypos = 2 and relative = TRUE,
232 then the widget would move one row down and two columns right.
233 If the value of relative was FALSE, then the widget would move
234 to the position (1,2).
235 Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
237 relative = TRUE. (weird things may happen).
238 · The final parameter refresh is a boolean value which states
240 whether the widget will get refreshed after the move.
241 newCDKDialog
243 creates a dialog widget and returns a pointer to it. Parameters:
244 screen
246 is the screen you wish this widget to be placed in.
247 xpos controls the placement of the object along the horizontal
249 axis. It may be integer or one of the pre-defined values
250 LEFT, RIGHT, and CENTER.
251 ypos controls the placement of the object along the vertical axis.
253 It may be an integer or one of the pre-defined values TOP,
254 BOTTOM, and CENTER.
255 message
257 is the text to be displayed in the message region of the dia‐
258 log box.
259 rows is the number of elements in the message list.
261 buttons
263 is an array containing the button labels to be displayed on
264 the bottom of the dialog box.
265 buttonCount
267 is the number of elements in the buttons array.
268 highlight
270 is the attribute of the currently highlighted button.
271 box is true if the widget should be drawn with a box around it.
273 separator
275 is true if a separator line should be drawn between the mes‐
276 sage region and the buttons.
277 shadow
279 turns the shadow on or off around this widget.
280 If the widget could not be created then a NULL pointer is
282 returned.
283 positionCDKDialog
285 allows the user to move the widget around the screen via the cur‐
286 sor/keypad keys. See cdk_position (3) for key bindings.
287 setCDKDialogBox
289 sets whether the widget will be drawn with a box around it.
290 setCDKDialog
292 lets the programmer modify certain elements of an existing dialog
293 widget.
294 The parameter names correspond to the same parameter names listed
296 in the newCDKDialog function.
297 setCDKDialogBackgroundAttrib
299 sets the background attribute of the widget.
300 The parameter attribute is a curses attribute, e.g., A_BOLD.
302 setCDKDialogBackgroundColor
304 sets the background color of the widget.
305 The parameter color is in the format of the Cdk format strings.
307 See cdk_display (3). setCDKDialogBox sets the box attribute of
309 the dialog widget.
310 setCDKDialogBoxAttribute
312 function sets the attribute of the box.
313 setCDKDialogHighlight
315 sets the highlight attribute of the selected button.
316 setCDKDialogHorizontalChar
318 sets the horizontal drawing character for the box to the given
319 character.
320 setCDKDialogLLChar
322 sets the lower left hand corner of the widget's box to the given
323 character.
324 setCDKDialogLRChar
326 sets the lower right hand corner of the widget's box to the given
327 character.
328 setCDKDialogPreProcess
330 allows the user to have the widget call a function after a key is
331 hit and before the key is applied to the widget.
332 · The parameter function is the callback function.
334 · The parameter data is a pointer to void.
336 To learn more about pre-processing see cdk_process [4m(3).
338 setCDKDialogPostProcess
340 allows the user to have the widget call a function after the key
341 has been applied to the widget.
342 · The parameter function is the callback function.
344 · The parameter data points to data passed to the callback func‐
346 tion.
347 To learn more about post-processing see cdk_process [4m(3).
349 setCDKDialogSeparator
351 sets the boolean flag whether the widget will be drawn with the
352 separator bar between the buttons and the message area.
353 setCDKDialogULChar
355 function sets the upper left hand corner of the widget's box to
356 the given character.
357 setCDKDialogURChar
359 sets the upper right hand corner of the widget's box to the given
360 character.
361 setCDKDialogVerticalChar
363 sets the vertical drawing character for the box to the given char‐
364 acter.
365
367 When the widget is activated there are several default key bindings
368 which will help the user enter or manipulate the information quickly.
369 The following table outlines the keys and their actions for this wid‐
370 get.
371 ┌────────────────┬─────────────────────────────────────┐
373 │Key │ Action │
374 ├────────────────┼─────────────────────────────────────┤
375 ├────────────────┼─────────────────────────────────────┤
376 │Left Arrow │ Selects the button to the left of │
377 │ │ the current button. │
378 ├────────────────┼─────────────────────────────────────┤
379 │Right Arrow │ Selects the button to the right of │
380 │ │ the current button. │
381 ├────────────────┼─────────────────────────────────────┤
382 │Tab │ Selects the button to the right of │
383 │ │ the current button. │
384 ├────────────────┼─────────────────────────────────────┤
385 │Space │ Selects the button to the right of │
386 │ │ the current button. │
387 ├────────────────┼─────────────────────────────────────┤
388 │Return │ Exits the widget and returns the │
389 │ │ index of the selected button. This │
390 │ │ also sets the widget data exitType │
391 │ │ to vNORMAL. │
392 ├────────────────┼─────────────────────────────────────┤
393 │Tab │ Exits the widget and returns the │
394 │ │ index of the selected button. This │
395 │ │ also sets the widget data exitType │
396 │ │ to vNORMAL. │
397 ├────────────────┼─────────────────────────────────────┤
398 │Escape │ Exits the widget and returns -1. │
399 │ │ This also sets the widget data │
400 │ │ exitType to vESCAPE_HIT. │
401 ├────────────────┼─────────────────────────────────────┤
402 │Ctrl-L │ Refreshes the screen. │
403 └────────────────┴─────────────────────────────────────┘
405 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3),
406 cdk_process(3), cdk_screen(3)
407 cdk_dialog(3)