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.
The following initargs controlling mnemonics apply only on MS Windows:
A list specifying mnemonics for the buttons.
A list of strings, each specifying the text and a mnemonic.
A character specifying the mnemonic escape. The default value is
#\&
.
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:
push-button-panel
|
push-button
|
radio-button-panel
|
radio-button
|
check-button-panel
|
check-button
|
(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.
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
'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 the example in the directory
examples/capi/buttons/
.
