Button classes inherit from the class button, which defines most of the attributes of buttons. button inherits from simple-pane and item. Button panels can be created, and are described in Choices - panes with items.
There are three classes of buttons:
Never selected, just invokes the callback when clicked.
Toggles between selected and unselected each time it is clicked.
When clicked is selected, and deselects all other buttons in the same panel.
A single radio-button does not really make sense and this class will normally be used only inside radio-button-panel. check-button and push-button are used both inside check-button-panel or push-button-panel and on their own. Note that when using a panel, you do not have to actually use button objects, because the panel generates them automatically, and most of the functionality of buttons can be specified in the button-panel.
The text and the data that are associated with a button are defined by the the initargs and accessor inherited from item: :data, :text, :print-function, item-data, item-text, item-print-function. The function print-capi-button can be used to find what string is displayed (or will be displayed) for a button.
The callbacks of button are inherited from callbacks (via item). The :selection-callback (the initarg :callback can be used too) is the main callback, and :retract-callback is called for deselection.
button has various initargs and accessors controlling which image(s) to display, whether it is selected and/or enabled, and whether it is a Cancel button or the default button.
The :enabled keyword can be used to specify whether or not the button should be selectable when it is displayed. This can be useful for disabling a button in certain situations.
The following code creates a push button which cannot be selected.
(setq offbutton (make-instance 'push-button
:data "Button"
:enabled nil))
(contain offbutton)
These setf expansions enable and disable the button:
(apply-in-pane-process
offbutton #'(setf button-enabled) t offbutton)
(apply-in-pane-process
offbutton #'(setf button-enabled) nil offbutton)
All subclasses of the button class can be disabled in this way.
Check buttons can be produced with the check-button element.
(setq check (make-instance 'check-button
:selection-callback 'hello
:retract-callback 'test-callback
:text "Button"))
(contain check)
Notice the use of :retract-callback in the example above, to specify a callback when the element is deselected.
Like push buttons, check buttons can be disabled by specifying :enabled nil.
Radio buttons can be created explicitly although they are usually part of a button panel as described in Choices - panes with items. The :selected initarg is used to specify whether or not the button is selected, and the :text initarg can be used to label the button.
(contain (make-instance 'radio-button
:text "Radio Button"
:selected t))
Figure 3.6 An explicitly created radio button
Although a single radio button is of limited use, having an explicit radio button class gives you greater flexibility, since associated radio buttons need not be physically grouped together. Generally, the easiest way of creating a group of radio buttons is by using a button panel, but doing so means that they will be geometrically, as well as semantically, connected.
This section applies to Microsoft Windows and GTK+ only.
The initarg :mnemonic allows you to specify a mnemonic for a button.
Alternatively you can specify the button text and its mnemonic together with the initarg :mnemonic-text, for example:
(contain
(make-instance 'radio-button
:mnemonic-text
"Radio Button with a &Mnemonic"))
For all the details see button.
CAPI User Guide and Reference Manual (Macintosh version) - 3 Aug 2017