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

list-view Class

Summary

The list view pane is a choice that displays its items as icons and text in a number of formats. Not implemented on Cocoa.

Package

capi

Superclasses

list-panel

Initargs
: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.
:image-lists
A plist of keywords and image-list objects.
:columns
Defines the columns used in report view.
:auto-reset-column-widths
Determines whether columns automatically resize. Defaults to :all.
:auto-arrange-icons
Determines whether icons are automatically arranged to fit the size of the window.
:use-large-images
Indicates whether large icons will be used (generally only if the icon view will be used). Defaults to t.
:use-small-images
Indicates whether small icons will be used. Defaults to t.
:use-state-images
Indicates whether state images will be used. Defaults to nil.
: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 to small-image-width.
:state-image-height
Height of a state image. Defaults to small-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
list-view-auto-arrange-icons

Description

The class list-view displays items as icons and text in a number of formats.

list-view inherits its functionality from choice. 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 interactions.

The list view displays its items in one of four ways, determined by the value in the view slot. An application may use the list view pane in just a single view, or may change the view between all four available views using (setf list-view-view).

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.

If auto-arrange-icons is true, then the icons are automatically arranged to fit the size of the window when the view is showing :icon or :small-icon. The default value of auto-arrange-icons is nil.

The subitem-function is called on the item to return subitem objects that represent the additional information to be displayed in the subsequent columns. Hence, subitem-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. subitem-print-function 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 the choice-print-function.

The image-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 with load-image. Currently this must be a bitmap file.

A symbol
The symbol must have been previously registered by means of a call to register-image-translation.
An image object
For example, as returned by 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 Microsoft 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.

The state-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, or nil 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 supplied, it should be a plist containing the following keywords as keys. The corresponding values should be image-list objects.

:normal
Specifies an image-list object that contains the large item images. The image-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. The state-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-lists initarg, and the image-function must return an integer. Take care to ensure that corresponding images in the :normal and :small image lists have the same numeric index.

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.

Notes
  1. list-view is not implemented on Cocoa.
  2. For some applications multi-column-list-panel will suffice instead of list-view.
See also

image-list
list-panel
make-image-locator
multi-column-list-panel
5.10.4 image-list, image-set and image-locator
13.10 Working with images


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