A choice
is an abstract class that collects together a group of items, and provides functionality for displaying and selecting them.
list-panel
button-panel
option-pane
graph-pane
menu-component
The interaction style of the choice.
The indexes of the choice's selected items.
The selected item for a single selection choice.
A list of the selected items.
The class choice
inherits most of its behavior from collection
, and then provides the selection facilities itself. The classes list-panel, button-panel, menu-component and graph-pane inherit from it, and so it plays a key role in CAPI applications.
A choice
can have one of four different interactions, and these control how it behaves when an item is selected by the user.
The choice behaves just as a collection.
The choice can have only one selected item.
The choice can have multiple selected items.
An alternative to multiple-selection
.
In no-selection
mode, the choice cannot have a selection, and so behaves just as a collection would.
In single-selection
mode, the choice can only have one item selected at a time. When a new selection is made, the old selection is cleared and the selection-callback
is called.
In multiple-selection
mode, the choice can have any number of items selected, and selecting an item toggles its selection status. The selection-callback
is called when an item becomes selected, and the retract-callback
is called when an item is deselected.
In extended-selection
mode, the choice can have any number of items selected as with multiple-selection
mode, but the usual selection gesture removes the old selection. However, there is a window system specific means of extending the selection. When an item is selected the selection
callback is called, when the selection is extended the extend-callback
is called, and when an item is deselected the retract-callback
is called.
The choice's selection stores the indices of the currently selected item, and is a single number for single selection choices and a list for all other interactions. The complementary accessors choice-selected-item
and choice-selected-items
treat the selection in terms of the items themselves as opposed to their indices.
Usually when a choice's items are changed using (setf collection-items)
the selection is lost.
However, if the choice was created with keep-selection-p
set to t
, then the selection is preserved over the change.
The following example defines a choice with three possible selections.
(setq choice (make-instance 'capi:choice
:items '("One" "Two" "Three")
:selection 0))
(capi:display-message "Selection: ~S"
(capi:choice-selection choice))
(capi:choice-selected-item choice)
The selection is changed using the following code.
(setf (capi:choice-selection choice) 1)
(capi:choice-selected-item choice)