A list of the root nodes.
A plist of keywords and image-list objects.
Flag to specify whether items have images. Defaults to
Defaults to 16.
Defaults to 16.
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.
controls automatic expansion of nodes (items) in the
. By default, initially only the items specified by the
argument are displayed. This initial display can be altered by supplying a function
which allows further items to be displayed. If supplied,
should be a function which is called on the
and is called recursively on the children if it returns true. When the user expands a node,
is called on each newly created child node, which is expanded if this call returns true, and so on recursively. The default value of
so that there is no automatic expansion and only the root nodes are visible initially.
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 .
is called when the user presses the
key. Two arguments are passed: the
and the selected item
. Note that, apart from calling the callback, the system does nothing in response to the
key. In particular, if you want to remove the selected
needs to do it by changing what the
returns when called on the parent of
. Normally you also need to to call tree-view-update-item with
to actually update the tree on the screen.
Note also that in extended-selection-tree-view (a subclass of
), if the
was not explictly changed to
, the second argument to
is a list of the selected items (even when only one item is selected).
This specifies the filename of a file suitable for loading with load-image. Currently this must be a bitmap file.
The symbol must have been previously registered by means of a call to
. It can also one of the following symbols, which map to standard images:
On Microsoft Windows, the following symbols are also recognized. They map to view images:
An image object, as returned by load-image.
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.
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.
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
to indicate that there is no state image. See also
, which overrides the
If image-lists is specified, it should be a plist containing the following keywords as keys. The corresponding values should be image-list objects.
object that contains the item images. The
should return a numeric index into this
object that contains the state images. The
should return a numeric index into this
, 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
(setf tree-view-roots)or by passing
make-instance. In a typical choice, you would do
(setf collection-items)or pass
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 .
The status can also be read and set programmatically (see tree-view-item-checkbox-status).
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.
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:
, then the status of
is set to
is non-nil, then the system recurses up from parent, and if
is non-nil, the system recurses down. The default
is non-nil and
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))
is displayed, its status is set from this list or, if item is not specified, from
. 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.
:selected-itemhas no effect. See the examples in interface-display for a way to set the selected item in a tree view.
tree-viewis 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-viewdo not pass
:items-map-function, and do not use the corresponding accessors.
tree-viewafter its selection-callback returns. If you need this callback to set the focus elsewhere, call set-pane-focus outside the callback, like this:
CAPI Reference Manual - 15 Dec 2011