button-panel Class

Summary

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.

Package

capi

Superclasses

choice
titled-object
simple-pane

Subclasses

push-button-panel
radio-button-panel
check-button-panel

Initargs

Accessors

pane-layout

Description

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:

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.

Examples

(capi:contain (make-instance 
               'capi:button-panel
               :items '(:red :green :blue)
               :print-function 'string-capitalize))

(setq buttons
      (capi:contain
       (make-instance
        'capi:button-panel
        :items '(:red :green :blue)
        :print-function 'string-capitalize
        :interaction :multiple-selection)))
 
(capi:apply-in-pane-process
 buttons #'(setf capi:choice-selected-items) 
 '(:red :green) buttons)

(capi:contain (make-instance 
               'capi:button-panel
               :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:

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

Also see these example files:

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

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

See also

radio-button
check-button
push-button
set-button-panel-enabled-items
5 Choices - panes with items