choice

choice Class

Summary

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
double-list-panel
extended-selection-tree-view
graph-pane
list-panel
menu-component
option-pane
toolbar-component
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 macOS.
`: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 macOS.

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 macOS, 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.

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.

Examples

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")