A list of the root items.
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
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.
and what children the
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.
controls automatic expansion of nodes (items) in the
tree-view. 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
nil 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 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 .
is called when the user presses the
key. Two arguments are passed: the
tree-view 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
t to actually update the tree on the screen.
Note also that in extended-selection-tree-view (a subclass of
tree-view), if the
was not explicitly changed to
:single-selection, 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 register-image-translation. 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
nil 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.
image-list object that contains the item images. The
should return a numeric index into this
image-list object that contains the state images. The
should return a numeric index into this
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
(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), 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.
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
t nil) where
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)). When
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:
There are further examples in Self-contained examples.
Choices - panes with items
Working with images
Drag and Drop
CAPI User Guide and Reference Manual (Macintosh version) - 3 Aug 2017