The class
list-panel
is a pane that can display a group of items and provides support for selecting items and performing actions on them. Each item may optionally have an image.
:right-click-selection-behavior
A keyword or
nil
. Controls the behavior on a right mouse button click.
A function designator or
nil
. Controls item text color on Microsoft Windows, Cocoa and GTK+.
A boolean influencing the use of alternating background color on Cocoa and GTK+.
A boolean. The default value is
nil
.
The following initargs take effect only when filter is non-nil.
A boolean. The default value is
t
.
A function designator or the keyword
:default
, which is the default value.
A boolean. The default value is
nil
.
A function that is used to search for an item when the user types ordinary characters.
Returns a state image for an item.
A plist of keywords and image-list objects.
Flag to specify whether items have images. Defaults to
t
.
Flag to specify whether items have state images. Defaults to
nil
.
Defaults to 16.
Defaults to 16.
list-panel-right-click-selection-behavior
list-panel-keyboard-search-callback
list-panel-image-function
list-panel-state-image-function
The class
list-panel
gains much of its behavior from choice, which is an abstract class that handles items and their selection. By default, a list panel has both horizontal and vertical scrollbars.
The
list-panel
class does not support the
:no-selection
interaction style. For a non-interactive list use a display-pane.
To scroll a
list-panel
, call scroll with
scroll-operation
:move
.
mnemonic-title is interpreted as for menu.
right-click-selection-behavior can take the following values:
Corresponds to the behavior in LispWorks 4.4 and earlier. The data is not passed.
All non-nil values pass the clicked item as data to the pane menu:
:existing-or-clicked/restore/discard
If the clicked item is not already selected, make it be the entire selection while the menu is displayed. If the clicked item is already selected, do not change the selection. If the menu is cancelled, the original selection is restored. If the user chooses an item from the menu, the selection is not restored.
A synonym for
:existing-or-clicked/restore/discard
.
:existing-or-clicked/restore/restore
If the clicked item is not already selected, make it be the entire selection while the menu is displayed. If the clicked item is already selected, do not change the selection. If the user chooses an item from the menu and the item's callback does not set the selection then the original selection is restored after the callback. If the callback sets the selection, then this selection remains. The original selection is restored if the user cancels the menu.
A synonym for
:existing-or-clicked/restore/restore
.
Make the clicked item be the entire selection while the menu is displayed. If the menu is cancelled, the original selection is restored. If the user chooses an item from the menu, the selection is not restored.
A synonym for
:clicked/restore/discard
.
Make the clicked item be the entire selection while the menu is displayed. If the user chooses an item from the menu and the item's callback does not set the selection then the original selection is restored after the callback. If the callback sets the selection, then this selection remains. The original selection is restored if the user cancels the menu.
:existing-or-clicked/discard/discard
If the clicked item is not already selected, make it be the entire selection while the menu is displayed. If the clicked item is already selected, do not change the selection. The original selection is never restored, regardless of whether the user chooses an item from the menu or cancels the menu.
A synonym for
:existing-or-clicked/discard/discard
.
Make the clicked item be the entire selection. The original selection is never restored, regardless of whether the user chooses an item from the menu or cancels the menu.
A synonym for
:clicked/discard/discard
.
Does not affect the selection, but the clicked item is nonetheless passed as the data.
The default value of
right-click-selection-behavior
is
:no-change
.
color-function allows you to control the text colors on Microsoft Windows, Cocoa and GTK+. If color-function is non-nil, then it is a function used to compute the text color of each item, with signature
color-function
list-panel
item
state
=>
result
When
alternating-background
is true, the list panel is drawn with alternating background on Cocoa. On GTK+ it provides a hint, which the theme can override. Experience suggests that theme may draw with alternating background even when
alternating-background
is false, but when it is true they tend to draw it always. The default value of
alternating-background
is
nil
.
state
is a keyword representing the state of the item. It can be one of
:normal
,
:selected
or
:disabled
. The value
result
should be a value suitable for the function convert-color. The pane uses the converted color as the foreground color for the item
item
.
color-function
is called while
list-panel
is being drawn, so it should not do heavyweight computations.
If
filter
is non-nil, the system automatically adds a filtering-layout above the list. The items in the
list-panel
are filtered by the value in the filtering-layout. Filtering displays only those items whose print representation matches the filter. (The print representation is the result of print-collection-item, and is what the user sees.) Only the items that match, or those that do not match if
Exclude
is set, are displayed in the
list-panel
.
Here filtering means mapping over the unfiltered items, collecting each item that matches the current setting in the filter, and then setting the items of the
list-panel
to the collected items.
For a
list-panel
with a filter,
collection-items
returns only the filtered items, and the selection (that is, the result of
choice-selection
and the argument to
(setf choice-selection)
index into the filtered items.
Calling
(setf collection-items)
on a filtered
list-panel
sets an internal unfiltered list, and then clears the filtering so that all items are visible.
To get and set the unfiltered items, use the accessor list-panel-unfiltered-items. To access the filter-state, use list-panel-filter-state. To access both the unfiltered items and the filter simultanously, which is especially useful when setting both of them at the same time, use list-panel-items-and-filter.
filter-automatic-p controls whether the filter automatically does the filtering whenever the text in the filter changes, and filter-callback defines the callback of the filtering-layout.
If
filter-automatic-p
is
t
, whenever a change occurs in the filter the list is refreshed against the new value in the filter. The
filter-callback
(if non-nil) is called with two arguments, the filtering-layout and the
list-panel
itself, when the user "confirms" (that is, she presses
Return
or clicks the
Confirm
button). If
filter-automatic-p
is false and
filter-callabck
is
:default
, then the filtering-layout is given a callback that does the filtering when the user "confirms". If
filter-automatic-p
is false and
filter-callback
is non-nil, then no filtering is done explicitly, and it is the responsibility of the callback to do any filtering that is required.
filter-matches-title
(default
t
) and
filter-help-string
(default
t
) are passed down to the filtering layout through the corresponding filtering-layout initargs:
:matches-title
:help-string
See filtering-layout for a description of these initargs.
If filter-short-menu-text is true, the filter menu has a short title. For example if the filter is set for case-sensitive plain inclusive matching the short label is PMC . If filter-short-menu-text were false then this label would be Filter:C .
keyboard-search-callback should be a function with signature:
keyboard-search-callback pane string position => index , last-match , last-match-reset-time
pane
is the
list-panel
,
string
is a string to match and
position
is the item index from which the system thinks that the search should start.
string contains the character that the user typed, appended to the "last match", if there is one. There is a "last match" if the previous call to keyboard-search-callback returned it (see below).
index
is an index in the
collection-items
to move to. Apart from an integer inside the items range of the
list-panel
, this can be
nil
, which means do nothing, or
:no-change
, which selects the current item.
last-match is a string that should be recorded as the "last match" (if it is not a string, the "last match" is reset). This is prepended to the character in the next call, if the character is typed before the "last match" is reset.
last-match-reset-time
is the time to wait before resetting the "last match", in seconds. Once this time passes, the last match is reset to
nil
. If
last-match-reset-time
is
nil
, the default value (which defaults to 1) is used. This default value can be changed by set-list-panel-keyboard-search-reset-time.
You can simplify the implementation of keyboard-search-callback by using list-panel-search-with-function.
As a special case, passing
:keyboard-search-callback t
tells CAPI to use its own internal search mechanism in preference to the native one. That can be useful on GTK+, where the default is to use the native search mechanism (for GTK+ versions after 2.4).
The image-function is called on an item to return an image associated with the item. It can return one of the following:
This specifies the filename of a file suitable for loading with load-image. Currently this must be a bitmap file.
The symbol must have been previously registered by means of a call to
register-image-translation
. It can also one of the following symbols, which map to standard images:
:std-cut
,
:std-copy
,
:std-paste
,
:std-undo
,
:std-redo
,
:std-delete
,
:std-file-new
,
:std-file-open
,
:std-file-save
,
:std-print
,
:std-print-pre
,
:std-properties
,
:std-help
,
:std-find
and
:std-replace
.
On Microsoft Windows, the following symbols are also recognized. They map to view images:
:view-large-icons
,
:view-small-icons
,
:view-list
,
:view-details
,
:view-sort-name
,
:view-sort-size
,
:view-sort-date
,
:view-sort-type
,
:view-parent-folder
,
:view-net-connect
,
:view-net-disconnect
and
:view-new-folder
.
Also on Microsoft Windows, these symbols are recognized. They map to history images:
:hist-back
,
:hist-forward
,
:hist-favorites
,
:hist-addtofavorites
and
:hist-viewtree
.
An image object, as returned by load-image.
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.
This is a zero-based index into the list panel's image lists. This is generally only useful if the image list is created explicitly. See image-list for more details.
The
state-image-function
is called on an item to determine the state image: an additional optional image used to indicate the state of an item. It can return one of the above, or
nil
to indicate that there is no state image.
If image-lists is specified, it should be a plist containing the following keywords as keys. The corresponding values should be image-list objects.
Specifies an
image-list
object that contains the item images. The
image-function
should return a numeric index into this
image-list
.
Specifies an
image-list
object that contains the state images. The
state-image-function
should return a numeric index into this
image-list
.
element-parent
of the
list-panel
, because it is implemented by wrapping some layouts around the
list-panel
.(setq list (capi:contain
(make-instance 'capi:list-panel
:items '(:red :blue :green)
:selected-item :blue
:print-function
'string-capitalize)))
(capi:apply-in-pane-process
list #'(setf capi:choice-selected-item) :red list)
(capi:apply-in-pane-process
list #'(setf capi:choice-selected-item) :green list)
(capi:contain (make-instance
'capi:list-panel
:items '(:red :blue :green)
:print-function 'string-capitalize
:selection-callback
#'(lambda (data interface)
(capi:display-message
"~S" data))))
This example illustrates the use of
:right-click-selection-behavior
:
(capi:define-interface click ()
((keyword :initarg :right-click-selection-behavior))
(:panes
(list-panel
capi:list-panel
:items '("foo" "bar" "baz" "quux")
:visible-min-height '(:character 4)
:pane-menu 'my-menu
:interaction :multiple-selection
:right-click-selection-behavior keyword)))
(defun my-menu (pane data x y)
(declare (ignore pane x y))
(make-instance 'capi:menu
:items (list "Hi There"
""
"Here's the data:"
data)))
(capi:display
(make-instance 'click
:right-click-selection-behavior
:clicked/restore/restore))
See also the example in
examples/capi/choice/list-pane-pane-menu.lisp
.
There are further examples in the directory
examples/capi/choice/
.
CAPI Reference Manual - 15 Dec 2011