1 CAPI Reference Entries

list-view

Class

Summary

The list view pane is achoice that displays its items as icons and text in a number of formats.

Superclasses

list-panel

Slots

view

Specifies which view the list view pane shows. The default is:icon.

subitem-function

Returns additional information to be displayed in report view.

subitem-print-functions

Used in report view to print the additional information.

image-function

Returns an image for an item

state-image-function

Returns a state image for an item.

columns

Defines the columns used in report view

auto-reset-column-widths

Determines whether columns automatically resize. Defaults to:all.

use-large-images

Indicates whether large icons will be used (generally only if the icon view will be used). Defaults tot.

use-small-images

Indicates whether small icons will be used. Defaults tot.

use-state-images

Indicates whether state images will be used. Defaults tonil.

large-image-width

Width of a large image. Defaults to 32.

large-image-height

Height of a large image. Defaults to 32.

small-image-width

Width of a small image. Defaults to 16.

small-image-height

Height of a small image. Defaults to 16.

state-image-width

Width of a state image. Defaults tosmall-image-width.

state-image-height

Height of a state image. Defaults tosmall-image-height.

Accessors

list-view-view list-view-subitem-function list-view-subitem-print-functions list-view-image-function list-view-state-image-function list-view-columns list-view-auto-reset-column-widths

Description

The list view inherits its functionality fromchoice. In many ways it may be regarded as a kind of enhanced list panel, although its behavior is not identical. It supports single selection and extended selection operation.

The list view displays its items in one of four ways, initially determined by the:view initarg, and subsequently changed by(setf list-view-view). An application may use the list view pane in just a single view, or may change the view between all four available views.

See the notes below on using both large and small icon views.

In all views, the text associated with the item (the label) is returned by the print-function, as with any other choice.

The icon view --:icon
In this view, large icons are displayed, together with their label, positioned in the space available.
The small icon view --:small-icon
In this view, small icons are displayed, together with their label, positioned in the space available.
The list view --:list
In this view, small icons are displayed, arranged in vertical columns.
The report view --:report
In this view, multiple columns are displayed. A small icon and the item's label is displayed in the first column. Additional pieces of information, known as subitems, are displayed in subsequent columns.
To use the report view,:columns must specify a list of column specifiers. Each column specifier is aplist, in which the following keywords are valid:

:title: The column heading
:width: The width of the column in pixels. If this keyword is omitted or has the valuenil, the width of the column is automatically calculated, based on the widest item to be displayed in that column.
:align: May be:left,:right or:center to indicate how items should be aligned in this column. The default is:left. Only left alignment is available for the first column.

Thesub-item-function is called on the item to return subitem objects that represent the additional information to be displayed in the subsequent columns. Hence, thesubitem-function should normally return a list, whose length is one less than the number of columns specified. Each subitem is then printed in its column using the appropriate subitem print function. Thesubitem-print-functions may be either a single print function, to be used for all subitems, or a list of functions: one for each subitem column.

Note that the first column always contains the item label, as determined by thechoice-print-function.

Theimage-function is called on an item to return an image associated with the item. It can return one of the following:

A pathname or string

This specifies the filename of a file suitable for loading withgp:load-image. Currently this must be a bitmap file.

A symbol

The symbol must have been previously registered by means of a call togp:register-image-translation.

An image object

As returned bygp:load-image.

An image locator object

Allowing a single bitmap to be created which contains several button images side by side. See make-image-locator for more information. On Windows, this also allows access to bitmaps stored as resources in a DLL.

An integer

This is a zero-based index into the list view's image list. This is generally only useful if the image list is created explicitly. See image-list for more details.

Thestate-image-function is called on an item to determine the state image, an additional optional image used to indicate the state of an item. It can return one of the above, ornil to indicate that there is no state image. State images may be used in any view, but are typically used in the report and list views.

If:image-lists is specified, it should be a plist containing the following keywords as keys. The corresponding values should beimage-list objects.

:normal: Specifies an image-list object that contains the large item images. Theimage-function should return a numeric index into this image-list.
:small: Specifies an image-list object that contains the small item images. The image-function should return a numeric index into this image-list.
:state: Specifies an image-list object that contains the state images. Thestate-image-function should return a numeric index into this image-list

If both the large icon view (icon view) and one or more of the small icon views (small icon view, list view, report view) are to be used, special considerations apply.

The image lists must be created explicitly, using the:image-listsinitarg, and theimage-function must return an integer. Care must be taken to ensure that corresponding images in the:normal and:smallimage lists have the same numeric index. This restriction will be relaxed in a future release.

Returning pathnames, strings or image-locators from the image function cause the CAPI to create the image-lists automatically; however, if large and small icon views are mixed, this will lead to incorrect icons (or no icons) being displayed in one or other view.