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

tree-view Class


A tree view is a pane that displays a hierarchical list of items. Each item may optionally have an image and a checkbox.





A list of the root items.
Returns the children of an item and hence defines the hierarchy in the tree.
Optional function which determines whether an item is a leaf item (that is, has no children). This is useful if it can be computed faster than the children-function.
Specifies if the tree view remembers whether hidden nodes were expanded.
A designator for a function of one argument, or nil.
A boolean. The default value is nil.
A function designator for a function of two arguments.
Controls the area within which selection by the mouse right button occurs. Default t.
Controls whether the line and expanding boxes of the root items are drawn. Default t.
Controls whether the tree has checkboxes. If non-nil, the value should be a non-negative integer less than the length of the image-list, or t. An integer specifies the default initial status, and t means the same as 2 (that is, by default the checkboxes are checked initially). The default is nil, meaning no checkboxes. Not implemented on Cocoa.
Controls the change in status when the user clicks on a checkbox. Can be an array, a function or an integer. Default #(2 2 0). Not implemented on Cocoa.
Controls the changes in the ancestors when the status of an item is changed. Not implemented on Cocoa.
Controls the changes in the descendants when the status of an item is changed. Not implemented on Cocoa.
A function called when the status of an item is changed interactively. Not implemented on Cocoa.
Specifies the initial status of specific items. Not implemented on Cocoa.
Returns an image for an item.
Returns a state image for an item.
A plist of keywords and image-list objects.
Flag to specify whether items have images. Defaults to t.
Flag to specify whether items have state images. Defaults to nil.
Defaults to 16.
Defaults to 16.
Defaults to image-width.
Defaults to image-height.





The class tree-view is a pane that displays a hierarchical list of items. Each item may optionally have an image and a checkbox.

The tree view pane allows the user to select between items displayed in a hierarchical list. Although it is a choice, only :single-selection interaction is supported. Use extended-selection-tree-view if you need other selection interaction styles.

The hierarchy of items in the tree is defined by the children-function, which must be a function taking a single argument (an item) and returning a list of child items. When an item is expanded, whether programmatically, automatically, or in response to a user gesture, the system calculates what children this item has by calling the children-function on it.

Both the roots and what children the children-function returns for an item can be any object. However, the list must not include an object which is cl:eql to another object in the tree. To work sensibly it also needs to be consistent over time, that is return the same objects each time it is called, unless the state of the entity that the tree represents changes. It should also be reasonably fast, as the user will be waiting to see the items.

If the tree is supposed to display items that are "the same" in different parts of the tree, you can define a "wrapper", typically cl:defstruct with a few slots, and return a list of these wrappers (each pointing to the actual object). This wrapping is also useful for keeping other information related to the display in the tree, for example the string or the image to display, and maybe cache the children.

If leaf-node-p-function is not supplied, the children-function is also used to decide whether unexpanded nodes are leaf items or not (and hence whether to display the expanding box). If the children-function is slow, this may slow significantly the display of large trees. If it is possible to check for the existence of children faster, you should supply leaf-node-p-function to avoid this slow down.

The default value of children-function is (constantly false), that is no children, and hence only the roots are displayed.

expandp-function controls automatic expansion of nodes (items) in the tree-view. By default, initially only the items specified by the roots argument are displayed. This initial display can be altered by supplying a function expandp-function which allows further items to be displayed. If supplied, expandp-function should be a function which is called on the roots and is called recursively on the children if it returns true. When the user expands a node, expandp-function is called on each newly created child node, which is expanded if this call returns true, and so on recursively. The default value of expandp-function is nil so that there is no automatic expansion and only the root nodes are visible initially.

The default value of retain-expanded-nodes is t.

Any item which has children has a small expansion button next to it to indicate that it can be expanded. When the user clicks on this button, the children items (as determined by the children function) are displayed.

If action-callback-expand-p is true, then the activate gesture expands a collapsed node, and collapses an expanded node. This expansion and contraction of the node is additional to any supplied action-callback.

delete-item-callback is called when the user presses the Delete key. Two arguments are passed: the tree-view and the selected item item. Note that, apart from calling the callback, the system does nothing in response to the Delete key. In particular, if you want to remove the selected item, delete-item-callback needs to do it by changing what the children-function returns when called on the parent of item. Normally you also need to to call tree-view-update-item with in-parent = t to actually update the tree on the screen.

Note also that in extended-selection-tree-view (a subclass of tree-view), if the interaction was not explicitly changed to :single-selection, the second argument to delete-item-callback is a list of the selected items (even when only one item is selected).

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. It can also one of the following symbols, which map to standard images: :std-cut, :std-copy, :std-paste, :std-undo, :std-redo, :std-delete, :std-file-new, :std-file-open, :std-file-save, :std-print, :std-print-pre, :std-properties, :std-help, :std-find and :std-replace.

