Class

Summary

A list panel with multiple columns of text.

Package

capi

Superclasses

list-panel

Initargs

:column-function

A function of one argument. The default is identity.

:item-print-functions

A function of one argument, or a list of such functions.

:columns

A list of column specifications.

:header-args

A plist of keywords and values.

:auto-reset-column-widths

A boolean. The default is t.

Description

The class multi-column-list-panel is a list panel which displays multiple columns of text. The columns can each have a title.

Note that this is a subclass of list-panel, and hence of choice, and inherits the behavior of those classes.

Each item in a multi-column-list-panel is displayed in a line of multiple objects. The corresponding objects of each line are aligned in a column.

The column-function generates the objects for each item. It should take an item as its single argument and return a list of objects to be displayed. The default column-function is identity, which works if each item is a list.

column-function can also be a list of function designators. In this case the length has to match the length of the columns . Each function is called with the item to generate the object for the corresponding column.

The item-print-functions argument determines how to calculate the text to display for each element. If item-print-functions is a single function, it is called on each object, and must return a string. Otherwise item-print-functions should be a sequence of length no less than than the number of columns. The text to display for each object is the result (again, a string) of calling the corresponding element of item-print-functions on that object.

The columns argument specifies the number of columns, and whether the columns have titles and callbacks on these titles.

Each element of columns is a specification for a column. Each column specification is a plist of keyword and values, where the allowed keywords are as follows:

:title

Specifies the title to use for the column. If any of the columns has a title, a header object is created which displays the titles. The values of the :title keywords are passed as the items of the header, unless header-args specifies :items.

:adjust

Specifies how to adjust the column. The value can be one of :right, :left, or :center.

:width

Specifies a fixed width of the column.

:default-width

Specifies the default initial width of the column. The user can resize it. If :width is supplied it overrides :default-width.

:visible-min-width

Minimum width of the column.

:gap

Specifies an additional gap alongside the text in the column. :gap is not supported consistently across platforms (see Notes below).

The values of :width, :visible-min-width and :gap are interpreted as standard geometric hints. See element for information about these hints.

columns should indicate how many columns to display. At a minimum the value needs to be (() ()) for two columns without any titles

header-args is a plist of initargs passed to the header which displays the titles of the columns. The header object is a collection. The following collection initargs are useful to pass in header-args :

:selection-callback

A callback function for clicking on the header, or the keyword :sort which specifies sorting as described below.

:callback-type

Defines the arguments of the selection-callback .

:items

The items of the header object, that is the titles. Note that :items overrides :title if that is supplied in columns .

:print-function

Controls how each of items is printed, providing the title of each column.

header-args may also contain the keyword :alignments. The value should be a list of alignment keywords, each of which is interpreted like an :adjust value in columns . The alignment is applied to the title only.

When the callback is :sort, clicking on a header causes a call to sorted-object-sorted-by on the pane, with sort-type the title of the column, as given either by :items or :title in the columns. To make it work, you also need to define the sort-definitions , by making the pane with sort-descriptions with types that match the titles (see sorted-object and make-sorting-description).

If auto-reset-column-widths is true, then the widths of the columns are recomputed when the items of the multi-column-list-panel are set.

Notes

1. Similar and enhanced functionality is provided by list-view.
2. On Microsoft Windows, :width in a column specification does not actually make the column width be fixed, though it does supply the initial width.
3. On Microsoft Windows, :gap in a column specification adds the gap on both sides of the text. On Motif it adds the gap only on the right side of the text. On GTK+ and Cocoa :gap is ignored.
4. The number of columns in a multi-column-list-panel, their titles and what they show can be changed after the pane is displayed using modify-multi-column-list-panel-columns.

Example

This example uses the columns initarg:

(capi:contain

 (make-instance 

  'capi:multi-column-list-panel

  :visible-min-width 300

  :visible-min-height :text-height

  :columns '((:title "Fruits" 

              :adjust :right 

              :width (character 15))

             (:title "Vegetables" 

              :adjust :left 

              :visible-min-width (character 30)))

  :items '(("Apple" "Artichoke")

           ("Pomegranate" "Pumpkin"))))

This example uses header-args to add callbacks and independent alignment on the titles:

(defun mclp-header-callback (interface item)

  (declare (ignorable interface))

  (capi:display-message "Clicked on ~a" item))

(capi:contain

 (make-instance

  'capi:multi-column-list-panel

  :visible-min-width 300

  :visible-min-height :text-height

  :columns '((:adjust :right 

              :width (character 15))

             (:adjust :left 

              :visible-min-width (character 30)))

  :header-args '(:items ( "Fruits" "Vegetables")

                 :selection-callback 

                 mclp-header-callback

                 :alignments (:left :right))

  :items '(("Apple" "Artichoke")

           ("Pomegranate" "Pumpkin"))))

This example file illustrates the use of the header's selection-callback :sort to implement sorting of the columns:

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

This example uses column-function to implement a primitive process browser:

(defun get-process-elements (process)

  (list (mp:process-name process)

        (mp:process-whostate process)

        (mp:process-priority process)))

(capi:contain

 (make-instance 

  'capi:multi-column-list-panel

  :visible-min-width '(character 70)

  :visible-min-height '(character 15)

  :items (mp:list-all-processes)

  :columns '((:title "Name" :adjust :left

              :visible-min-width (character 30))

             (:title "State" :adjust :center 

              :visible-min-width (character 20))

             (:title "Priority" :adjust :center 

              :visible-min-width (character 12)))

  :column-function 'get-process-elements))

There are further examples in Self-contained examples.

See also

collection
list-panel
list-view
make-sorting-description
modify-multi-column-list-panel-columns
sorted-object-sorted-by
Multi-column list panels