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.  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
156       destroyCDKDialog
157            removes  the  widget  from  the screen and frees memory the object
158            used.
159
160       drawCDKDialog
161            draws the dialog widget on the screen.  If the  box  parameter  is
162            true, the widget is drawn with a box.
163
164       drawCDKDialogButtons
165            draws the dialog buttons and the separation line.
166
167       eraseCDKDialog
168            removes  the  widget  from  the screen.  This does NOT destroy the
169            widget.
170
171       getCDKDialog
172            returns true if the list will be drawn with a box around it.
173
174       getCDKDialogBox
175            returns true if the dialog will be drawn with a box around it.
176
177       getCDKDialogHighlight
178            returns the highlight attribute of the widget.
179
180       getCDKDialogSeparator
181            returns the state of the separator flag.
182
183       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
190            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
195            ESCAPE the function returns -1.  The widget data exitType  is  set
196                   to vESCAPE_HIT.
197
198            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
203       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
218       newCDKDialog
219            creates a dialog widget and returns a pointer to it.  Parameters:
220
221            screen
222                 is the screen you wish this widget to be placed in.
223
224            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
228            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
232            message
233                 is the text to be displayed in the message region of the dia‐
234                 log box.
235
236            rows is the number of elements in the message list.
237
238            buttons
239                 is an array containing the button labels to be  displayed  on
240                 the bottom of the dialog box.
241
242            buttonCount
243                 is the number of elements in the buttons array.
244
245            highlight
246                 is the attribute of the currently highlighted button.
247
248            box  is true if the widget should be drawn with a box around it.
249
250            separator
251                 is  true if a separator line should be drawn between the mes‐
252                 sage region and the buttons.
253
254            shadow
255                 turns the shadow on or off around this widget.
256
257            If the widget  could  not  be  created  then  a  NULL  pointer  is
258            returned.
259
260       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
264       setCDKDialogBox
265            sets whether the widget will be drawn with a box around it.
266
267       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
272       setCDKDialogBackgroundAttrib
273            sets the  background  attribute  of  the  widget.   The  parameter
274            attribute is a curses attribute, e.g., A_BOLD.
275
276       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
281       setCDKDialogBoxAttribute
282            function sets the attribute of the box.
283
284       setCDKDialogHighlight
285            sets the highlight attribute of the selected button.
286
287       setCDKDialogHorizontalChar
288            sets  the  horizontal  drawing  character for the box to the given
289            character.
290
291       setCDKDialogLLChar
292            sets the lower left hand corner of the widget's box to  the  given
293            character.
294
295       setCDKDialogLRChar
296            sets  the lower right hand corner of the widget's box to the given
297            character.
298
299       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 (3).
305
306       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 (3).
312
313       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
317       setCDKDialogULChar
318            function  sets  the  upper left hand corner of the widget's box to
319            the given character.
320
321       setCDKDialogURChar
322            sets the upper right hand corner of the widget's box to the  given
323            character.
324
325       setCDKDialogVerticalChar
326            sets the vertical drawing character for the box to the given char‐
327            acter.
328

KEY BINDINGS

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

SEE ALSO

368       cdk(3),      cdk_binding(3),      cdk_display(3),      cdk_position(3),
369       cdk_process(3), cdk_screen(3)
370
371
372
373                                                                 cdk_dialog(3)
Impressum