Class

Summary

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

Package

capi

Superclasses

collection

Subclasses

button-panel
extended-selection-tree-view
graph-pane
list-panel
menu-component
option-pane
tree-view

Initargs

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

Accessors

choice-selection

Readers

choice-interaction
choice-initial-focus-item

Description

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:

: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, except on Mac OS X.

:extended-selection

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.

Notes

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.

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)

Also see the examples in the directory examples/capi/choice/ and in examples/capi/graphics/graph-pane.lisp

See also

choice-selected-item
choice-selected-item-p
choice-selected-items
choice-update-item