All Manuals > CAPI User Guide and Reference Manual > 21 CAPI Reference Entries

list-panel Class

Summary

A pane that displays a group of items and provides support for selecting items and performing actions on them. Each item may optionally have an image.

Package

capi

Superclasses

choice
simple-pane
sorted-object
titled-object

Subclasses

list-view
multi-column-list-panel

Initargs
:right-click-selection-behavior
A keyword or nil. Controls the behavior on a right mouse button click.
:color-function
A function designator or nil. Controls item text color on Microsoft Windows, Cocoa and GTK+.
:alternating-background
A boolean influencing the use of alternating background color on Cocoa and GTK+.
:filter
A boolean. The default value is nil. Only used when filter is non-nil.
:the
:filter-automatic-p
A boolean. The default value is t. Only used when filter is non-nil.
:filter-callback
A function designator or the keyword :default, which is the default value. Only used when filter is non-nil.
:filter-change-callback-p
A boolean. Only used when filter is non-nil.
:filter-short-menu-text
A boolean. The default value is nil. Only used when filter is non-nil.
:filter-matches-title
A string, t or nil. Only used when filter is non-nil.
:filter-help-string
A string, t or nil. Only used when filter is non-nil.
:filter-added-filters
A list of additional filter specifications.
:keyboard-search-callback
A function that is used to search for an item when the user types ordinary characters.
:image-function
Returns an image for an item.
:state-image-function
Returns a state image for an item.
:image-lists
A plist of keywords and image-list objects.
:use-images
Flag to specify whether items have images. Defaults to t.
:use-state-images
Flag to specify whether items have state images. Defaults to nil.
:image-width
Defaults to 16.
:image-height
Defaults to 16.
:state-image-width
Defaults to image-width.
:state-image-height
Defaults to image-height.
:separators
One of nil (the default), :horizontal, :vertical, :both or t.
Accessors

list-panel-right-click-selection-behavior
list-panel-keyboard-search-callback
list-panel-image-function
list-panel-state-image-function

Description

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.

list-panel 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.

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.

Description: Filter

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 simultaneously, 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-callback 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 using the filtering-layout initargs :matches-title and :help-string respectively. 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.

When filter-added-filters is non-nil, it adds additional filters that apply to the items of the list-panel. Each element of filter-added-filters must be one of:

A cons of a string and a function.

This specifies a check-button, with the string as its text, plus an associated function.

A list of conses, where each cons is a cons of a string and a function.

This specifies an option-pane, where the string of each cons specifies the text of an item in the option-pane, plus an associated function for the item. The function can also be nil, which means no filtering.

The check-button and option-pane panes are displayed in the same row as the filter.

Before checking if an item in the list-panel matches the filter's text, the filter passes the item to the associated function from each selected check-button and from the selected item of each option-pane (unless the associated function is nil). If any of these functions returns nil, then the item is excluded (so it is not displayed). Note that the Exclude setting of the filter does not apply to the added filters, and the functions are called with the item in the list-panel, rather than its printed representation.

Any change in the selection of any of the check-button and option-pane panes causes the filter to be applied, which recomputes the displayed items.

There is a simple example of using filter-added-filters in:

(example-edit-file "capi/choice/filter-added-filters")
Notes: Filter

If you use filter:

  1. You should not rely on the element-parent of the list-panel, because it is implemented by wrapping some layouts around the list-panel.
  2. The filter is actually a filtering layout, so it has the same interactive semantics as filtering-layout.
Description: Keyboard search

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).

Notes: Keyboard search

keyboard-search-callback is intended for searching, but it is not limited to doing a search, and in fact can be used for implementing other functionality. However, since the system waits for the result, if the callback does something heavy or interacts with the user, it should schedule it in some way and return, for example:

(defun my-keyboard-search-callback (pane string pos)
  (declare (ignore pane pos))
  ;; cause a call to display-message in event loop
  (mp:current-process-send
   (list 'capi:display-message
         (format nil "You pressed  ~a" string)))
  nil ; return nil so do nothing
  )
Description: Images

The image-function is called on an item to return an image associated with the item. It can return 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. 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
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 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.

:normal
Specifies an image-list object that contains the item images. The image-function should return a numeric index into this image-list.
:state
Specifies an image-list object that contains the state images. The state-image-function should return a numeric index into this image-list.
Description: Right-click selection behavior

right-click-selection-behavior can take the following values:

nil
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.

:temporary-selection

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.

:temporary-restore

A synonym for :existing-or-clicked/restore/restore.

:clicked/restore/discard

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.

:temporary-always

A synonym for :clicked/restore/discard.

:clicked/restore/restore

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.

:discard-selection

A synonym for :existing-or-clicked/discard/discard.

: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.

:discard-always

A synonym for :clicked/discard/discard.

:no-change

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.

separators controls whether there are separators. Horizontal separators means that each row is separated from the previous row by a horizontal line. Vertical separators are applicable only in multi-column-list-panel, and means that by default each column is separated by a vertical line from the previous column. This can be overridden by the :separator option in the column specification (see entry for multi-column-list-panel). If separators is nil (the default), there are no separators. :both and t are equivalent, and specify both horizontal and vertical separators. :horizontal and :vertical specify separators for one direction.

Examples
(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 this example:

(example-edit-file "capi/choice/list-panel-pane-menu")

There are further examples here:

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

This example illustrates the use of color-function:

(example-edit-file "capi/applications/simple-symbol-browser")

There are further examples in 20 Self-contained examples.

See also

button-panel
double-list-panel
1.2.1 CAPI elements
3.1.4.1 Controlling Mnemonics
19.3.2 Matching resources for GTK+
5 Choices - panes with items
7 Programming with CAPI Windows
10.2.3 Prompting for an item in a list
13.10 Working with images
17 Drag and Drop


CAPI User Guide and Reference Manual (Windows version) - 01 Dec 2021 19:33:57