All Manuals > CAPI Reference Manual > 1 CAPI Reference Entries




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


Returns the children of a node.


Optional function which determines whether a node is a leaf node (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 nodes are drawn. Default t .

Initargs for handling check boxes. Note that these do not work on Cocoa:


Controls whether the tree has checkboxes, except on Cocoa. 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.


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


Controls the changes in the ancestors when the status of an item is changed.


Controls the changes in the descendents when the status of an item is changed.


A function called when the status of an item is changed interactively.


Specifies the initial status of specific items.

Initargs for handling images:


Returns an image for a node.


Returns a state image for a node.


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

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 nodes (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 explictly 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, 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 nodes 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), grey-checked(1) and checked(2). If an item is checked or un-checked, then all its decendents have the same status. If an item is grey-checked, then its descendents have various statuses. When the status of an item changes, all the descendents of that item change to the same status, and all its ancestors change to grey-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 descendents 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:
  (list 'capi:set-pane-focus 
See also


CAPI Reference Manual - 15 Dec 2011