All Manuals > CAPI Reference Manual > 1 CAPI Reference Entries




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.


A list of the selected items.


If t , retains any selection when the items change.


If supplied, this should be an item in the 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, except on Mac OS X.


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 for lists 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. 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 .

Compatibility note

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

See also


CAPI Reference Manual - 15 Dec 2011