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.
Returns a state image for a node.
A plist of keywords and image-list objects.
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.
Optional function which is called to decide whether a node should be displayed in expanded form. If not specified, all nodes are displayed collapsed, so only the root nodes are visible.
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.
A boolean. The default value is
nil
.
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
.
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. This integer specifies the default initial status. 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.
tree-view-roots
tree-view-children-function
tree-view-image-function
tree-view-state-image-function
tree-view-leaf-node-p-function
tree-view-retain-expanded-nodes
tree-view-expandp-function
tree-view-action-callback-expand-p
tree-view-right-click-extended-match
tree-view-has-root-line
tree-view-checkbox-next-map
tree-view-checkbox-parent-function
tree-view-checkbox-status
tree-view-checkbox-child-function
tree-view-checkbox-change-callback
tree-view-checkbox-initial-status
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.
Initially, only the items specified by the roots argument are displayed (unless an expandp-function is used, in which case further items may also be displayed).
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 .
The image-function is called on an item to return an image associated with the item. It can return one of the following:
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
.
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 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. 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:
(setf tree-view-expanded-p)
.
(setf tree-view-roots)
or by passing
:roots
to
make-instance
. In a typical choice, you would do
(setf collection-items)
or pass
:items
to
make-instance
.
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. 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 the its descendents have various statuses. When the status of an item changes, all the descendents of that item change to 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.
The default value of
vertical-scroll
in a
tree-view
is
t
.
Note:
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.
choice
tree-view-ensure-visible
tree-view-expanded-p
tree-view-item-checkbox-status
tree-view-item-children-checkbox-status
tree-view-update-item