tree-view

Initargs

:roots

A list of the root nodes.

:children-function

Returns the children of a node.

:image-function

Returns an image for a node.

:state-image-function

Returns a state image for a node.

:leaf-node-p-function

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 .

:retain-expanded-nodes

Specifies if the tree view remembers whether hidden nodes were expanded.

:expandp-function

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.

:use-images

Flag to specify whether items have images. Defaults to t .

:use-state-images

Flag to specify whether items have state images. Defaults to nil .

:image-width

Defaults to 16.

:image-height

Defaults to 16.

:state-image-width

Defaults to image-width .

:state-image-height

Defaults to image-height .

:action-callback-expand-p

A boolean. The default value is nil .

:right-click-extended-match

Controls the area within which selection by the mouse right button occurs. Default t .

:has-root-line

Controls whether the line and expanding boxes of the root nodes are drawn. Default t .

:checkbox-status

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.

:checkbox-next-map

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

:checkbox-parent-function

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

:checkbox-child-function

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

:checkbox-change-callback

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

:checkbox-initial-status

Specifies the initial status of specific items.

Description

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:

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 .

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

:normal

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

:state

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:

When the tree view needs to be neater. Note that the user does not have a mouse gesture to expand the root node. Normally the programmer would compensate for this by making some other gesture call (setf tree-view-expanded-p) .
If a children-function is not supplied, this can be used to create a pane like a list view with checkboxes (see below for details of checkboxes). This pane can be handled as if it is a typical choice, except that setting the items is done by (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:

Left mouse button on a checkbox changes its status
Space changes the status of all selected items.

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

When the status of an item changes:

The statuses of its ancestors may change if a checkbox-parent-function was supplied.
The statuses of an items descendents may change if a checkbox-child-function was supplied.
A callback given by checkbox-callback-function will be called, if this was supplied.

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

An array of statuses. When the user clicks on item 's checkbox, the status of item is used to index into checkbox-next-map , and the status at that index becomes the new status of item . For example, with the default checkbox-next-map, checked(0) changes to un-checked(2), grey-checked(1) changes to un-checked(2), and un-checked(2) changes to checked(0).
A function of two arguments. The first argument is a list of items and the second argument is their current status (and if the items have various statuses, the most common is used). checkbox-next-map should return the new status to use.
An integer: the status is increased by 1, until this integer is reached, at which point the status becomes 0 again.

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

tree-view

Class

Summary

Package

Superclasses

Initargs

Accessors

Readers

Description

See also