This section summarizes the general properties of choices.
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
are listed below.
choice-interaction is provided for accessing the
of a choice.
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
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
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:
:retract-callback (called when a deselection is made),
: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
: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.
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.
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
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
An image-list object can be used repeatedly in several panes. It is useful because it simplifies the handling of the images.
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.
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.
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.
CAPI User Guide and Reference Manual (Windows version) - 3 Aug 2017