1 CAPI Reference Entries

choice

Class

Summary

Achoice is an abstract class that collects together a group of items, and provides functionality for displaying and selecting them.

Superclasses:

collection

Subclasses

list-panel button-panel option-pane graph-pane menu-component

Slots

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

Itt, retains any selection when the items change.

Accessors

choice-selection choice-selected-item choice-selected-items

Readers

choice-interaction

Description

The classchoice inherits most of its behavior fromcollection, 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.

Achoice can have one of four different interactions, and these control how it behaves when an item is selected by the user.

:no-selection

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.

:extended-selection

An alternative tomultiple-selection.

Inno-selection mode, the choice cannot have a selection, and so behaves just as a collection would.

Insingle-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 theselection-callback is called.

Inmultiple-selection mode, the choice can have any number of items selected, and selecting an item toggles its selection status. Theselection-callback is called when an item becomes selected, and theretract-callback is called when an item is deselected.

Inextended-selection mode, the choice can have any number of items selected as withmultiple-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 theselection callback is called, when the selection is extended theextend-callback is called, and when an item is deselected theretract-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 accessorschoice-selected-item andchoice-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 withkeep-selection-p set tot, then the selection is preserved over the change.

Example

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)

See also
: choice-selected-item
choice-selected-items