5.9.1 Interaction

All choices have an interaction style, controlled by the :interaction initarg. The radio-button-panel and check-button-panel are simply button-panels with their interactions set appropriately. The possible values for interaction are listed below.

:single-selection

Only one item may be selected at a time: selecting an item deselects any other selected item.

:multiple-selection

A multiple selection choice allows the user to select as many items as she wants. A selected item may be deselected by clicking on it again.

:extended-selection

An extended selection choice is a combination of the previous two: only one item may be selected, but the selection may be extended to more than one item.

:no-selection

Forces no interaction. Note that this option is not available for list panels. To display a list of items with no selection you should use a display pane instead.

Specifying an interaction style that is invalid for a particular choice causes an error.

The accessor choice-interaction is provided for accessing the interaction of a choice.

5.9.2 Selections

All choices have a selection. This is a state representing the items currently selected. The selection is represented as a list of indexes into the list of the choice's items, unless it is a single-selection choice, in which case it is just represented as an index. The indexes in the selection can be used to access the actual items using get-collection-item.

The initial selection is controlled with the initarg :selection. The choice accessor choice-selection is provided, and you can also use (setf choice-selection).

Generally, it is easier to refer to the selection in terms of the items selected, rather than by indexes, so the CAPI provides the notion of a selected item and the selected items . The first of these is the selected item in a single-selection choice. The second is a list of the selected items in any choice.

The accessors choice-selected-item and choice-selected-items provide access to these conceptual slots, and you can also supply the values at make-instance time via the initargs :selected-item and :selected-items.

5.9.3 Callbacks in choices

All choices can have callbacks associated with them. Callbacks are invoked both by mouse button presses and keyboard gestures that change the selection or are "Action Gestures" such as Return. Different sorts of gesture can have different sorts of callback associated with them.

The following callbacks are available: :selection-callback, :retract-callback (called when a deselection is made), :extend-callback, :action-callback (called when a double-click occurs) and :alternative-action-callback (called when a modified double-click occurs). What makes one choice different from another is that they permit different combinations of these callbacks. This is a consequence of the differing interactions. For example, you cannot have an :extend-callback in a radio button panel, because you cannot extend selection in one.

Callbacks pass data to the function they call. There are default arguments for each type of callback. Using the :callback-type keyword allows you to change these defaults. Example values of callback-type are :interface (which causes the interface to be passed as an argument to the callback function), :data (the value of the selected data is passed), :element (the element containing the callback is passed) and :none (no arguments are passed). Also there is a variety of composite :callback-type values, such as :data-interface (which causes two arguments, the data and the interface, to be passed). For a complete description of :callback-type values, see the manual page for callbacks.

The following example uses a push button and a callback function to display the arguments it receives.

(defun show-callback-args (arg1 arg2)

  (display-message "The arguments were ~S and ~S" arg1 arg2))

(setq example-button 

      (make-instance 'push-button

                     :text "Push Me"

                     :callback 'show-callback-args

                     :data "Here is some data"

                     :callback-type :data-interface))

(contain example-button)

Try changing the :callback-type to other values.

If you do not use the :callback-type argument and you do not know what the default is, you can define your callback function with lambda list (&rest args) to account for all the arguments that might be passed.

Specifying a callback that is invalid for a particular choice causes an error.

5.9.4 image-list, image-set and image-locator

Choices that need images for displaying items generally have an slot image-function which holds a function that returns the image to use for an item. The return value ultimately needs to evaluate to an image to display, but there are various ways to specify it. These include all the specifications that load-image understands. In addition, they can also be an integer which is an index into an image-list or an image-locator.

To use image-list in a choice you need to specify the image-list by the appropriate initarg, for example :image-lists for tree-view. See the entry for each specific class. Once the choice has image-lists, the image-function can return an index into the relevant list.

An image-list is an object that specifies an ordered set of images with a common width and common height. The images in the image-list can be image objects, image identifiers (pathname or symbol, which are automatically loaded by load-image), or image-set objects. You need to supply these objects when you make the image-list by cl:make-instance.

An image-list object can be used repeatedly in several panes. It is useful because it simplifies the handling of the images.

Example:

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

An image-set represents a group of images of the same size that are derived from a single object. For example, six images of 16x16 pixels each can be derived from a single image of 16x96 pixels. This is an example of the "general" image-set, which is created by make-general-image-set. In addition, you can create a scaled image set by either make-scaled-general-image-set or make-scaled-image-set. On Microsoft Windows, you can also create image-sets from resources in a DLL, either a bitmap resource by make-resource-image-set, or icon resource by make-icon-resource-image-set.

image-sets are useful because it is often convenient to hold a group of images as a combined larger image, which reduces the number of objects that needed to be dealt with. image-sets are used inside image-lists, and sometimes can be used directly, for example in toolbar. image-set can also be used in image-locators.

Examples:

(example-edit-file "capi/choice/tree-view") (example-edit-file "capi/elements/toolbar") (example-edit-file "capi/choice/multi-column-list-panels")

An image-locator specifies one image out of an image-set, and it is created by make-image-locator. It can be used instead of an image in various places, most usefully as a result of the various image-function s.

Example:

(example-edit-file "capi/choice/multi-column-list-panels")

For choices like tree-view or list-panel, you can include a sub-set from an image-set either by using image locators, or by including the image-set in an image-list and use the image-list in the choice. The latter technique is normally more convenient when all the image-set is used, but in other situations using image-locators may be more convenient.