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

button-panel Class


The class button-panel is a pane containing a number of buttons that are laid out in a particular style, and that have group behavior.







The type of layout for the buttons.
Initialization arguments for the layout.
The selection callbacks for each button.
The class of the buttons.
A list.
A list.
A list.
A list.
A list.
A list.
Specifies the default button.
Specifies the cancel button.
A list specifying mnemonics for the buttons, only implemented on Microsoft Windows.
A list of strings, each specifying the text and a mnemonics, only implemented on Microsoft Windows.
A character specifying the mnemonic escape. The default value is #\&s, only implemented on Microsoft Windows.
A string specifying the title and a mnemonics, only implemented on Microsoft Windows.



The class button-panel inherits most of its behavior from choice, which is an abstract class providing support for handling items and selections. By default, a button panel has single selection interaction style (meaning that only one of the buttons can be selected at any one time), but this can be changed by specifying an interaction.

The subclasses push-button-panel, radio-button-panel and check-button-panel are provided as convenience classes, but they are just button panels with different interactions (:no-selection, :single-selection and :multiple-selection respectively).

The layout of the buttons is controlled by a layout of class layout-class (which defaults to row-layout) but this can be changed to be any other CAPI layout. When the layout is created, the list of initargs layout-args is passed to make-instance.

Each button uses the callbacks specified for the button panel itself, unless the argument callbacks is specified. callbacks should be a list (one element per button). Each element of callbacks, if non-nil, will be used as the selection callback of the corresponding button.

button-class, if supplied, determines the class used for each of the buttons. This should be the class appropriate for the interaction, or a subclass of it. The default behavior is to create buttons of the class appropriate for the interaction.

Each of images, disabled-images, armed-images, selected-images, selected-disabled-images and help-keys, if supplied, should be a list of the same length as items. The values are passed to the corresponding item, and interpreted as described for button. The button-panel images values map to button image arguments, and so on.

For button-panel and its subclasses, the items supplied to the :items initarg and (setf collection-items) function can contain button objects. In this case, the button is used directly in the button panel rather than a button being created by the CAPI.

This allows button size and spacing to be controlled explicitly. Note that the button must be of the appropriate type for the subclass of button-panel being used, as shown in the following table:

Button and panel classes
Button panel classButton class







For example:

(let ((button1 (make-instance 'capi:push-button
                              :text "button1"
                              :internal-border 20
                              :visible-min-width 200))
      (button2 (make-instance 'capi:push-button
                              :text "button2"
                              :internal-border 20
                              :visible-min-width 200)))
  (capi:contain (make-instance 'capi:push-button-panel
                           :items (list button1 button2)
                           :layout-args '(:x-gap 30))))

default-button specifies which button is the default (selected by pressing Return). It should be equal to a member of items when compared by test-function. If the items are non-immediate objects such as strings or button objects, you must ensure either that the same (eq) object is passed in items as in default-button, or that a suitable test-function is supplied.

cancel-button specifies which button is selected by pressing Escape. The comparison with members of items is as for default-button.

mnemonics is a list of the same length as items. Each element is a character, integer or symbol specifying the mnemonic for the corresponding button in the same way as described for menu.

mnemonic-items is an alternate way to specify the mnemonics in a button panel. It is a list of the same length as items. Each element is a string which is interpreted for the corresponding button as its mnemonic-text initarg.

mnemonic-title and mnemonic-escape are interpreted as for menu. mnemonic-escape specifies the escape character for mnemonics both in the buttons and in the pane's title.

Compatibility note

Button panels now default to having a maximum size constrained to their minimum size as this is useful when attempting to layout button panels into arbitrary spaces without them changing size. To get the old behavior, specify :visible-max-width nil in the make-instance.

(capi:contain (make-instance 
               :items '(:red :green :blue)
               :print-function 'string-capitalize))
(setq buttons
        :items '(:red :green :blue)
        :print-function 'string-capitalize
        :interaction :multiple-selection)))
 buttons #'(setf capi:choice-selected-items) 
 '(:red :green) buttons)
(capi:contain (make-instance 
               :items '(1 2 3 4 5 6 7 8 9)
               :layout-class 'capi:grid-layout
               :layout-args '(:columns 3)))

This example illustrates use of default-button and test-function:

 (make-instance 'capi:push-button-panel 
                :items '("one" "two" "three")
                :default-button "two"
                :test-function 'equalp

Also see these example files:

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

5 Choices - panes with items

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