tree-view

Initargs

:roots

A list of the root items.

:children-function

Returns the children of an item and hence defines the hierarchy in the tree.

:leaf-node-p-function

Optional function which determines whether an item is a leaf item (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

A designator for a function of one argument, or nil.

:action-callback-expand-p

A boolean. The default value is nil.

:delete-item-callback

A function designator for a function of two arguments.

: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 items are drawn. Default t.

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

:checkbox-status

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.

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

Initargs for handling images:

:image-function

Returns an image for an item.

:state-image-function

Returns a state image for an item.

:image-lists

A plist of keywords and image-list objects.

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

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

Both the roots and what children the children-function 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.

The default value of children-function is (constantly false), that is no children, and hence only the roots are displayed.

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

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

: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 items 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 item. 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 (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:

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

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), gray-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 descendants 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.

tree-view

Class

Summary

Package

Superclasses

Initargs

Accessors

Readers

Description

Notes

Examples

See also