--- name: "cdk_button" section: "3" platform: "linux" package: "libcdk5-dev" version: "5.0.20250116-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/cdk_button" --- # cdk\_button(3) create and manage a Cdk button widget ## NAME cdk\_button - create and manage a *Cdk* button widget ## SYNOPSIS **cc** \[ *flag* ... \] *file* ... **-lcdk** \[ *library* ... \] **#include \** **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***,** **const char \****message***,** **tButtonCallback** *callback***,** **boolean** *box***,** **boolean** *shadow***);** - **void setCDKButton(** **CDKBUTTON \****b***,** **const char \****message***,** **boolean** *box***);** - **void setCDKButtonBackgroundAttrib (** **CDKBUTTON \****b***,** **chtype** *attribute***);** - **void setCDKButtonBackgroundColor (** **CDKBUTTON \****b***,** **const 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***,** **const 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. ## AUTHORS Grant Edwards, Aspen Research Corporation ## SEE ALSO [**cdk**(3)](/cdk/3.md), [**cdk\_binding**(3)](/cdk_binding/3.md), [**cdk\_display**(3)](/cdk_display/3.md), [**cdk\_position**(3)](/cdk_position/3.md), [**cdk\_process**(3)](/cdk_process/3.md), [**cdk\_screen**(3)](/cdk_screen/3.md), [**cdk\_traverse**(3)](/cdk_traverse/3.md)