TreeItem (JavaFX 19)
Description: declaration: module: javafx.controls, package: javafx.scene.control, class: TreeItem

Module javafx.controls
Package javafx.scene.control

# Class TreeItem<T>

java.lang.Object
javafx.scene.control.TreeItem<T>

Type Parameters:
  `T` - The type of the `value` property within TreeItem.

All Implemented Interfaces:
  `EventTarget`

Direct Known Subclasses:
  `CheckBoxTreeItem`

public class TreeItem<T> extends Object implements EventTarget
The model for a single node supplying a hierarchy of values to a control such as `TreeView`. The model may be implemented such that values may be loaded in memory as they are needed.

The model allows registration of listeners which will be notified as the number of items changes, their position or if the values themselves change. Note however that a TreeItem is not a Node, and therefore no visual events will be fired on the TreeItem. To get these events, it is necessary to add relevant observers to the TreeCell instances (via a custom cell factory - see the `Cell` class documentation for more details).

In the simplest case, TreeItem instances may be created in memory as such:

     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);

This approach works well for simple tree structures, or when the data is not excessive (so that it can easily fit in memory). In situations where the size of the tree structure is unknown (and therefore potentially huge), there is the option of creating TreeItem instances on-demand in a memory-efficient way. To demonstrate this, the code below creates a file system browser:

      private TreeView buildFileSystemBrowser() {
          TreeItem<File> root = createNode(new File("/"));
          return new TreeView<File>(root);
      }

      // This method creates a TreeItem to represent the given File. It does this
      // by overriding the TreeItem.getChildren() and TreeItem.isLeaf() methods
      // anonymously, but this could be better abstracted by creating a
      // 'FileTreeItem' subclass of TreeItem. However, this is left as an exercise
      // for the reader.
      private TreeItem<File> createNode(final File f) {
          return new TreeItem<File>(f) {
              // We cache whether the File is a leaf or not. A File is a leaf if
              // it is not a directory and does not have any files contained within
              // it. We cache this as isLeaf() is called often, and doing the
              // actual check on File is expensive.
              private boolean isLeaf;

              // We do the children and leaf testing only once, and then set these
              // booleans to false so that we do not check again during this
              // run. A more complete implementation may need to handle more
              // dynamic file system situations (such as where a folder has files
              // added after the TreeView is shown). Again, this is left as an
              // exercise for the reader.
              private boolean isFirstTimeChildren = true;
              private boolean isFirstTimeLeaf = true;

              @Override public ObservableList<TreeItem<File>> getChildren() {
                  if (isFirstTimeChildren) {
                      isFirstTimeChildren = false;

                      // First getChildren() call, so we actually go off and
                      // determine the children of the File contained in this TreeItem.
                      super.getChildren().setAll(buildChildren(this));
                  }
                  return super.getChildren();
              }

              @Override public boolean isLeaf() {
                  if (isFirstTimeLeaf) {
                      isFirstTimeLeaf = false;
                      File f = (File) getValue();
                      isLeaf = f.isFile();
                  }

                  return isLeaf;
              }

              private ObservableList<TreeItem<File>> buildChildren(TreeItem<File> TreeItem) {
                  File f = TreeItem.getValue();
                  if (f != null && f.isDirectory()) {
                      File[] files = f.listFiles();
                      if (files != null) {
                          ObservableList<TreeItem<File>> children = FXCollections.observableArrayList();

                          for (File childFile : files) {
                              children.add(createNode(childFile));
                          }

                          return children;
                      }
                  }

                  return FXCollections.emptyObservableList();
              }
          };
      }

TreeItem Events

TreeItem supports the same event bubbling concept as elsewhere in the scenegraph. This means that it is not necessary to listen for events on all TreeItems (and this is certainly not encouraged!). A better, and far more low cost solution is to instead attach event listeners to the TreeView `root` item. As long as there is a path between where the event occurs and the root TreeItem, the event will be bubbled to the root item.

It is important to note however that a TreeItem is not a Node, which means that only the event types defined in TreeItem will be delivered. To listen to general events (for example mouse interactions), it is necessary to add the necessary listeners to the `cells` contained within the TreeView (by providing a `cell factory`).

The TreeItem class defines a number of events, with a defined hierarchy. These are shown below (follow the links to learn more about each event type):

