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

multi-column-list-panel Class

Summary

A list panel with multiple columns of text.

Package

capi

Superclasses

list-panel

Initargs
:column-function
A function of one argument or a list of functions 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.
:reorderable-columns
A boolean. The default is nil.
:x-adjust
A list. The default is nil.
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).

:reorderable

Has an effect only on GTK+. When non-nil, :reorderable specifies that the column is reorderable, that is the user can drag the header of the column to move the column to another position. Note that the initarg reorderable-columns forces all columns to be reorderable, overriding any :reorderable value in the column specification.

:separator

A boolean specifying whether the column has a separator from its previous column. The first column never has a separator. For columns that do not have this keyword, whether they have a separator is determined by the initarg :separators, which is inherited from list-panel and defaults to nil.

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.

reorderable-columns has effect only on GTK+. When reorderable-columns is non-nil, it makes all the columns in the multi-column-list-panel reorderable, so the user can change their order by dragging the header of a column. Note that you can also make only some columns reorderable by not using reorderable-columns, and instead using :reorderable in the column specification.

If x-adjust is non-nil, then it specifies the adjust values for each columns, that is it has the same effect as having :adjust in each column specification with the value being the matching item in x-adjust. x-adjust (when non-nil) must be a list of the same length as columns, where each item is one of the keywords that :adjust in the column specification can accept. The value in x-adjust overrides any :adjust given in the column specification.

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

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 20 Self-contained examples.

See also

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


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:27