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

NAME

6       cdk_button - create and manage a curses button widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       typedef void (*tButtonCallback)(struct SButton *button);
14
15       int activateCDKButton (
16                      CDKBUTTON *button,
17                      chtype * actions);
18
19       void destroyCDKButton (
20                      CDKBUTTON *button);
21
22       void drawCDKButton (
23                      CDKBUTTON *b,
24                      boolean box);
25
26       void eraseCDKButton (
27                      CDKBUTTON *button);
28
29       boolean getCDKButtonBox (
30                      CDKBUTTON *b);
31
32       chtype *getCDKButtonMessage (
33                      CDKBUTTON *b);
34
35       int injectCDKButtonbox (
36                      CDKBUTTON *buttonbox,
37                      chtype input);
38
39       CDKBUTTON *newCDKButton(
40                      CDKSCREEN *cdkscreen,
41                      int xpos,
42                      int ypos,
43                      const char *message,
44                      tButtonCallback callback,
45                      boolean box,
46                      boolean shadow);
47
48       void setCDKButton(
49                      CDKBUTTON *b,
50                      const char *message,
51                      boolean box);
52
53       void setCDKButtonBackgroundAttrib (
54                      CDKBUTTON *b,
55                      chtype attribute);
56
57       void setCDKButtonBackgroundColor (
58                      CDKBUTTON *b,
59                      const char * color);
60
61       void setCDKButtonBox (
62                      CDKBUTTON *button,
63                      boolean box);
64
65       void setCDKButtonBoxAttribute (
66                      CDKBUTTON *b,
67                      chtype c);
68
69       void setCDKButtonHorizontalChar (
70                      CDKBUTTON *b,
71                      chtype c);
72
73       void setCDKButtonLLChar (
74                      CDKBUTTON *b,
75                      chtype c);
76
77       void setCDKButtonLRChar (
78                      CDKBUTTON *b,
79                      chtype c);
80
81       void setCDKButtonMessage (
82                      CDKBUTTON *b,
83                      const char *message);
84
85       void setCDKButtonULChar (
86                      CDKBUTTON *b,
87                      chtype c);
88
89       void setCDKButtonURChar (
90                      CDKBUTTON *b,
91                      chtype c);
92
93       void setCDKButtonVerticalChar (
94                      CDKBUTTON *b,
95                      chtype c);
96
97       void moveCDKButton(
98                      CDKBUTTON *b,
99                      int xpos,
100                      int ypos,
101                      boolean relative,
102                      boolean refresh);
103
104       void positionCDKButton (
105                      CDKBUTTON *b);
106
107       void waitCDKButton (
108                      CDKBUTTON *button,
109                      char key);
110

DESCRIPTION

112       The Cdk button widget displays a message string and executes a callback
113       when the user presses enter or space.  As such, it is only useful on  a
114       screen  that  is being managed by some external screen traversal engine
115       such as traverseCDKScreen().  The button will be highlighted  when  the
116       widget has the focus.  The following functions create or manipulate the
117       Cdk button widget.
118

AVAILABLE FUNCTIONS

