@DefaultProperty("root")
public class TreeView<T>
  Comment     Returned-by     Constructor-argument     Method-argument     Field-type     Type-bound     Links  

The TreeView control provides a view on to a tree root (of type TreeItem). By using a TreeView, it is possible to drill down into the children of a TreeItem, recursively until a TreeItem has no children (that is, it is a leaf node in the tree). To facilitate this, unlike controls like ListView, in TreeView it is necessary to only specify the root node.

For more information on building up a tree using this approach, refer to the TreeItem class documentation. Briefly however, to create a TreeView, you should do something along the lines of the following:


 TreeItem<String> root = new TreeItem<String>("Root Node");
 root.setExpanded(true);
 root.getChildren().addAll(
     new TreeItem<String>("Item 1"),
     new TreeItem<String>("Item 2"),
     new TreeItem<String>("Item 3")
 );
 TreeView<String> treeView = new TreeView<String>(root);
 

A TreeView may be configured to optionally hide the root node by setting the showRoot property to false. If the root node is hidden, there is one less level of indentation, and all children nodes of the root node are shown. By default, the root node is shown in the TreeView.

TreeView Selection / Focus APIs

To track selection and focus, it is necessary to become familiar with the SelectionModel and FocusModel classes. A TreeView has at most one instance of each of these classes, available from selectionModel and focusModel properties respectively. Whilst it is possible to use this API to set a new selection model, in most circumstances this is not necessary - the default selection and focus models should work in most circumstances.

The default SelectionModel used when instantiating a TreeView is an implementation of the MultipleSelectionModel abstract class. However, as noted in the API documentation for the selectionMode property, the default value is SelectionMode.SINGLE. To enable multiple selection in a default TreeView instance, it is therefore necessary to do the following:

 
 treeView.getSelectionModel().setSelectionMode(SelectionMode.MULTIPLE);

Customizing TreeView Visuals

The visuals of the TreeView can be entirely customized by replacing the default cell factory. A cell factory is used to generate TreeCell instances, which are used to represent an item in the TreeView. See the Cell class documentation for a more complete description of how to write custom Cells.

Editing

This control supports inline editing of values, and this section attempts to give an overview of the available APIs and how you should use them.

Firstly, cell editing most commonly requires a different user interface than when a cell is not being edited. This is the responsibility of the Cell implementation being used. For TreeView, this is the responsibility of the cell factory. It is your choice whether the cell is permanently in an editing state (e.g. this is common for CheckBox cells), or to switch to a different UI when editing begins (e.g. when a double-click is received on a cell).

To know when editing has been requested on a cell, simply override the javafx.scene.control.Cell.startEdit() method, and update the cell text and graphic properties as appropriate (e.g. set the text to null and set the graphic to be a TextField). Additionally, you should also override Cell.cancelEdit() to reset the UI back to its original visual state when the editing concludes. In both cases it is important that you also ensure that you call the super method to have the cell perform all duties it must do to enter or exit its editing mode.

Once your cell is in an editing state, the next thing you are most probably interested in is how to commit or cancel the editing that is taking place. This is your responsibility as the cell factory provider. Your cell implementation will know when the editing is over, based on the user input (e.g. when the user presses the Enter or ESC keys on their keyboard). When this happens, it is your responsibility to call Cell.commitEdit(Object) or Cell.cancelEdit(), as appropriate.

When you call Cell.commitEdit(Object) an event is fired to the TreeView, which you can observe by adding an EventHandler via TreeView.setOnEditCommit(javafx.event.EventHandler). Similarly, you can also observe edit events for edit start and edit cancel.

By default the TreeView edit commit handler is non-null, with a default handler that attempts to overwrite the property value for the item in the currently-being-edited row. It is able to do this as the Cell.commitEdit(Object) method is passed in the new value, and this is passed along to the edit commit handler via the EditEvent that is fired. It is simply a matter of calling EditEvent.getNewValue() to retrieve this value.

It is very important to note that if you call TreeView.setOnEditCommit(javafx.event.EventHandler) with your own EventHandler, then you will be removing the default handler. Unless you then handle the writeback to the property (or the relevant data source), nothing will happen. You can work around this by using the TreeView.addEventHandler(javafx.event.EventType, javafx.event.EventHandler) method to add a TreeView.EDIT_COMMIT_EVENT EventType with your desired EventHandler as the second argument. Using this method, you will not replace the default implementation, but you will be notified when an edit commit has occurred.

Hopefully this summary answers some of the commonly asked questions. Fortunately, JavaFX ships with a number of pre-built cell factories that handle all the editing requirements on your behalf. You can find these pre-built cell factories in the javafx.scene.control.cell package.

extends Control

Parameters:
<T>    The type of the item contained within the TreeItem value property for all tree items in this TreeView.

See also:
TreeItem, TreeCell

Since:  JavaFX 2.0