Next Prev Up Top Contents Index

choice

Class
Summary

A choice 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

It t , retains any selection when the items change.

Accessors

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

Readers

choice-interaction

Description

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.

: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 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.

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


LispWorks CAPI Reference Manual - 14 Dec 2001

Next Prev Up Top Contents Index