123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206 |
- ---
- title: Tree
- order: 26
- layout: page
- ---
-
- [[components.tree]]
- = Tree
-
- ifdef::web[]
- [.sampler]
- image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/grids-and-trees/tree"]
- endif::web[]
-
- [[components.tree.overview]]
- == Overview
-
- The [classname]#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.
- [classname]#Tree# is a selection component that allows selecting items.
-
- A typical use of the [classname]#Tree# component is for displaying a hierarchical menu, as illustrated in <<figure.components.tree>>, or for displaying file systems or hierarchical datasets.
-
- [[figure.components.tree]]
- .A [classname]#Tree# component
- image::img/tree-basic.png[width=70%, scaledwidth=100%]
-
- [[components.tree.data]]
- == Binding to Data
-
- [classname]#Tree# is used by binding it to a hierarchical data provider. The data provider can be based on in-memory or back end data. For in-memory data, the [classname]#TreeDataProvider# can be used, and for loading data from a back end, you need to implement three methods from the [interfacename]#HierarchicalDataProvider# interface. Usage of both data providers is described in
- <<../datamodel/datamodel-hierarchical.asciidoc#datamodel.hierarchical,"Hierarchical Data">>.
-
-
- The [classname]#TreeData# class can be used to build the hierarchical data structure,
- and it can then be passed on to [classname]#TreeDataProvider#. It is simply a hierarchical
- collection, that the data provider uses to populate the [classname]#Tree#.
-
- The [methodname]#setItems# method in [classname]#Tree# can be used to set the root level items. Internally
- an [classname]#TreeDataProvider# with [classname]#TreeData# is used.
-
- [source, java]
- ----
- // An initial planet tree
- Tree<String> tree = new Tree<>();
- TreeData<String> treeData = new TreeData<>();
-
- // Couple of childless root items
- treeData.addItem(null,"Mercury");
- treeData.addItem(null,"Venus");
-
- // Items with hierarchy
- treeData.addItem(null,"Earth");
- treeData.addItem("Earth","The Moon");
-
- inMemoryDataProvider = new TreeDataProvider<>(treeData);
- tree.setDataProvider(inMemoryDataProvider);
- tree.expand("Earth"); // Expand programmatically
- ----
-
- If at any time you want to modify
- the in-memory data in the tree, you may do it as follows:
-
- [source, java]
- ----
- // Add Mars with satellites
- treeData.addItem(null, "Mars");
- treeData.addItem("Mars", "Phobos");
- treeData.addItem("Mars", "Deimos");
- inMemoryDataProvider.refreshAll();
-
- ----
-
-
- The result was shown in <<figure.components.tree>>.
-
- The caption and the icon of tree items is generated by the [classname]#ItemCaptionGenerator# and the
- [classname]#IconGenerator#, set with [methodname]#setItemCaptionGenerator()# and [methodname]#setItemIconGenerator()# respectively.
-
- [[components.tree.selection]]
- == Handling Selection and Clicks
-
- [classname]#Tree# supports single selection mode, you can use [methodname]#asSingleSelect()# to access the selection
- object, which supports selection listeners and data binding. For more details, see link:<<../datamodel/datamodel-selection.asciidoc#datamodel.selection,"Selecting Items">>.
- The [classname]#Tree# also supports the shortcut method [methodname]#addSelectionListener()#.
-
- [classname]#Tree# also emits [classname]##ItemClickEvent##s when items are clicked.
- This way you can handle item clicks also when you want special user interaction specifically on clicks.
-
- [source, Java]
- ----
- tree.addItemClickListener(event ->
- Notification.show("Click",
- Notification.Type.HUMANIZED_MESSAGE)
- );
- ----
-
- [[components.tree.right.clicks]]
- === Right-clicks
- Right-clicks are supported similar way via `addContextClickListener()` method
-
- [source, java]
- ----
- tree.addContextClickListener(event -> Notification.show(
- ((TreeContextClickEvent<Person>)event).getItem() + " Clicked")
- );
- ----
-
- [[components.tree.expandcollapse]]
- == Expanding and Collapsing Nodes
-
- [classname]#Tree# nodes that have children can be expanded and collapsed by either user interaction or through the server-side API:
-
- [source, java]
- ----
- // Expands a child project. If the child project is not yet
- // in the visible hierarchy, nothing will be shown.
- tree.expand(childProject);
- // Expands the root project. If child project now becomes
- // visible it is also expanded into view.
- tree.expand(rootProject);
- // Collapses the child project.
- tree.collapse(childProject);
- ----
-
- To use the server-side API with a backend data provider the [methodname]#hashCode# and [methodname]#equals# methods for the node's type must be implemented so that when the desired node is retrieved from the backend it can be correctly matched with the object passed to either [methodname]#expand# or [methodname]#collapse#.
-
- The [classname]#Tree# component supports listening to the expansion and collapsing of items in its hierarchy.
- The expand and collapse listeners can be added as follows:
-
- [source, java]
- ----
- tree.addExpandListener(event -> log("Item expanded: " + event.getExpandedItem()));
- tree.addCollapseListener(event -> log("Item collapsed: " + event.getCollapsedItem()));
- ----
-
- The return types of the methods `getExpandedItem` and `getCollapsedItem` are the same as the type of the [classname]#Tree# the events originated from.
- Note that collapse listeners will not be triggered for any expanded subtrees of the collapsed item.
-
- [[components.tree.node.collapsing]]
- == Prevent Node Collapsing
-
- [classname]#Tree# supports setting a callback method that can allow or prevent the user from collapsing an expanded node.
- It can be set with [methodname]#setItemCollapseAllowedProvider# method, that takes a [interfacename]#ItemCollapseAllowedProvider#.
- For nodes that cannot be collapsed, the [literal]#++collapse-disabled++# class name is applied to the expansion element
-
- Avoid doing any heavy operations in the method, since it is called for each item when it is being sent to the client.
-
- Example using a predefined set of persons that can not be collapsed:
- [source, java]
- ----
- Set<Person> alwaysExpanded;
- personTree.setItemCollapseAllowedProvider(person ->
- !alwaysExpanded.contains(person));
- ----
-
- [[components.treegrid.keyboard]]
- == Keyboard Navigation and Focus Handling in TreeGrid
-
- The user can navigate through rows with kbd:[Up] and kbd:[Down], collapse rows with kbd:[Left],
- and expand them with kbd:[Right].
-
- [[components.tree.css]]
- == CSS Style Rules
-
- [source, css]
- ----
- .v-tree8 {
- .v-tree8-scroller, .v-tree8-scroller-horizontal { }
- .v-tree8-tablewrapper {
- .v-tree8-body {
- .v-tree8-row,
- .v-tree8-stripe,
- .v-tree8-row-focused,
- .v-tree8-row-has-data {
- .v-tree8-expander, expanded {}
- .v-tree8-cell-content {}
- }
- }
- }
- }
- ----
-
- [[components.tree.css.itemstyles]]
- === Generating Item Styles
-
- You can style each tree item individually by generating a style name for them with a [interfacename]#StyleGenerator#, which you assign to a tree with [methodname]#setStyleGenerator()#.
- The generator should return a style name for each item or `null`.
-
- [source, Java]
- ----
- // Show all leaf nodes as disabled
- tree.setStyleGenerator(item -> {
- if (!tree.getDataProvider().hasChildren(item))
- return "leaf";
- return null;
- }
- );
- ----
-
- [source, css]
- ----
- .leaf .v-tree8-cell-content {
- background-color:green
- }
- ----
|