- `TreeItem.treeNotificationEvent()`
  - `TreeItem.valueChangedEvent()`
  - `TreeItem.graphicChangedEvent()`
  - `TreeItem.expandedItemCountChangeEvent()`
    - `TreeItem.branchExpandedEvent()`
    - `TreeItem.branchCollapsedEvent()`
    - `TreeItem.childrenModificationEvent()`

The indentation shown above signifies the relationship between event types. For example, all TreeItem event types have `treeNotificationEvent()` as their parent event type, and the branch `expand` / `collapse` event types are both `treeNotificationEvent()`. For performance reasons, it is encouraged to listen to only the events you need to listen to. This means that it is encouraged that it is better to listen to, for example, `TreeItem.valueChangedEvent()`, rather than `TreeItem.treeNotificationEvent()`.

Since:
  JavaFX 2.0
See Also:
  - `TreeView`

- ## Property Summary

  Properties
  Type
  Property
  Description
  `final BooleanProperty`
  `expanded`
  The expanded state of this TreeItem.
  `final ObjectProperty<Node>`
  `graphic`
  The node that is generally shown to the left of the value property.
  `final ReadOnlyBooleanProperty`
  `leaf`
  Represents the TreeItem leaf property, which is true if the TreeItem has no children.
  `final ReadOnlyObjectProperty<TreeItem<T>>`
  `parent`
  A property that represents the parent of this TreeItem.
  `final ObjectProperty<T>`
  `value`
  A property representing the application-specific data contained within this TreeItem.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `TreeItem.TreeModificationEvent<T>`
  An `Event` that contains relevant information for all forms of TreeItem modifications.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TreeItem()`
  Creates an empty TreeItem.
  `TreeItem(T value)`
  Creates a TreeItem with the value property set to the provided object.
  `TreeItem(T value, Node graphic)`
  Creates a TreeItem with the value property set to the provided object, and the graphic set to the provided Node.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<E extends Event>
  void`
  `addEventHandler(EventType<E> eventType, EventHandler<E> eventHandler)`
  Registers an event handler to this TreeItem.
  `static <T> EventType<TreeItem.TreeModificationEvent<T>>`
  `branchCollapsedEvent()`
  An EventType used when the TreeItem receives a modification to its expanded property, such that the TreeItem is now in the collapsed state.
  `static <T> EventType<TreeItem.TreeModificationEvent<T>>`
  `branchExpandedEvent()`
  An EventType used when the TreeItem receives a modification to its expanded property, such that the TreeItem is now in the expanded state.
  `EventDispatchChain`
  `buildEventDispatchChain(EventDispatchChain tail)`
  Construct an event dispatch chain for this target.
  `static <T> EventType<TreeItem.TreeModificationEvent<T>>`
  `childrenModificationEvent()`
  An EventType used when the TreeItem receives a direct modification to its children list.
  `static <T> EventType<TreeItem.TreeModificationEvent<T>>`
  `expandedItemCountChangeEvent()`
  The general EventType used when the TreeItem receives a modification that results in the number of children being visible changes.
  `final BooleanProperty`
  `expandedProperty()`
  The expanded state of this TreeItem.
  `ObservableList<TreeItem<T>>`
  `getChildren()`
  The children of this TreeItem.
  `final Node`
  `getGraphic()`
  Returns the node that is generally shown to the left of the value property.
  `final TreeItem<T>`
  `getParent()`
  The parent of this TreeItem.
  `final T`
  `getValue()`
  Returns the application-specific data represented by this TreeItem.
  `static <T> EventType<TreeItem.TreeModificationEvent<T>>`
  `graphicChangedEvent()`
  An EventType used when the TreeItem receives a modification to its graphic property.
  `final ObjectProperty<Node>`
  `graphicProperty()`
  The node that is generally shown to the left of the value property.
  `final boolean`
  `isExpanded()`
  Returns the expanded state of this TreeItem.
  `boolean`
  `isLeaf()`
  A TreeItem is a leaf if it has no children.
  `final ReadOnlyBooleanProperty`
  `leafProperty()`
  Represents the TreeItem leaf property, which is true if the TreeItem has no children.
  `TreeItem<T>`
  `nextSibling()`
  Returns the next sibling of the TreeItem.
  `TreeItem<T>`
  `nextSibling(TreeItem<T> afterNode)`
  Returns the next sibling after the given node.
  `final ReadOnlyObjectProperty<TreeItem<T>>`
  `parentProperty()`
  A property that represents the parent of this TreeItem.
  `TreeItem<T>`
  `previousSibling()`
  Returns the previous sibling of the TreeItem.
  `TreeItem<T>`
  `previousSibling(TreeItem<T> beforeNode)`
  Returns the previous sibling after the given node.
  `<E extends Event>
  void`
  `removeEventHandler(EventType<E> eventType, EventHandler<E> eventHandler)`
  Unregisters a previously registered event handler from this TreeItem.
  `final void`
  `setExpanded(boolean value)`
  Sets the expanded state of this TreeItem.
  `final void`
  `setGraphic(Node value)`
  Sets the node that is generally shown to the left of the value property.
  `final void`
  `setValue(T value)`
  Sets the application-specific data represented by this TreeItem.
  `String`
  `toString()`
  Returns a string representation of this `TreeItem` object.
  `static <T> EventType<TreeItem.TreeModificationEvent<T>>`
  `treeNotificationEvent()`
  The base EventType used to indicate that an event has occurred within a TreeItem.
  `static <T> EventType<TreeItem.TreeModificationEvent<T>>`
  `valueChangedEvent()`
  An EventType used when the TreeItem receives a modification to its value property.
  `final ObjectProperty<T>`
  `valueProperty()`
  A property representing the application-specific data contained within this TreeItem.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Property Details

  - ### value

    public final ObjectProperty<T> valueProperty
    A property representing the application-specific data contained within this TreeItem.
    See Also:
      - `getValue()`
      - `setValue(T)`

  - ### graphic

    public final ObjectProperty<Node> graphicProperty
    The node that is generally shown to the left of the value property. For best effect, this tends to be a 16x16 image.
    See Also:
      - `getGraphic()`
      - `setGraphic(Node)`

  - ### expanded

    public final BooleanProperty expandedProperty
    The expanded state of this TreeItem.
    See Also:
      - `isExpanded()`
      - `setExpanded(boolean)`

  - ### leaf

    public final ReadOnlyBooleanProperty leafProperty
    Represents the TreeItem leaf property, which is true if the TreeItem has no children.
    See Also:
      - `isLeaf()`

  - ### parent

    public final ReadOnlyObjectProperty<TreeItem<T>> parentProperty
    A property that represents the parent of this TreeItem.
    See Also:
      - `getParent()`

