3.10 Button elements

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 5 Choices - panes with items.

There are three classes of buttons:

push-button	Never selected, just invokes the callback when clicked.
check-button	Toggles between selected and unselected each time it is clicked.
radio-button	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.

3.10.1 Push buttons

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.

3.10.2 Check buttons

Check buttons can be produced with the check-button element.

1. Enter the following in a Listener:

   (setq check (make-instance 'check-button  
                          :selection-callback 'hello
                          :retract-callback 'test-callback
                          :text "Button"))
    
   (contain check)
   

   A check button

   

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.

3.10.3 Radio buttons

Radio buttons can be created explicitly with the radio-button element, but they are usually part of a button panel as described in 5 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))

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.

3.10.4 Mnemonics in buttons

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.