option-pane

option-pane Class

Summary

A pane which offers a choice of items, but which displays only the currently selected item.

Package

capi

Superclasses

Initargs

`:enabled`	Non-nil if the option pane is enabled.
`:visible-items-count`
	An integer or the symbol `:default`.
`:popup-callback`	A function called just before the popup menu appears, or `nil`.
`:popdown-callback`
`:image-function`	A function providing images for items, or `nil`.
`:image-lists`	A plist of keywords and image-list objects.
`:separator-item`	An item that acts as a separator between other items, or `nil`.
`:enabled-positions`	A list of fixnums, or the keyword `:all`.
`:window-styles`	A list of keywords.

Accessors

option-pane-enabled
option-pane-image-function
option-pane-visible-items-count
option-pane-popup-callback
option-pane-separator-item
option-pane-enabled-positions

Description

The class option-pane provides a pane which offers a choice between a number of items via a popup menu. Only the currently selected item is displayed.

The class option-pane inherits from choice, and so has all of the standard choice behavior such as selection and callbacks. It also has an extra enabled slot along with an accessor which is used to enable and disable the option pane.

visible-items-count is implemented only on Microsoft Windows. If visible-items-count is an integer then the popup menu is no longer than this, and is scrollable if there are more items. If visible-items-count is :default, then the popup menu is no longer than 10. This is the default value.

When popup-callback is non-nil, it should be a function of one argument that will be called just before the popup menu appears when the user clicks on it. The single argument to the function is the option pane and the return value is ignored. If required, the function can change the items or selection of the pane. The default value of popup-callback is nil.

If image-function is non-nil, it should be a function of one argument which is called with each item. The return value depends on image-lists. If image-lists contains an image-list for the :normal key, then the result of image-function should be one of the following:

A pathname or string	This specifies the filename of a file suitable for loading with load-image. Currently this must be a bitmap file.
A symbol	The symbol must have been previously registered by means of a call to register-image-translation.
An image object	For example, as returned by load-image.
An image locator object
	This allowing a single bitmap to be created which contains several button images side by side. See make-image-locator for more information. On Microsoft Windows, it also allows access to bitmaps stored as resources in a DLL.
An integer	This is a zero-based index into the option-pane's image-list. This is generally only useful if the image list is created explicitly. See image-list for more details.

Otherwise if there is no image-list then it should return one of:

`nil`	No image is shown.
An image object	The pane displays this image.
An image id or an external-image object
	The system converts the value to a temporary image for the item and frees it when it is no longer needed.

If image-function is nil, no items have images. This is the default value..

If image-lists is specified, it should be a plist containing the keyword :normal as a key. The corresponding value should be an image-list object. No other keys are supported at the present time. The image-list associated with the :normal key is used with the image-function (see above) to specify an image to display in each tab.

separator-item should be an item (compared using test-function) that acts as a separator between other items. A separator item is not selectable. The default value nil means that there are no separators (regardless of test-function).

If enabled-positions is :all then all the items can be selected. Otherwise the value is a list of fixnums indicating the positions in the item list which can be selected. The default value is :all.

On Microsoft Windows, if window-styles contains the keyword :simple-text-only, then the option-pane is displayed using the UI theme and the enabled-positions, separator-item, image-function and visible-items-count initargs are not supported. Otherwise it is displayed without the UI theme and those options work as documented. This is a limitation in Microsoft Windows.

Notes

The user cannot edit the items in an option-pane. For an element with similar functionality which allows editing, see text-input-choice.
:image-function and :image-lists are currently only implemented for Microsoft Windows, GTK+ and Cocoa.
On Motif, the separator is represented simply as a blank item between the other items.
On Motif and GTK+ versions older than 2.12, there is no visible representation of the disabled items.

Examples

This example sets the selection and changes the enabled state of an option-pane:

(setq option-pane (capi:contain
                   (make-instance 'capi:option-pane
                                  :items '(1 2 3 4 5)
                                  :selected-item 3)))
 
(capi:apply-in-pane-process 
 option-pane #'(setf capi:choice-selected-item) 
 5 option-pane)
 
(capi:apply-in-pane-process 
 option-pane #'(setf capi:option-pane-enabled) 
 nil option-pane)
 
(capi:apply-in-pane-process 
 option-pane #'(setf capi:option-pane-enabled) 
 t option-pane)

This example illustrates the use of visible-items-count (Windows only):

(capi:contain
 (make-instance 'capi:option-pane
                :items 
                (loop for i below 20 collect i)
                :visible-items-count 6))

These are further examples:

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

(example-edit-file "capi/choice/option-pane-with-images")

There are further examples in 20 Self-contained examples.