- ## Constructor Details

  - ### TreeItem

    public TreeItem()
    Creates an empty TreeItem.

  - ### TreeItem

    public TreeItem(T value)
    Creates a TreeItem with the value property set to the provided object.
    Parameters:
      `value` - The object to be stored as the value of this TreeItem.

  - ### TreeItem

    public TreeItem(T value, Node graphic)
    Creates a TreeItem with the value property set to the provided object, and the graphic set to the provided Node.
    Parameters:
      `value` - The object to be stored as the value of this TreeItem.
      `graphic` - The Node to show in the TreeView next to this TreeItem.

- ## Method Details

  - ### treeNotificationEvent

    public static <T> EventType<TreeItem.TreeModificationEvent<T>> treeNotificationEvent()
    The base EventType used to indicate that an event has occurred within a TreeItem. When an event occurs in a TreeItem, the event is fired to any listeners on the TreeItem that the event occurs, before it 'bubbles' up the TreeItem chain by following the TreeItem parent property. This repeats until a TreeItem whose parent TreeItem is null is reached At this point the event stops 'bubbling' and goes no further. This means that events that occur on a TreeItem can be relatively cheap, as a listener needs only be installed on the TreeView root node to be alerted of events happening at any point in the tree.
    Type Parameters:
      `T` - The type of the value contained within the TreeItem.
    Returns:
      the base EventType when an event has occurred within a TreeItem

  - ### expandedItemCountChangeEvent

    public static <T> EventType<TreeItem.TreeModificationEvent<T>> expandedItemCountChangeEvent()
    The general EventType used when the TreeItem receives a modification that results in the number of children being visible changes. This is normally achieved via one of the sub-types of this EventType (see `branchExpandedEvent()`, `branchCollapsedEvent()` and `childrenModificationEvent()` for the three sub-types).
    Type Parameters:
      `T` - The type of the value contained within the TreeItem.
    Returns:
      The general EventType when the TreeItem receives a modification
    Since:
      JavaFX 8.0

  - ### branchExpandedEvent

    public static <T> EventType<TreeItem.TreeModificationEvent<T>> branchExpandedEvent()
    An EventType used when the TreeItem receives a modification to its expanded property, such that the TreeItem is now in the expanded state.
    Type Parameters:
      `T` - The type of the value contained within the TreeItem.
    Returns:
      The EventType used when the TreeItem receives a modification

  - ### branchCollapsedEvent

    public static <T> EventType<TreeItem.TreeModificationEvent<T>> branchCollapsedEvent()
    An EventType used when the TreeItem receives a modification to its expanded property, such that the TreeItem is now in the collapsed state.
    Type Parameters:
      `T` - The type of the value contained within the TreeItem.
    Returns:
      The EventType when the TreeItem receives a modification

  - ### childrenModificationEvent

    public static <T> EventType<TreeItem.TreeModificationEvent<T>> childrenModificationEvent()
    An EventType used when the TreeItem receives a direct modification to its children list.
    Type Parameters:
      `T` - The type of the value contained within the TreeItem.
    Returns:
      The EventType when the TreeItem receives a direct modification to its children list

  - ### valueChangedEvent

    public static <T> EventType<TreeItem.TreeModificationEvent<T>> valueChangedEvent()
    An EventType used when the TreeItem receives a modification to its value property.
    Type Parameters:
      `T` - The type of the value contained within the TreeItem.
    Returns:
      The EventType when the TreeItem receives a modification to its value property

  - ### graphicChangedEvent

    public static <T> EventType<TreeItem.TreeModificationEvent<T>> graphicChangedEvent()
    An EventType used when the TreeItem receives a modification to its graphic property.
    Type Parameters:
      `T` - The type of the value contained within the TreeItem.
    Returns:
      The EventType when the TreeItem receives a modification to its graphic property

  - ### setValue

    public final void setValue(T value)
    Sets the application-specific data represented by this TreeItem.
    Parameters:
      `value` - the application-specific data

  - ### getValue

    public final T getValue()
    Returns the application-specific data represented by this TreeItem.
    Returns:
      the data represented by this TreeItem

  - ### valueProperty

    public final ObjectProperty<T> valueProperty()
    A property representing the application-specific data contained within this TreeItem.
    See Also:
      - `getValue()`
      - `setValue(T)`

  - ### setGraphic

    public final void setGraphic(Node value)
    Sets the node that is generally shown to the left of the value property. For best effect, this tends to be a 16x16 image.
    Parameters:
      `value` - The graphic node that will be displayed to the user.

  - ### getGraphic

    public final Node getGraphic()
    Returns the node that is generally shown to the left of the value property. For best effect, this tends to be a 16x16 image.
    Returns:
      The graphic node that will be displayed to the user.

  - ### graphicProperty

    public final ObjectProperty<Node> graphicProperty()
    The node that is generally shown to the left of the value property. For best effect, this tends to be a 16x16 image.
    See Also:
      - `getGraphic()`
      - `setGraphic(Node)`

  - ### setExpanded

    public final void setExpanded(boolean value)
    Sets the expanded state of this TreeItem. This has no effect on a TreeItem with no children. On a TreeItem with children however, the result of toggling this property is that visually the children will either become visible or hidden, based on whether expanded is set to true or false.
    Parameters:
      `value` - If this TreeItem has children, calling setExpanded with `true` will result in the children becoming visible. Calling setExpanded with `false` will hide any children belonging to the TreeItem.

  - ### isExpanded

    public final boolean isExpanded()
    Returns the expanded state of this TreeItem.
    Returns:
      Returns the expanded state of this TreeItem.

  - ### expandedProperty

    public final BooleanProperty expandedProperty()
    The expanded state of this TreeItem.
    See Also:
      - `isExpanded()`
      - `setExpanded(boolean)`

  - ### isLeaf

    public boolean isLeaf()
    A TreeItem is a leaf if it has no children. The isLeaf method may of course be overridden by subclasses to support alternate means of defining how a TreeItem may be a leaf, but the general premise is the same: a leaf can not be expanded by the user, and as such will not show a disclosure node or respond to expansion requests.
    Returns:
      true if this TreeItem has no children

  - ### leafProperty

    public final ReadOnlyBooleanProperty leafProperty()
    Represents the TreeItem leaf property, which is true if the TreeItem has no children.
    See Also:
      - `isLeaf()`

  - ### getParent

    public final TreeItem<T> getParent()
    The parent of this TreeItem. Each TreeItem can have no more than one parent. If a TreeItem has no parent, it represents a root in the tree model.
    Returns:
      The parent of this TreeItem, or null if the TreeItem has no parent.

  - ### parentProperty

    public final ReadOnlyObjectProperty<TreeItem<T>> parentProperty()
    A property that represents the parent of this TreeItem.
    See Also:
      - `getParent()`

  - ### getChildren

    public ObservableList<TreeItem<T>> getChildren()
    The children of this TreeItem. This method is called frequently, and it is therefore recommended that the returned list be cached by any TreeItem implementations.
    Returns:
      a list that contains the child TreeItems belonging to the TreeItem.

  - ### previousSibling

    public TreeItem<T> previousSibling()
    Returns the previous sibling of the TreeItem. Ordering is based on the position of the TreeItem relative to its siblings in the children list belonging to the parent of the TreeItem.
    Returns:
      A TreeItem that is the previous sibling of the current TreeItem, or null if no such sibling can be found.

  - ### previousSibling

    public TreeItem<T> previousSibling(TreeItem<T> beforeNode)
    Returns the previous sibling after the given node. Ordering is based on the position of the given TreeItem relative to its siblings in the children list belonging to the parent of the TreeItem.
    Parameters:
      `beforeNode` - The TreeItem for which the previous sibling is being sought.
    Returns:
      A TreeItem that is the previous sibling of the given TreeItem, or null if no such sibling can be found.

  - ### nextSibling

    public TreeItem<T> nextSibling()
    Returns the next sibling of the TreeItem. Ordering is based on the position of the TreeItem relative to its siblings in the children list belonging to the parent of the TreeItem.
    Returns:
      A TreeItem that is the next sibling of the current TreeItem, or null if no such sibling can be found.

  - ### nextSibling

    public TreeItem<T> nextSibling(TreeItem<T> afterNode)
    Returns the next sibling after the given node. Ordering is based on the position of the given TreeItem relative to its siblings in the children list belonging to the parent of the TreeItem.
    Parameters:
      `afterNode` - The TreeItem for which the next sibling is being sought.
    Returns:
      A TreeItem that is the next sibling of the given TreeItem, or null if no such sibling can be found.

  - ### toString

    public String toString()
    Returns a string representation of this `TreeItem` object.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of this `TreeItem` object.

  - ### buildEventDispatchChain

    public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail)
    Construct an event dispatch chain for this target. The event dispatch chain contains event dispatchers which might be interested in processing of events targeted at this `EventTarget`. This event target is not automatically added to the chain, so if it wants to process events, it needs to add an `EventDispatcher` for itself to the chain.

    In the case the event target is part of some hierarchy, the chain for it is usually built from event dispatchers collected from the root of the hierarchy to the event target.

    The event dispatch chain is constructed by modifications to the provided initial event dispatch chain. The returned chain should have the initial chain at its end so the dispatchers should be prepended to the initial chain.

    The caller shouldn't assume that the initial chain remains unchanged nor that the returned value will reference a different chain.

    Specified by:
      `buildEventDispatchChain` in interface `EventTarget`
    Parameters:
      `tail` - the initial chain to build from
    Returns:
      the resulting event dispatch chain for this target

  - ### addEventHandler

    public <E extends Event> void addEventHandler(EventType<E> eventType, EventHandler<E> eventHandler)
    Registers an event handler to this TreeItem. The TreeItem class allows registration of listeners which will be notified as the number of items changes, their position or if the values themselves change. Note however that a TreeItem is not a Node, and therefore no visual events will be fired on the TreeItem. To get these events, it is necessary to add relevant observers to the TreeCell instances (via a custom cell factory - see the `Cell` class documentation for more details).
    Type Parameters:
      `E` - The event
    Parameters:
      `eventType` - the type of the events to receive by the handler
      `eventHandler` - the handler to register
    Throws:
      `NullPointerException` - if the event type or handler is null

  - ### removeEventHandler

    public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHandler<E> eventHandler)
    Unregisters a previously registered event handler from this TreeItem. One handler might have been registered for different event types, so the caller needs to specify the particular event type from which to unregister the handler.
    Type Parameters:
      `E` - The event
    Parameters:
      `eventType` - the event type from which to unregister
      `eventHandler` - the handler to unregister
    Throws:
      `NullPointerException` - if the event type or handler is null