All Manuals > CAPI User Guide and Reference Manual > 21 CAPI Reference Entries

button Class


A class of pane that displays either a piece of text or an image, and that performs an action when pressed. Certain types of buttons can also be selected and deselected.







The interaction style for the button.
For radio button and check button styles, if selected is set to t, the button is initially selected.
Specifies the callback to use when the button is selected.
An image for the button (or nil).
The image used when the button is selected.
If nil the button cannot be selected.
If true the button is the "Cancel" button, that is, the button selected by the Escape key.
If true the button is the default button, that is, the button selected by the Return key.
The image for the button when disabled (or nil), only implemented on Motif and Microsoft Windows.
The image used when the button is selected and disabled, only implemented on Motif and Microsoft Windows.
The image used when the button is pressed and interaction is :no-selection, only implemented on GTK+ and Motif and Microsoft Windows.
A character, integer or symbol specifying a mnemonic for the button, only implemented on Microsoft Windows and GTK+.
A string specifying the text and a mnemonic, only implemented on Microsoft Windows and GTK+.
A character specifying the mnemonic escape. The default value is #\&, only implemented on Microsoft Windows and GTK+.



The class button is the class that push-button, radio-button, and check-button are built on. It can be displayed either with text or an image, and a callback is called when the button is clicked. It inherits all of its textual behavior from item, including the slot text which is the text that appears in the button.

Rather than creating direct instances of button, you usually create instances of its subclasses, each of which has a specific interaction style. Occasionally it may be easier to instantiate button directly with the appropriate value of interaction (for instance, when the interaction style is only known at run-time) but you may not use such a button as an item in a button-panel.

The values allowed for interaction are as follows:

A push button.

A radio button.


A check button.

Both radio buttons and check buttons can have a selection which can be set using the initarg :selected and the accessor button-selected.

The button's callback gets called when the user clicks on the button, and by default gets passed the data in the button and the interface. This can be changed by specifying a callback type as described in the description of callbacks. The following callbacks are accepted by buttons:


Called when the button is selected.

For buttons this is a synonym of :selection-callback.

Called when the button is deselected.

By default, image and disabled-image are nil, meaning that the button is a text button, but if image is provided then the button displays an image instead of the text. The image can be an external-image or any object accepted by load-image, including a .ico file on Microsoft Windows. The disabled image is the image that is shown when the button is disabled (or nil, meaning that it is left for the window system to decide how to display the image as disabled). On some platforms the system computes the disabled image and so disabled-image is ignored.

The button's actions can be enabled and disabled with the enabled slot, and its associated accessor button-enabled. This means that when the button is disabled, pressing on it does not call any callbacks or change its selection.

Note that the class button-panel provides functionality to group buttons together, and should normally be used in preference to creating individual buttons yourself. For instance, a radio-button-panel makes a number of radio buttons and also controls them such that only one button is ever selected at a time.

A mnemonic is an underlined character within the button text or the printed representation of the button data which can be entered to select the button. The value mnemonic is interpreted as described for menu.

An alternative way to specify a mnemonic is to pass mnemonic-text. This is a string which provides the text for the button and also specifies the mnemonic character. mnemonic-text and mnemonic-escape are interpreted in just the same way as the mnemonic-title and mnemonic-escape of menu.

  1. The simple-pane initarg foreground is not supported for buttons on Windows and Cocoa.
  2. The disabled-image, armed-image and selected-disabled-image will work on Microsoft Windows provided you are running with the themed look-and-feel (which is the default). See 19.1.1 Using Windows themes.

In the following example a button is created. Using the button-enabled accessor the button is then enabled and disabled.

(setq button
      (capi:contain (make-instance 
                     :text "Press Me")))
 button #'(setf capi:button-enabled) nil button)
 button #'(setf capi:button-enabled) t button)

In the next example a button with an image instead of text is created.

(setq button

The following examples illustrate mnemonics:

(defun egg (&rest ignore) 
  (declare (ignore ignore))
  (capi:display-message "Egg"))
 (make-instance 'capi:push-button  
                :selection-callback 'egg
                :mnemonic-text "Chicken && Rice"))
 (make-instance 'capi:push-button  
                :data "Chicken"
                :selection-callback 'egg
                :mnemonic #\k))

Compare this with the previous example: the #\k does not appear and the #\e becomes the mnemonic:

 (make-instance 'capi:push-button  
                :selection-callback 'egg
                :mnemonic-escape  #\k      
                :mnemonic-text "Chicken"))

Also see these examples:

(example-edit-file "capi/buttons/")
See also

3.10 Button elements
13.10 Working with images

CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:27