On Microsoft Windows, the following symbols are also recognized. They map to view images: :view-large-icons, :view-small-icons, :view-list, :view-details, :view-sort-name, :view-sort-size, :view-sort-date, :view-sort-type, :view-parent-folder, :view-net-connect, :view-net-disconnect and :view-new-folder.

Also on Microsoft Windows, these symbols are recognized. They map to history images: :hist-back, :hist-forward, :hist-favorites, :hist-addtofavorites and :hist-viewtree.

An image object
For example, as returned by load-image.
An image locator object

This 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, it also allows access to bitmaps stored as resources in a DLL.

An integer
This is a zero-based index into the tree-view's image lists. 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 objects listed above, just as for image-function, or nil to indicate that there is no state image. See also checkbox-status, which overrides the state-image-function.

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

Specifies an image-list object that contains the item images. The image-function should return a numeric index into this image-list.
Specifies an image-list object that contains the state images. The state-image-function should return a numeric index into this image-list.

If right-click-extended-match is nil, the mouse right button gesture within the tree view selects an item only when the cursor is on the item. Otherwise, this gesture also selects an item to the left or right of the cursor. The default for right-click-extended-match is t.

If has-root-line is nil, the vertical root line and expanding boxes of the root items are not drawn. This is useful in two cases:

The default for has-root-line is t.

If the checkbox-status is non-nil then the tree view provides an automatic way of using the state images as checkboxes (except on Cocoa where check boxes are not supported). The state-image is defaulted to a set of images containing checkboxes and the state-image-function is ignored, but each item has a status that is a non-negative integer no greater than the number of images in state-image-list. The status specifies which image is displayed alongside item.

When item is expanded in the tree for the first time, the status of each child is set to item's status. The status can be changed interactively by the user:

The status can also be read and set programmatically (see tree-view-item-checkbox-status).

When the status of an item changes:

By default checkboxes have three statuses indicated by images: un-checked(0), gray-checked(1) and checked(2). If an item is checked or un-checked, then all its descendants have the same status. If an item is gray-checked, then its descendants have various statuses. When the status of an item changes, all the descendants of that item change to the same status, and all its ancestors change to gray-checked.

For non-default status-changing behavior, specify checkbox-next-map. The value can be:

When the status of an item is changed, the statuses of items above and below it in the tree may also be changed: the system recurses up and down the tree using checkbox-parent-function and checkbox-child-function respectively.

To recurse upwards, checkbox-parent-function is called on the parent with five arguments: the parent, the parent's status, the item, the item's status and an flag which is non-nil if all the items at the same level as the item now have the same status:

checkbox-parent-function parent parent-status item item-status all-items-same-p => new-parent-status, recurse-up, recurse-down

If new-parent-status differs from parent-status, then the status of parent is set to new-parent-status. If recurse-up is non-nil, then the system recurses up from parent, and if recurse-down is non-nil, the system recurses down. The default checkbox-parent-function returns (values new-item-status t nil) where new-item-status is item-status if all-items-same-p is non-nil and 1 otherwise.

To recurse downwards, checkbox-child-function is called on each child with four arguments and the results are used similarly to those of checkbox-parent-function:

checkbox-child-function child child-status item item-status => new-child-status, recurse-up, recurse-down

The default checkbox-child-function returns (values parent-status nil t).

Note: if an item has never been expanded, then it has no children. If an item has been collapsed, then it has children even though they are not currently visible.

checkbox-parent-function and checkbox-child-function should not modify the tree in any way.

checkbox-change-callback takes three arguments: the tree, a list of items and their new status:

checkbox-change-callback tree items new-status

This is called after the new statuses of items and their ancestors and descendants have been resolved.

checkbox-initial-status is used the first time that each specified item, which can be anywhere in the tree, appears. The value is a list of conses of items and their initial statuses, for example ((item1. 2) (item2. 0)). When item is displayed, its status is set from this list or, if item is not specified, from checkbox-status. Items are removed from the list when they are displayed and setting the list does not affect the checkbox status of items that have already been displayed. Note that check boxes are not supported on Cocoa.

The default value of vertical-scroll in a tree-view is t.

  1. Since the items of a tree view are not computed until display time, the choice initarg :selected-item has no effect. See the examples in interface-display for a way to set the selected item in a tree view.
  2. Although tree-view is a subclass of collection, it does its own items handling and you must not access its items and related slots directly. In particular for tree-view do not pass :items, :items-count-function, :items-get-function or :items-map-function, and do not use the corresponding accessors.
  3. On Microsoft Windows, the system always sets the input focus to the tree-view after its selection-callback returns. If you need this callback to set the focus elsewhere, call set-pane-focus outside the callback, like this:
    (mp:process-send process
      (list 'capi:set-pane-focus pane))

This example shows how to combine an XML parser with tree-view to display an RSS file.

(example-edit-file "capi/applications/rss-reader")

There are further examples in 20 Self-contained examples.

See also

1.2.1 CAPI elements
5 Choices - panes with items
13.10 Working with images
17 Drag and Drop

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