A pane which offers a choice of items, but which displays only the currently selected item.
capi
choice
titled-object
simple-pane
: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. |
option-pane-enabled
option-pane-image-function
option-pane-visible-items-count
option-pane-popup-callback
option-pane-separator-item
option-pane-enabled-positions
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.
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.
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.
text-input-choice
3.1.4.1 Controlling Mnemonics
5 Choices - panes with items
9.7.1 Toolbar items other than buttons with images
CAPI User Guide and Reference Manual (Unix version) - 01 Dec 2021 19:32:42