Class

Summary

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.

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 and GTK+.

:filter

A boolean. The default value is nil .

The following initargs take effect only when filter is non-nil.

:filter-automatic-p

A boolean. The default value is t .

:filter-callback

A function designator or the keyword :default , which is the default value.

:filter-change-callback-p

A boolean.

:filter-short-menu-text

A boolean. The default value is nil .

:filter-matches-title

A string, t or nil .

:filter-help-string

A string, t or nil .

Accessors

list-panel-right-click-selection-behavior

Description

The class list-panel gains most 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:

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 .

color-function allows you to control the text colors on Microsoft Windows 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

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:

filter-matches-title

:matches-title

filter-help-string

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

Notes

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.

Example

(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/ .

This example illustrates the use of color-function :

examples/capi/applications/simple-symbol-browser.lisp

See also

button-panel