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. The parameter dialog is a pointer to a non-NULL dialog
146 widget. If the actions parameter is passed with a non-NULL value,
147 the characters in the array will be injected into the widget. To
148 activate the widget interactively pass in a NULL pointer for
149 actions. If the character entered into this widget is RETURN or
150 TAB then this function will return a value from 0 to the number of
151 buttons -1, representing the button selected. It also sets the
152 widget data exitType to vNORMAL. If the character entered into
153 this widget was ESCAPE then the widget returns a value of -1 and
154 the widget data exitType will be set to vESCAPE_HIT.
155 destroyCDKDialog
157 removes the widget from the screen and frees memory the object
158 used.
159 drawCDKDialog
161 draws the dialog widget on the screen. If the box parameter is
162 true, the widget is drawn with a box.
163 drawCDKDialogButtons
165 draws the dialog buttons and the separation line.
166 eraseCDKDialog
168 removes the widget from the screen. This does NOT destroy the
169 widget.
170 getCDKDialog
172 returns true if the list will be drawn with a box around it.
173 getCDKDialogBox
175 returns true if the dialog will be drawn with a box around it.
176 getCDKDialogHighlight
178 returns the highlight attribute of the widget.
179 getCDKDialogSeparator
181 returns the state of the separator flag.
182 injectCDKDialog
184 injects a single character into the widget. The parameter dialog
185 is a pointer to a non-NULL dialog widget. The parameter character
186 is the character to inject into the widget. The return value and
187 side-effect (setting the widget data exitType) depend upon the
188 injected character:
189 RETURN or TAB
191 the function returns a value from zero to one less than the
192 number of buttons, representing the button selected. The
193 widget data exitType is set to vNORMAL.
194 ESCAPE the function returns -1. The widget data exitType is set
196 to vESCAPE_HIT.
197 Otherwise
199 unless modified by preprocessing, postprocessing or key
200 bindings, the function returns -1. The widget data exit‐
201 Type is set to vEARLY_EXIT.
202 moveCDKDialog
204 moves the given widget to the given position. The parameters xpos
205 and ypos are the new position of the widget. The parameter xpos
206 may be an integer or one of the pre-defined values TOP, BOTTOM,
207 and CENTER. The parameter ypos may be an integer or one of the
208 pre-defined values LEFT, RIGHT, and CENTER. The parameter rela‐
209 tive states whether the xpos/ypos pair is a relative move or an
210 absolute move. For example, if xpos = 1 and ypos = 2 and relative
211 = TRUE, then the widget would move one row down and two columns
212 right. If the value of relative was FALSE then the widget would
213 move to the position (1,2). Do not use the values TOP, BOTTOM,
214 LEFT, RIGHT, or CENTER when relative = TRUE. (weird things may
215 happen). The final parameter refresh is a boolean value which
216 states whether the widget will get refreshed after the move.
217 newCDKDialog
219 creates a dialog widget and returns a pointer to it. Parameters:
220 screen
222 is the screen you wish this widget to be placed in.
223 xpos controls the placement of the object along the horizontal
225 axis. It may be integer or one of the pre-defined values
226 LEFT, RIGHT, and CENTER.
227 ypos controls the placement of the object along the vertical axis.
229 It may be an integer or one of the pre-defined values TOP,
230 BOTTOM, and CENTER.
231 message
233 is the text to be displayed in the message region of the dia‐
234 log box.
235 rows is the number of elements in the message list.
237 buttons
239 is an array containing the button labels to be displayed on
240 the bottom of the dialog box.
241 buttonCount
243 is the number of elements in the buttons array.
244 highlight
246 is the attribute of the currently highlighted button.
247 box is true if the widget should be drawn with a box around it.
249 separator
251 is true if a separator line should be drawn between the mes‐
252 sage region and the buttons.
253 shadow
255 turns the shadow on or off around this widget.
256 If the widget could not be created then a NULL pointer is
258 returned.
259 positionCDKDialog
261 allows the user to move the widget around the screen via the cur‐
262 sor/keypad keys. See cdk_position (3) for key bindings.
263 setCDKDialogBox
265 sets whether the widget will be drawn with a box around it.
266 setCDKDialog
268 lets the programmer modify certain elements of an existing dialog
269 widget. The parameter names correspond to the same parameter
270 names listed in the newCDKDialog function.
271 setCDKDialogBackgroundAttrib
273 sets the background attribute of the widget. The parameter
274 attribute is a curses attribute, e.g., A_BOLD.
275 setCDKDialogBackgroundColor
277 sets the background color of the widget. The parameter color is
278 in the format of the Cdk format strings. See cdk_display (3).
279 setCDKDialogBox sets the box attribute of the dialog widget.
280 setCDKDialogBoxAttribute
282 function sets the attribute of the box.
283 setCDKDialogHighlight
285 sets the highlight attribute of the selected button.
286 setCDKDialogHorizontalChar
288 sets the horizontal drawing character for the box to the given
289 character.
290 setCDKDialogLLChar
292 sets the lower left hand corner of the widget's box to the given
293 character.
294 setCDKDialogLRChar
296 sets the lower right hand corner of the widget's box to the given
297 character.
298 setCDKDialogPreProcess
300 allows the user to have the widget call a function after a key is
301 hit and before the key is applied to the widget. The parameter
302 function is the callback function. The parameter data is a
303 pointer to void. To learn more about pre-processing see
304 cdk_process [4m(3).
305 setCDKDialogPostProcess
307 allows the user to have the widget call a function after the key
308 has been applied to the widget. The parameter function is the
309 callback function. The parameter data points to data passed to
310 the callback function. To learn more about post-processing see
311 cdk_process [4m(3).
312 setCDKDialogSeparator
314 sets the boolean flag whether the widget will be drawn with the
315 separator bar between the buttons and the message area.
316 setCDKDialogULChar
318 function sets the upper left hand corner of the widget's box to
319 the given character.
320 setCDKDialogURChar
322 sets the upper right hand corner of the widget's box to the given
323 character.
324 setCDKDialogVerticalChar
326 sets the vertical drawing character for the box to the given char‐
327 acter.
328
330 When the widget is activated there are several default key bindings
331 which will help the user enter or manipulate the information quickly.
332 The following table outlines the keys and their actions for this wid‐
333 get.
334 ┌────────────────┬─────────────────────────────────────┐
336 │Key │ Action │
337 ├────────────────┼─────────────────────────────────────┤
338 ├────────────────┼─────────────────────────────────────┤
339 │Left Arrow │ Selects the button to the left of │
340 │ │ the current button. │
341 ├────────────────┼─────────────────────────────────────┤
342 │Right Arrow │ Selects the button to the right of │
343 │ │ the current button. │
344 ├────────────────┼─────────────────────────────────────┤
345 │Tab │ Selects the button to the right of │
346 │ │ the current button. │
347 ├────────────────┼─────────────────────────────────────┤
348 │Space │ Selects the button to the right of │
349 │ │ the current button. │
350 ├────────────────┼─────────────────────────────────────┤
351 │Return │ Exits the widget and returns the │
352 │ │ index of the selected button. This │
353 │ │ also sets the widget data exitType │
354 │ │ to vNORMAL. │
355 ├────────────────┼─────────────────────────────────────┤
356 │Tab │ Exits the widget and returns the │
357 │ │ index of the selected button. This │
358 │ │ also sets the widget data exitType │
359 │ │ to vNORMAL. │
360 ├────────────────┼─────────────────────────────────────┤
361 │Escape │ Exits the widget and returns -1. │
362 │ │ This also sets the widget data │
363 │ │ exitType to vESCAPE_HIT. │
364 ├────────────────┼─────────────────────────────────────┤
365 │Ctrl-L │ Refreshes the screen. │
366 └────────────────┴─────────────────────────────────────┘
368 cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3),
369 cdk_process(3), cdk_screen(3)
370 cdk_dialog(3)