5.3 List panels

Lists of selectable items can be created with the list-panel class. Here is a simple example of a list panel:

Notice how the items in the list panel are passed as symbols, and a print-function is specified which controls how those items are displayed on the screen.

By default, list panels are single selection — that is, only one item in the list may be selected at once. You can use the :interaction keyword to change this:

You can add callbacks to any items in the list using the :selection-callback keyword.

5.3.1 List interaction

If you select different items in the list, only the last item you select remains highlighted. The way in which the items in a list panel interact upon selection can be controlled with the :interaction keyword.

The list produced in the example above is known as a single-selection list because only one item at a time may be selected. List panels are :single-selection by default.

There are also multiple-selection and extended-selection lists available. The possible interactions for list panels are:

:single-selection — only one item may be selected.
:multiple-selection — more than one item may be selected.
:extended-selection — see Extended selection.

To get a particular interaction, supply one of the values above to the :interaction keyword, like this:

(contain

 (make-instance

  'list-panel

  :items '("Red" "Green" "Blue")

  :interaction :multiple-selection))

Note that :no-selection is not a supported choice for list panels. To display a list of items with no selection possible you should use a display-pane.

5.3.2 Extended selection

Application users often want to make single and multiple selections from a list. Some of the time they want a new selection to deselect the previous one, so that only one selection remains — just like a :single-selection panel. On other occasions, they want new selections to be added to the previous ones — just like a :multiple-selection panel.

The :extended-selection interaction combines these two interactions. Here is an extended-selection list panel:

(contain

 (make-instance

  'list-panel

  :items '("Item" "Thing" "Object")

  :interaction :extended-selection))

Before continuing, here are the definitions of a few terms. The action you perform to select a single item is called the selection gesture . The action performed to select additional items is called the extension gesture . There are two extension gestures. To add a single item to the selection, the extension gesture is a click of the left button while holding down the Control key. For selecting a range of items, it is a click of the left button while holding down the Shift key.

5.3.3 Deselection, retraction, and actions

As well as selecting items, users often want to deselect them. Items in multiple-selection and extended-selection lists may be deselected.

In a multiple-selection list, deselection is done by clicking on the selected item again with either of the selection or extension gestures.

In an extended-selection list, deselection is done by performing the extension gesture upon the selected item. (If this was done using the selection gesture, the list would behave as a single-selection list and all other selections would be lost.)

Just like a selection, a deselection — or retraction — can have a callback associated with it.

For a multiple-selection list panel, there may be the following callbacks:

:selection-callback — called when a selection is made.
:retract-callback — called when a selection is retracted.

Consider the following example. The function set-title changes the title of the interface to the value of the argument passed to it. By using this as the callback to the check-button-panel, the title of the interface is set to the current selection. The retract-callback function displays a message dialog with the name of the button retracted.

Display the example window:

(defun set-title (data interface)

  (setf (interface-title interface)

        (format nil "~A" (string-capitalize data))))

(setq check-button-panel

      (make-instance 'check-button-panel

                     :items '(one two three four five)

                     :print-function 'string-capitalize

                     :selection-callback 'set-title

                     :retract-callback 'test-callback))

(contain check-button-panel)

Figure 5.5 The example check button panel before the callback.

Try selecting one of the check buttons. The window title will change:

Figure 5.6 The example check button panel after the callback.

Now de-select the button. Notice that the retract-callback is called.

For an extended-selection list panel, there may be the following callbacks:

:selection-callback — called when a selection is made.
:retract-callback — called when a selection is retracted.
:extend-callback — called when a selection is extended.

Also available in extended-selection and single-selection lists is the action callback. This is called when you double-click on an item.

:action-callback — called when a double-click occurs.

5.3.5 Images and appearance

A list panel can include images displayed on the left of each item. To include images supply the initarg :image-function. You can use images from an image-list via the initarg :image-lists.

Additionally, state images are supported on Microsoft Windows, GTK+ and Motif, via the initarg :state-image-function and, if required, :image-lists.

A list panel can have an alternating background color on Cocoa and GTK+, when specified by the initarg :alternating-background.

5.3.6 Filters

You can add a filter to a list-panel by passing the :filter initarg.

List panel filters are used in the LispWorks IDE, for example in the Inspector tool.

When a list-panel has a filter, you can the state of the filter by using list-panel-filter-state. The accessor collection-items on a list-panel with a filter returns the items after filtering. The function list-panel-unfiltered-items can be used to retrieve all the items. (setf collection-items) resets the filter, and (setf list-panel-unfiltered-items) can be used to set the items without affecting the filter. The function list-panel-items-and-filter can be used to get or set the unfiltered items and filter state together. (setf list-panel-items-and-filter) is especially useful, because setting the items and the filters separately causes the list-panel to redisplay twice.

5.3.7 Multi-column list panels

multi-column-list-panel is a subclass of list-panel which has several columns. Each line in a multi-column-list-panel displays several strings corresponding to a single item. multi-column-list-panel takes an initarg :item-print-functions which specifies how to generate the strings. The initarg :columns specifies column properties including width, alignment, and title.

The columns can have headers, which can be active (that is, they have callbacks). In particular, the headers can be made to sort the items based on some key and comparison function, by supplying the header's selection-callback as :sort and defining sort-descriptions (inherited from sorted-object via list-panel) with types that match the titles of the columns.

For an example see:


(example-edit-file "capi/choice/multi-column-list-panels")