Class

Summary

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

Package

capi

Superclasses

choice
titled-object
simple-pane

Initargs

:enabled

Non-nil if the option pane is enabled.

:visible-items-count

An integer specifying the maximum length of the popup menu, or the symbol :default .

:popup-callback

A function called just before the popup menu appears, or nil .

:image-function

A function providing images for items, or nil .

:separator-item

An item that acts as a separator between other items, or nil .

:enabled-positions

A list of fixnums, or the keyword :all .

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.

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. image-function is called with each item and should return one of:

nil

No image is shown.

An image object

The pane displays this image.

An image id or external-image

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.

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 .

Notes

1. :image-function is currently only implemented for Microsoft Windows and Cocoa.
2. On Motif, the separator is represented simply as a blank item between the other items.
3. On Motif and GTK+ versions older than 2.12, there is no visible representation of the disabled items.

Example

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 :

(capi:contain

 (make-instance 'capi:option-pane

                :items 

                (loop for i below 20 collect i)

                :visible-items-count 6))

There are further examples in the files examples/capi/choice/option-pane.lisp and examples/capi/choice/option-pane-with-images.lisp .