An abstract class that collects together a group of items, and provides functionality for displaying and selecting them.
capi
button-panel
double-list-panel
extended-selection-tree-view
graph-pane
list-panel
menu-component
option-pane
toolbar-component
tree-view
:interaction |
The interaction style of the choice. |
:selection |
The indexes of the choice's selected items. |
:selected-item |
The selected item for a single selection choice. |
:selected-items |
A list of the selected items. |
:keep-selection-p |
If t , retains any selection when the items change. |
:initial-focus-item | |
If supplied, this should be an item in the choice. |
choice-selection
choice-interaction
choice-initial-focus-item
The class choice
inherits most of its behavior from collection, and then provides the selection facilities itself. The classes list-panel, button-panel, option-pane, 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 interaction styles, and these control how it behaves when an item is selected by the user. interaction can be one of:
The choice behaves just as a collection. | |
:single-selection | The choice can have only one selected item. |
:multiple-selection | |
The choice can have multiple selected items, except on macOS. | |
:extended-selection | |
An alternative to |
With interaction :no-selection
, the choice cannot have a selection, and so behaves just as a collection would.
With interaction :single-selection
, the choice can only have one item selected at a time. When a new selection is made, the old selection is cleared and its selection-callback is called. The selection-callback is also called when the user invokes the selection gesture on the selected item.
With interaction :multiple-selection
, 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. :multiple-selection
is not supported for lists on macOS.
With interaction :extended-selection
, the choice can have any number of items selected as with :multiple-selection
interaction, 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.
On macOS, the selection gesture is mouse (left button) click. Deselection and discontinuous selections are made by Command+Click
, and a continuous selection is made by Shift+Click
, regardless of whether if interaction is :multiple-selection
or :extended-selection
.
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. Therefore when calling (setf choice-selection)
you must pass an integer or nil
if interaction is :single-selection
, and you must pass a list of integers if interaction is :multiple-selection
or :extended-selection
.The functions 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
t
, then the selection is preserved over the change.
initial-focus-item, if supplied, specifies the item which has the input focus when the choice is first displayed.
When calling (setf choice-selection)
you must pass an integer or nil
when interaction is :single-selection
. You must pass a list for other values of interaction.
In LispWorks 5.0 and earlier versions, for interaction :single-selection
the selection-callback is called only after a new selection is made.
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)
Also see these examples:
(example-edit-file "capi/choice/")
(example-edit-file "capi/graphics/graph-pane")
choice-selected-item
choice-selected-item-p
choice-selected-items
choice-update-item
redisplay-collection-item
remove-items
replace-items
5 Choices - panes with items
CAPI User Guide and Reference Manual (Unix version) - 01 Dec 2021 19:32:42