A
choice
is an abstract class that collects together a group of items, and provides functionality for displaying and selecting them.
The interaction style of the choice.
The indexes of the choice's selected items.
The selected item for a single selection choice.
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.
The choice can have only one selected item.
The choice can have multiple selected items.
An alternative to
multiple-selection
.
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 on Mac OS X.
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 Mac OS X, the selection gesture is mouse (left button) click. De-selection 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. 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.
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 the examples in the directory
examples/capi/choice/
and in
examples/capi/graphics/graph-pane.lisp