120       activateCDKButton
121            activates the button widget and lets the user  interact  with  the
122            widget.
123
124            ·   The parameter button is a pointer to a non-NULL button widget.
125
126            ·   If  the actions parameter is passed with a non-NULL value, the
127                characters in the array will be injected into the widget.
128
129                To activate the widget interactively pass in  a  NULL  pointer
130                for actions.
131
132            If  the  character  entered into this widget is RETURN or TAB then
133            this function will return a value from 0 to the number of  buttons
134            -1, representing the button selected.  It will also set the widget
135            data exitType to vNORMAL.
136
137            If the character entered into this widget was ESCAPE then the wid‐
138            get will return a value of -1 and the widget data exitType will be
139            set to vESCAPE_HIT.
140
141       destroyCDKButton
142            removes the widget from the screen and frees  up  any  memory  the
143            object used.
144
145       drawCDKButton
146            draws the button widget on the screen.
147
148            If the box parameter is true, the widget is drawn with a box.
149
150       eraseCDKButton
151            removes  the  widget  from  the screen.  This does NOT destroy the
152            widget.
153
154       getCDKButtonBox
155            returns true if the widget will be drawn with a box around it.
156
157       getCDKButtonMessage
158            returns the contents of the button widget.
159
160       injectCDKButton
161            injects a single character into the widget.
162
163            ·   The parameter button is a pointer to a non-NULL button widget.
164
165            ·   The parameter character is the character to  inject  into  the
166                widget.
167
168            The  return  value  and side-effect (setting the widget data exit‐
169            Type) depend upon the injected character:
170
171            RETURN or TAB
172                   this function returns 0, representing the button  selected.
173                   The widget data exitType is set to vNORMAL.
174
175            ESCAPE the  function  returns -1.  The widget data exitType is set
176                   to vESCAPE_HIT.
177
178            Otherwise
179                   unless modified by  preprocessing,  postprocessing  or  key
180                   bindings,  the  function returns -1.  The widget data exit‐
181                   Type is set to vEARLY_EXIT.
182
183       moveCDKButton
184            moves the given widget to the given position.
185
186            ·   The parameters xpos and ypos are the new position of the  wid‐
187                get.
188
189                The parameter xpos may be an integer or one of the pre-defined
190                values TOP, BOTTOM, and CENTER.
191
192                The parameter ypos may be an integer or one of the pre-defined
193                values LEFT, RIGHT, and CENTER.
194
195                The  parameter relative states whether the xpos/ypos pair is a
196                relative move or an absolute move.
197
198                For example, if xpos = 1 and ypos = 2  and  relative  =  TRUE,
199                then the widget would move one row down and two columns right.
200                If the value of relative was FALSE, then the widget would move
201                to the position (1,2).
202
203                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
204                relative = TRUE.  (weird things may happen).
205
206            ·   The final parameter refresh is a boolean  value  which  states
207                whether the widget will get refreshed after the move.
208
209       newCDKButton
210            creates a pointer to a buttonbox widget.  Parameters:
211
212            ·   The  screen parameter is the screen you wish this widget to be
213                placed in.
214
215            ·   xpos controls the placement of the object along the horizontal
216                axis.   It  may be an integer or one of the pre-defined values
217                LEFT, RIGHT, and CENTER.
218
219            ·   ypos controls the placement of the object along  the  vertical
220                axis.   It be an integer or one of the pre-defined values TOP,
221                BOTTOM, and CENTER.
222
223            ·   message is the message to display in the button  window,  for‐
224                matted as described in cdk_display.
225
226            ·   callback  is  an  optional pointer to a callback function that
227                will be executed when the user activates the button by  press‐
228                ing space or enter.
229
230            ·   box  is  true  if the widget should be drawn with a box around
231                it.
232
233            ·   shadow turns the shadow on or off around this widget.
234
235            If the widget  could  not  be  created  then  a  NULL  pointer  is
236            returned.
237
238       positionCDKButton
239            allows  the user to move the widget around the screen via the cur‐
240            sor/keypad keys.  See cdk_position (3) for key bindings.
241
242       setCDKButton
243            lets the programmer modify certain elements of an existing button‐
244            box widget.
245
246            The  parameter names correspond to the same parameter names listed
247            in the newCDKButton function.
248
249       setCDKButtonBackgroundAttrib
250            sets the background attribute of the widget.
251
252            The parameter attribute is a curses attribute, e.g., A_BOLD.
253
254       setCDKButtonBackgroundColor
255            sets the background color of the widget.
256
257            The parameter color is in the format of the  Cdk  format  strings.
258            (See cdk_display).
259
260       setCDKButtonBox
261            sets true if the widget will be drawn with a box around it.
262
263       setCDKButtonBoxAttribute
264            sets the attribute of the box.
265
266       setCDKButtonHorizontalChar
267            sets  the  horizontal  drawing  character for the box to the given
268            character.
269
270       setCDKButtonLLChar
271            sets the lower left hand corner of the widget's box to  the  given
272            character.
273
274       setCDKButtonLRChar
275            sets  the lower right hand corner of the widget's box to the given
276            character.
277
278       setCDKButtonMessage
279            This sets the contents of the label widget.
280
281       setCDKButtonULChar
282            sets the upper left hand corner of the widget's box to  the  given
283            character.
284
285       setCDKButtonURChar
286            sets  the upper right hand corner of the widget's box to the given
287            character.
288
289       setCDKButtonVerticalChar
290            sets the vertical drawing character for the box to the given char‐
291            acter.
292

BUGS

294       Changing  the  Box attribute after the widget has been created probably
295       does not work right.  None of the positioning/movement  code  has  been
296       tested.
297

AUTHOR

299       Grant Edwards, Aspen Research Corporation
300

SEE ALSO

302       cdk(3),      cdk_binding(3),      cdk_display(3),      cdk_position(3),
303       cdk_process(3), cdk_screen(3), cdk_traverse(3)
304
305
306
307                                                                 cdk_button(3)
Impressum