choice

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.

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

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 these examples:


(example-edit-file "capi/choice/")


(example-edit-file "capi/graphics/graph-pane")

choice

Class

Summary

Package

Superclasses

Subclasses

Initargs

Accessors

Readers

Description

Notes

Compatibility note

Example

See also