T
- The type of the value
property within TreeItem.public class TreeItem<T>
extends java.lang.Object
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):
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()
.
TreeView
Type | Property and Description |
---|---|
BooleanProperty |
expanded
The expanded state of this TreeItem.
|
<any> |
graphic
The node that is generally shown to the left of the value property.
|
ReadOnlyBooleanProperty |
leaf
Represents the TreeItem leaf property, which is true if the TreeItem has no children.
|
<any> |
parent
A property that represents the parent of this TreeItem.
|
<any> |
value
A property representing the application-specific data contained within
this TreeItem.
|
Modifier and Type | Class and Description |
---|---|
static class |
TreeItem.TreeModificationEvent<T>
An
Event that contains relevant information for all forms of
TreeItem modifications. |
Modifier and Type | Field and Description |
---|---|
private static <any> |
BRANCH_COLLAPSED_EVENT |
private static <any> |
BRANCH_EXPANDED_EVENT |
(package private) <any> |
children |
private static <any> |
CHILDREN_MODIFICATION_EVENT |
private <any> |
childrenListener
*
Callbacks and events *
*
|
private EventHandlerManager |
eventHandlerManager |
private BooleanProperty |
expanded |
private static <any> |
EXPANDED_ITEM_COUNT_CHANGE_EVENT |
private int |
expandedDescendentCount |
private boolean |
expandedDescendentCountDirty |
private <any> |
graphic |
private static <any> |
GRAPHIC_CHANGED_EVENT |
private boolean |
ignoreSortUpdate
*
Instance Variables *
*
|
private <any> |
itemListener |
(package private) java.util.Comparator<TreeItem<T>> |
lastComparator |
(package private) TreeSortMode |
lastSortMode |
private ReadOnlyBooleanWrapper |
leaf |
private <any> |
parent |
private int |
parentLinkCount |
(package private) int |
previousExpandedDescendentCount |
private static <any> |
TREE_NOTIFICATION_EVENT |
private <any> |
value
*
Properties *
*
|
private static <any> |
VALUE_CHANGED_EVENT |
Constructor and 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.
|
Modifier and Type | Method and Description |
---|---|
<E extends Event> |
addEventHandler(<any> eventType,
<any> eventHandler)
Registers an event handler to this TreeItem.
|
static <T> <any> |
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> <any> |
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) |
private void |
checkSortState() |
static <T> <any> |
childrenModificationEvent()
An EventType used when the TreeItem receives a direct modification to its
children list.
|
private void |
doSort(<any> children,
java.util.Comparator<TreeItem<T>> comparator) |
static <T> <any> |
expandedItemCountChangeEvent()
The general EventType used when the TreeItem receives a modification that
results in the number of children being visible changes.
|
BooleanProperty |
expandedProperty()
The expanded state of this TreeItem.
|
private void |
fireEvent(TreeItem.TreeModificationEvent<T> evt) |
<any> |
getChildren()
The children of this TreeItem.
|
(package private) int |
getExpandedDescendentCount(boolean reset) |
Node |
getGraphic()
Returns the node that is generally shown to the left of the value property.
|
TreeItem<T> |
getParent()
The parent of this TreeItem.
|
private TreeItem<T> |
getRoot() |
T |
getValue()
Returns the application-specific data represented by this TreeItem.
|
static <T> <any> |
graphicChangedEvent()
An EventType used when the TreeItem receives a modification to its
graphic property.
|
<any> |
graphicProperty()
The node that is generally shown to the left of the value property.
|
boolean |
isExpanded()
Returns the expanded state of this TreeItem.
|
boolean |
isLeaf()
A TreeItem is a leaf if it has no children.
|
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.
|
<any> |
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> |
removeEventHandler(<any> eventType,
<any> eventHandler)
Unregisters a previously registered event handler from this TreeItem.
|
private void |
runSort(<any> children,
java.util.Comparator<TreeItem<T>> comparator,
TreeSortMode sortMode) |
void |
setExpanded(boolean value)
Sets the expanded state of this TreeItem.
|
void |
setGraphic(Node value)
Sets the node that is generally shown to the left of the value property.
|
private void |
setLeaf(boolean value) |
private void |
setParent(TreeItem<T> value) |
void |
setValue(T value)
Sets the application-specific data represented by this TreeItem.
|
(package private) void |
sort()
*
private methods *
*
|
private void |
sort(<any> children,
java.util.Comparator<TreeItem<T>> comparator,
TreeSortMode sortMode) |
java.lang.String |
toString()
Returns a string representation of this
TreeItem object. |
static <T> <any> |
treeNotificationEvent()
The base EventType used to indicate that an event has occurred within a
TreeItem.
|
private void |
updateChildren(<any> c) |
private static <T> void |
updateChildrenParent(java.util.List<? extends TreeItem<T>> treeItems,
TreeItem<T> newParent) |
private void |
updateExpandedDescendentCount(boolean reset) |
static <T> <any> |
valueChangedEvent()
An EventType used when the TreeItem receives a modification to its
value property.
|
<any> |
valueProperty()
A property representing the application-specific data contained within
this TreeItem.
|
public final <any> valueProperty
public final <any> graphicProperty
getGraphic()
,
setGraphic(Node)
public final BooleanProperty expandedProperty
isExpanded()
,
setExpanded(boolean)
public final ReadOnlyBooleanProperty leafProperty
isLeaf()
public final <any> parentProperty
getParent()
private static final <any> TREE_NOTIFICATION_EVENT
private static final <any> EXPANDED_ITEM_COUNT_CHANGE_EVENT
private static final <any> BRANCH_EXPANDED_EVENT
private static final <any> BRANCH_COLLAPSED_EVENT
private static final <any> CHILDREN_MODIFICATION_EVENT
private static final <any> VALUE_CHANGED_EVENT
private static final <any> GRAPHIC_CHANGED_EVENT
private final <any> itemListener
private boolean ignoreSortUpdate
private boolean expandedDescendentCountDirty
<any> children
private final EventHandlerManager eventHandlerManager
private int expandedDescendentCount
int previousExpandedDescendentCount
TreeSortMode lastSortMode
private int parentLinkCount
private <any> childrenListener
private <any> value
private <any> graphic
private BooleanProperty expanded
private ReadOnlyBooleanWrapper leaf
private <any> parent
public TreeItem()
public TreeItem(T value)
value
- The object to be stored as the value of this TreeItem.public TreeItem(T value, Node graphic)
value
- The object to be stored as the value of this TreeItem.graphic
- The Node to show in the TreeView next to this TreeItem.public static <T> <any> treeNotificationEvent()
T
- The type of the value contained within the TreeItem.public static <T> <any> expandedItemCountChangeEvent()
branchExpandedEvent()
,
branchCollapsedEvent()
and childrenModificationEvent()
for the three sub-types).T
- The type of the value contained within the TreeItem.public static <T> <any> branchExpandedEvent()
T
- The type of the value contained within the TreeItem.public static <T> <any> branchCollapsedEvent()
T
- The type of the value contained within the TreeItem.public static <T> <any> childrenModificationEvent()
T
- The type of the value contained within the TreeItem.public static <T> <any> valueChangedEvent()
T
- The type of the value contained within the TreeItem.public static <T> <any> graphicChangedEvent()
T
- The type of the value contained within the TreeItem.public final void setValue(T value)
value
- the application-specific datapublic final T getValue()
public final <any> valueProperty()
public final void setGraphic(Node value)
value
- The graphic node that will be displayed to the user.public final Node getGraphic()
public final <any> graphicProperty()
getGraphic()
,
setGraphic(Node)
public final void setExpanded(boolean value)
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.public final boolean isExpanded()
public final BooleanProperty expandedProperty()
isExpanded()
,
setExpanded(boolean)
private void setLeaf(boolean value)
public boolean isLeaf()
public final ReadOnlyBooleanProperty leafProperty()
isLeaf()
public final TreeItem<T> getParent()
public final <any> parentProperty()
getParent()
public <any> getChildren()
public TreeItem<T> previousSibling()
public TreeItem<T> previousSibling(TreeItem<T> beforeNode)
beforeNode
- The TreeItem for which the previous sibling is being
sought.public TreeItem<T> nextSibling()
public TreeItem<T> nextSibling(TreeItem<T> afterNode)
afterNode
- The TreeItem for which the next sibling is being
sought.public java.lang.String toString()
TreeItem
object.toString
in class java.lang.Object
TreeItem
object.private void fireEvent(TreeItem.TreeModificationEvent<T> evt)
public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail)
public <E extends Event> void addEventHandler(<any> eventType, <any> eventHandler)
Cell
class documentation for more details).E
- The eventeventType
- the type of the events to receive by the handlereventHandler
- the handler to registerjava.lang.NullPointerException
- if the event type or handler is nullpublic <E extends Event> void removeEventHandler(<any> eventType, <any> eventHandler)
E
- The eventeventType
- the event type from which to unregistereventHandler
- the handler to unregisterjava.lang.NullPointerException
- if the event type or handler is nullvoid sort()
private void sort(<any> children, java.util.Comparator<TreeItem<T>> comparator, TreeSortMode sortMode)
private void checkSortState()
private void runSort(<any> children, java.util.Comparator<TreeItem<T>> comparator, TreeSortMode sortMode)
int getExpandedDescendentCount(boolean reset)
private void updateExpandedDescendentCount(boolean reset)
private void updateChildren(<any> c)