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

NAME

6       cdk_dialog - curses dialog widget
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       int activateCDKDialog (
14                      CDKDIALOG *dialog,
15                      chtype * actions);
16
17       void destroyCDKDialog (
18                      CDKDIALOG *dialog);
19
20       void drawCDKDialog (
21                      CDKDIALOG *dialog,
22                      boolean box);
23
24       void drawCDKDialogButtons (
25                      CDKDIALOG *dialog);
26
27       void eraseCDKDialog (
28                      CDKDIALOG *dialog);
29
30       boolean getCDKDialog (
31                      CDKDIALOG *dialog);
32
33       boolean getCDKDialogBox (
34                      CDKDIALOG *dialog);
35
36       chtype getCDKDialogHighlight (
37                      CDKDIALOG *dialog);
38
39       boolean getCDKDialogSeparator (
40                      CDKDIALOG *dialog);
41
42       int injectCDKDialog (
43                      CDKDIALOG *dialog,
44                      chtype input);
45
46       void moveCDKDialog (
47                      CDKDIALOG *dialog,
48                      int xpos,
49                      int ypos,
50                      boolean relative,
51                      boolean refresh);
52
53       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
66       void positionCDKDialog (
67                      CDKDIALOG *dialog);
68
69       void setCDKDialogBox (
70                      CDKDIALOG *dialog,
71                      boolean boxWidget);
72
73       void setCDKDialog (
74                      CDKDIALOG *dialog,
75                      chtype highlight,
76                      boolean separator,
77                      boolean box);
78
79       void setCDKDialogBackgroundAttrib (
80                      CDKDIALOG *dialog,
81                      chtype attribute);
82
83       void setCDKDialogBackgroundColor (
84                      CDKDIALOG *dialog,
85                      const char * color);
86
87       void setCDKDialogBox (
88                      CDKDIALOG *dialog,
89                      boolean box);
90
91       void setCDKDialogBoxAttribute (
92                      CDKDIALOG *dialog,
93                      chtype character);
94
95       void setCDKDialogHighlight (
96                      CDKDIALOG *dialog,
97                      chtype highlight);
98
99       void setCDKDialogHorizontalChar (
100                      CDKDIALOG *dialog,
101                      chtype character);
102
103       void setCDKDialogLLChar (
104                      CDKDIALOG *dialog,
105                      chtype character);
106
107       void setCDKDialogLRChar (
108                      CDKDIALOG *dialog,
109                      chtype character);
110
111       void setCDKDialogPostProcess (
112                      CDKDIALOG *dialog,
113                      PROCESSFN callback,
114                      void * data);
115
116       void setCDKDialogPreProcess (
117                      CDKDIALOG *dialog,
118                      PROCESSFN callback,
119                      void * data);
120
121       void setCDKDialogSeparator (
122                      CDKDIALOG *dialog,
123                      boolean separator);
124
125       void setCDKDialogULChar (
126                      CDKDIALOG *dialog,
127                      chtype character);
128
129       void setCDKDialogURChar (
130                      CDKDIALOG *dialog,
131                      chtype character);
132
133       void setCDKDialogVerticalChar (
134                      CDKDIALOG *dialog,
135                      chtype character);
136

DESCRIPTION

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

AVAILABLE FUNCTIONS

