tree-view Class

Summary

A tree view is a pane that displays a hierarchical list of items. Each item may optionally have an image and a checkbox.

Package

capi

Superclasses

choice
titled-object
simple-pane

Initargs

Accessors

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-child-function
tree-view-checkbox-change-callback
tree-view-checkbox-initial-status

Readers

tree-view-checkbox-status

Description

The class tree-view is a pane that displays a hierarchical list of items. Each item may optionally have an image and a checkbox.

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:

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.

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.

Notes

1. 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.
2. Although tree-view is 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-view do not pass :items, :items-count-function, :items-get-function or :items-map-function, and do not use the corresponding accessors.
3. On Microsoft Windows, the system always sets the input focus to the tree-view after its selection-callback returns. If you need this callback to set the focus elsewhere, call set-pane-focus outside the callback, like this:

   (mp:process-send process
     (list 'capi:set-pane-focus pane))
   

Examples

This example shows how to combine an XML parser with tree-view to display an RSS file.

(example-edit-file "capi/applications/rss-reader")

There are further examples in 20 Self-contained examples.

See also

choice
extended-selection-tree-view
tree-view-ensure-visible
tree-view-expanded-p
tree-view-item-checkbox-status
tree-view-item-children-checkbox-status
tree-view-update-item
1.2.1 CAPI elements
5 Choices - panes with items
13.10 Working with images
17 Drag and Drop