NAME¶
cdk_button - create and manage a curses button widget.
SYNOPSIS¶
cc [
flag ... ]
file ...
-lcdk [
library ...
]
#include <cdk.h>
typedef void (*tButtonCallback)(struct SButton *button);
- int activateCDKButton (
-
CDKBUTTON *button,
chtype * actions);
- void destroyCDKButton (
-
CDKBUTTON *button);
- void drawCDKButton (
-
CDKBUTTON *b,
boolean box);
- void eraseCDKButton (
-
CDKBUTTON *button);
- boolean getCDKButtonBox (
-
CDKBUTTON *b);
- chtype *getCDKButtonMessage (
-
CDKBUTTON *b);
- int injectCDKButtonbox (
-
CDKBUTTON *buttonbox,
chtype input);
- CDKBUTTON *newCDKButton(
-
CDKSCREEN *cdkscreen,
int xpos,
int ypos,
char *message,
tButtonCallback callback,
boolean box,
boolean shadow);
- void setCDKButton(
-
CDKBUTTON *b,
char *message,
boolean box);
- void setCDKButtonBackgroundAttrib (
-
CDKBUTTON *b,
chtype attribute);
- void setCDKButtonBackgroundColor (
-
CDKBUTTON *b,
char * color);
- void setCDKButtonBox (
-
CDKBUTTON *button,
boolean box);
- void setCDKButtonBoxAttribute (
-
CDKBUTTON *b,
chtype c);
- void setCDKButtonHorizontalChar (
-
CDKBUTTON *b,
chtype c);
- void setCDKButtonLLChar (
-
CDKBUTTON *b,
chtype c);
- void setCDKButtonLRChar (
-
CDKBUTTON *b,
chtype c);
- void setCDKButtonMessage (
-
CDKBUTTON *b,
char *message);
- void setCDKButtonULChar (
-
CDKBUTTON *b,
chtype c);
- void setCDKButtonURChar (
-
CDKBUTTON *b,
chtype c);
- void setCDKButtonVerticalChar (
-
CDKBUTTON *b,
chtype c);
- void moveCDKButton(
-
CDKBUTTON *b,
int xpos,
int ypos,
boolean relative,
boolean refresh);
- void positionCDKButton (
-
CDKBUTTON *b);
- void waitCDKButton (
-
CDKBUTTON *button,
char key);
DESCRIPTION¶
The Cdk button widget displays a message string and executes a callback when the
user presses enter or space. As such, it is only useful on a screen that is
being managed by some external screen traversal engine such as
traverseCDKScreen(). The button will be highlighted when the widget has
the focus. The following functions create or manipulate the Cdk button widget.
AVAILABLE FUNCTIONS¶
- activateCDKButton
- activates the button widget and lets the user interact with
the widget. The parameter button is a pointer to a non-NULL button
widget. If the actions parameter is passed with a non-NULL value,
the characters in the array will be injected into the widget. To activate
the widget interactively pass in a NULL pointer for actions.
If the character entered into this widget is RETURN or TAB
then this function will return a value from 0 to the number of buttons -1,
representing the button selected. It will also set the widget data
exitType to vNORMAL. If the character entered into this
widget was ESCAPE then the widget will return a value of -1 and the
widget data exitType will be set to vESCAPE_HIT.
- destroyCDKButton
- removes the widget from the screen and frees up any memory
the object used.
- drawCDKButton
- draws the button widget on the screen. If the box
parameter is true, the widget is drawn with a box.
- eraseCDKButton
- removes the widget from the screen. This does NOT
destroy the widget.
- getCDKButtonBox
- returns true if the widget will be drawn with a box around
it.
- getCDKButtonMessage
- returns the contents of the button widget.
- injectCDKButton
- injects a single character into the widget. The parameter
button is a pointer to a non-NULL button widget. The parameter
character is the character to inject into the widget. The return
value and side-effect (setting the widget data exitType) depend
upon the injected character:
- RETURN or TAB
- this function returns 0, representing the button selected.
The widget data exitType is set to vNORMAL.
- ESCAPE
- the function returns -1. The widget data exitType is
set to vESCAPE_HIT.
- Otherwise
- unless modified by preprocessing, postprocessing or key
bindings, the function returns -1. The widget data exitType is set
to vEARLY_EXIT.
- moveCDKButton
- moves the given widget to the given position. The
parameters xpos and ypos are the new position of the widget.
The parameter xpos may be an integer or one of the pre-defined
values TOP, BOTTOM, and CENTER. The parameter
ypos may be an integer or one of the pre-defined values
LEFT, RIGHT, and CENTER. The parameter
relative states whether the xpos/ypos pair is a
relative move or an absolute move. For example, if xpos = 1 and
ypos = 2 and relative = TRUE, then the widget would
move one row down and two columns right. If the value of relative
was FALSE then the widget would move to the position (1,2). Do not
use the values TOP, BOTTOM, LEFT, RIGHT, or
CENTER when relative = TRUE. (weird things may
happen). The final parameter refresh is a boolean value which
states whether the widget will get refreshed after the move.
- newCDKButton
- creates a pointer to a buttonbox widget. Parameters:
- The screen parameter
- is the screen you wish this widget to be placed in.
- xpos
- controls the placement of the object along the horizontal
axis. It may be an integer or one of the pre-defined values LEFT,
RIGHT, and CENTER.
- ypos
- controls the placement of the object along the vertical
axis. It be an integer or one of the pre-defined values TOP,
BOTTOM, and CENTER.
- message
- is the message to display in the button window, formatted
as described in cdk_display.
- callback
- is an optional pointer to a callback function that will be
executed when the user activates the button by pressing space or
enter.
- box
- is true if the widget should be drawn with a box around
it.
- shadow
- turns the shadow on or off around this widget.
- If the widget could not be created then a NULL
pointer is returned.
- positionCDKButton
- allows the user to move the widget around the screen via
the cursor/keypad keys. See cdk_position (3) for key bindings.
- setCDKButton
- lets the programmer modify certain elements of an existing
buttonbox widget. The parameter names correspond to the same parameter
names listed in the newCDKButton function.
- setCDKButtonBackgroundAttrib
- sets the background attribute of the widget. The parameter
attribute is a curses attribute, e.g., A_BOLD.
- setCDKButtonBackgroundColor
- sets the background color of the widget. The parameter
color is in the format of the Cdk format strings. (See
cdk_display).
- setCDKButtonBox
- sets true if the widget will be drawn with a box around
it.
- setCDKButtonBoxAttribute
- sets the attribute of the box.
- setCDKButtonHorizontalChar
- sets the horizontal drawing character for the box to the
given character.
- setCDKButtonLLChar
- sets the lower left hand corner of the widget's box to the
given character.
- setCDKButtonLRChar
- sets the lower right hand corner of the widget's box to the
given character.
- setCDKButtonMessage
- This sets the contents of the label widget.
- setCDKButtonULChar
- sets the upper left hand corner of the widget's box to the
given character.
- setCDKButtonURChar
- sets the upper right hand corner of the widget's box to the
given character.
- setCDKButtonVerticalChar
- sets the vertical drawing character for the box to the
given character.
BUGS¶
Changing the Box attribute after the widget has been created probably does not
work right. None of the positioning/movement code has been tested.
AUTHOR¶
Grant Edwards, Aspen Research Corporation
SEE ALSO¶
cdk(3),
cdk_binding(3),
cdk_display(3),
cdk_position(3),
cdk_process(3),
cdk_screen(3),
cdk_traverse(3)