143       activateCDKDialog
144            activates  the  dialog  widget and lets the user interact with the
145            widget.
146
147            ·   The parameter dialog is a pointer to a non-NULL dialog widget.
148
149            ·   If the actions parameter is passed with a non-NULL value,  the
150                characters in the array will be injected into the widget.
151
152                To  activate  the  widget interactively pass in a NULL pointer
153                for actions.
154
155            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
160            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
164       destroyCDKDialog
165            removes  the  widget  from  the screen and frees memory the object
166            used.
167
168       drawCDKDialog
169            draws the dialog widget on the screen.
170
171            If the box parameter is true, the widget is drawn with a box.
172
173       drawCDKDialogButtons
174            draws the dialog buttons and the separation line.
175
176       eraseCDKDialog
177            removes the widget from the screen.  This  does  NOT  destroy  the
178            widget.
179
180       getCDKDialog
181            returns true if the list will be drawn with a box around it.
182
183       getCDKDialogBox
184            returns true if the dialog will be drawn with a box around it.
185
186       getCDKDialogHighlight
187            returns the highlight attribute of the widget.
188
189       getCDKDialogSeparator
190            returns the state of the separator flag.
191
192       injectCDKDialog
193            injects a single character into the widget.
194
195            ·   The parameter dialog is a pointer to a non-NULL dialog widget.
196
197            ·   The  parameter  character  is the character to inject into the
198                widget.
199
200            The return value and side-effect (setting the  widget  data  exit‐
201            Type) depend upon the injected character:
202
203            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
208            ESCAPE the  function  returns -1.  The widget data exitType is set
209                   to vESCAPE_HIT.
210
211            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
216       moveCDKDialog
217            moves the given widget to the given position.
218
219            ·   The parameters xpos and ypos are the new position of the  wid‐
220                get.
221
222                The parameter xpos may be an integer or one of the pre-defined
223                values TOP, BOTTOM, and CENTER.
224
225                The parameter ypos may be an integer or one of the pre-defined
226                values LEFT, RIGHT, and CENTER.
227
228                The  parameter relative states whether the xpos/ypos pair is a
229                relative move or an absolute move.
230
231                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
236                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
237                relative = TRUE.  (weird things may happen).
238
239            ·   The final parameter refresh is a boolean  value  which  states
240                whether the widget will get refreshed after the move.
241
242       newCDKDialog
243            creates a dialog widget and returns a pointer to it.  Parameters:
244
245            screen
246                 is the screen you wish this widget to be placed in.
247
248            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
252            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
256            message
257                 is the text to be displayed in the message region of the dia‐
258                 log box.
259
260            rows is the number of elements in the message list.
261
262            buttons
263                 is an array containing the button labels to be  displayed  on
264                 the bottom of the dialog box.
265
266            buttonCount
267                 is the number of elements in the buttons array.
268
269            highlight
270                 is the attribute of the currently highlighted button.
271
272            box  is true if the widget should be drawn with a box around it.
273
274            separator
275                 is  true if a separator line should be drawn between the mes‐
276                 sage region and the buttons.
277
278            shadow
279                 turns the shadow on or off around this widget.
280
281            If the widget  could  not  be  created  then  a  NULL  pointer  is
282            returned.
283
284       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
288       setCDKDialogBox
289            sets whether the widget will be drawn with a box around it.
290
291       setCDKDialog
292            lets the programmer modify certain elements of an existing  dialog
293            widget.
294
295            The  parameter names correspond to the same parameter names listed
296            in the newCDKDialog function.
297
298       setCDKDialogBackgroundAttrib
299            sets the background attribute of the widget.
300
301            The parameter attribute is a curses attribute, e.g., A_BOLD.
302
303       setCDKDialogBackgroundColor
304            sets the background color of the widget.
305
306            The parameter color is in the format of the Cdk format strings.
307
308            See cdk_display (3).  setCDKDialogBox sets the  box  attribute  of
309            the dialog widget.
310
311       setCDKDialogBoxAttribute
312            function sets the attribute of the box.
313
314       setCDKDialogHighlight
315            sets the highlight attribute of the selected button.
316
317       setCDKDialogHorizontalChar
318            sets  the  horizontal  drawing  character for the box to the given
319            character.
320
321       setCDKDialogLLChar
322            sets the lower left hand corner of the widget's box to  the  given
323            character.
324
325       setCDKDialogLRChar
326            sets  the lower right hand corner of the widget's box to the given
327            character.
328
329       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
333            ·   The parameter function is the callback function.
334
335            ·   The parameter data is a pointer to void.
336
337            To learn more about pre-processing see cdk_process (3).
338
339       setCDKDialogPostProcess
340            allows  the  user to have the widget call a function after the key
341            has been applied to the widget.
342
343            ·   The parameter function is the callback function.
344
345            ·   The parameter data points to data passed to the callback func‐
346                tion.
347
348            To learn more about post-processing see cdk_process (3).
349
350       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
354       setCDKDialogULChar
355            function sets the upper left hand corner of the  widget's  box  to
356            the given character.
357
358       setCDKDialogURChar
359            sets  the upper right hand corner of the widget's box to the given
360            character.
361
362       setCDKDialogVerticalChar
363            sets the vertical drawing character for the box to the given char‐
364            acter.
365

KEY BINDINGS

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
372               ┌────────────────┬─────────────────────────────────────┐
373Key             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               └────────────────┴─────────────────────────────────────┘

SEE ALSO

405       cdk(3),      cdk_binding(3),      cdk_display(3),      cdk_position(3),
406       cdk_process(3), cdk_screen(3)
407
408
409
410                                                                 cdk_dialog(3)
Impressum