LispWorks CAPI Reference Manual > 1 CAPI Reference Entries

NextPrevUpTopContentsIndex

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

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 the width of the columns.

:visible-min-width

Minimum width of the column.

:gap

Specifies an additional gap to the right of the text in the column.

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

The callback for clicking on the header.

:callback-type

Defines the arguments of the selection-callback .

:items

The items of the header object. 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.

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.

Note: similiar and enhanced functionality is provided by list-view.

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" "Pumkpin"))))

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" "Pumkpin"))))
 

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))
See also

collection
list-panel
list-view


LispWorks CAPI Reference Manual - 21 Dec 2009

NextPrevUpTopContentsIndex