multi-column-list-panel

multi-column-list-panel Class

Summary

A list panel with multiple columns of text.

Package

capi

Superclasses

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

Similar and enhanced functionality is provided by list-view.
On Microsoft Windows, :width in a column specification does not actually make the column width be fixed, though it does supply the initial width.
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.
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.