Tree

The Tree component allows a natural way to represent data that has hierarchical relationships. The user can drill down in the hierarchy by expanding items by clicking on the expand arrow, and likewise collapse items. Tree is a selection component that allows selecting items. It also supports drag and drop, so you can drag items to and from a tree, and drop them in the hierarchy.

A typical use of the Tree component is for displaying a hierarchical menu, as illustrated in A Tree component as a menu, or for displaying file systems or hierarchical datasets.

A Tree component as a menu

The data is managed in a container implementing the Hierarchical interface, such as HierarchicalContainer or FilesystemContainer. You can use ContainerHierarchicalWrapper to add hierarchical capability to any other container. Tree itself implements the interface and delegates operations to the underlying container.

Java

The result was shown in in a practical situation, with the wrapped inside a Panel. Tree itself does not have scrollbar, but Panel can be used for the purpose.

Tree is a selection component, which are described in “Selection Components”. You can thereby get or set the currently selected item by the value property of the tree, that is, with getValue() and setValue(). When the user selects an item, the tree will receive an ValueChangeEvent, which you can catch with a ValueChangeListener.

Java

// Handle selection changes
menu.addValueChangeListener(event -> { // Java 8
    if (event.getProperty() != null &&
        event.getProperty().getValue() != null) {
    }
});

Tree is selectable by default; you can disallow selection with setSelectable(false).

Tree also emits ItemClickEvents when items are clicked. This way you can handle item clicks also when selection is not enabled or you want special user interaction specifically on clicks.

Java

An item can have children only if the childrenAllowed property is set as true. The expand indicator is shown when and only when the property is true. The property is defined in the container and can be set with setChildrenAllowed().

Expanding an item fires an Tree.ExpandEvent and collapsing an Tree.CollapseEvent, which you can handle with respective listeners.

tree.addExpandListener(new Tree.ExpandListener() {
    public void nodeExpand(ExpandEvent event) {
        Notification.show("Expand!");
    }
});

You can expand and collapse items programmatically with expandItem() or expandItemRecursively().

Java

CSS

    .v-tree-node-caption {}  /* Caption of the node     */
    .v-tree-node-children {} /* Contains child nodes    */
  .v-tree-node-root {}       /* If node is a root node  */
  .v-tree-node-leaf {}       /* If node has no children */

You can style each tree item individually by generating a style name for them with a Tree.ItemStyleGenerator, which you assign to a tree with setItemStyleGenerator(). The generator should return a style name for each item or null.

Java

The style names are prefixed with v-tree-node-caption-. You could thereby define the item styling as follows:

CSS

.v-tree-node-caption-disabled {
    color: graytext;