Package docking.widgets.tree

Class GTreeNode

java.lang.Object
docking.widgets.tree.GTreeNode
All Implemented Interfaces:
Cloneable, Comparable<GTreeNode>
Direct Known Subclasses:
DomainFileNode, GTreeLazyNode, InProgressGTreeNode, InProgressGTreeRootNode, NoProjectNode
public abstract class GTreeNode extends Object implements Comparable<GTreeNode>
Base implementation for GTree nodes. Direct subclasses of this class are expected to have all their children in hand when initially constructed (either in their constructor or externally using addNode(GTreeNode) or setChildren(List). For large trees, subclasses should instead extend GTreeLazyNode or GTreeSlowLoadingNode

All methods in this class that mutate the children node must perform that operation in the swing thread.

To create a simple GTreeNode where nodes will be added immediately using the addNode() methods, simply extend this class and implement the following methods:

  • getName()
  • getToolTip()
  • isLeaf()
  • getIcon()
Usage Notes:
  • The equals() method: The GTree has the ability to remember expanded and selected states. This will only work if the nodes in the saved state can be matched with the nodes in the GTree. Java will do this by using the equals() method. There is a potential problem with this usage. If nodes within the GTree get rebuilt ( i.e., new nodes are created), then, by default, the expanded and selected state feature will be unable to find the correct nodes, since the default equals() method on GTreeNode performs a comparison based upon instances. To fix this problem, the equals(Object) method has been implemented such that nodes are considered equal if they have the same name (see getName()). The hashCode() method will return the hash of the name. The name attribute was chosen because it should be the most unique and descriptive piece of information available in a generic GTreeNode.


    There are two situations where the equals(Object) and hashCode() using the name are insufficient. One is if your tree implementation allows nodes with the same name with the same parent. The other possible situation is if your nodes can change their name, which may confuse the tree. If either of these situations apply, just override the equals(Object) and hashCode() methods to make them more robust.


  • Constructor Details

    • GTreeNode

      public GTreeNode()

  • Method Details

    • generateChildren

      protected List<GTreeNode> generateChildren()
      Subclasses implement this method to initially load the children.
      Returns:
      a list of the initial children for this node.

    • getDisplayText

      public String getDisplayText()
      Returns the display text for the node. By default, this is the same as the name of the node. The name of the node usually serves two purposes: 1) to uniquely identify the node (the identity) and 2) the display text (what you see in the tree). Sometimes, it is useful to display more information in the tree without affecting the nodes identity. In this case, you can override this method to return the "display" name, while getName() will still return the name used to identify the node.
      Returns:
      the display text for the node.

    • getName

      public abstract String getName()
      Returns the name of the node. If getDisplayText() is not overridden, then this is also the text that will be displayed in the tree for that node. In general, the name of a node should not change. If the text displayed in the tree changes over time, override getDisplayText().
      Returns:
      the name of the node

    • getIcon

      public abstract Icon getIcon(boolean expanded)
      Returns the Icon to be displayed for this node in the tree
      Parameters:
      expanded - true if the node is expanded
      Returns:
      the icon to be displayed for this node in the tree

    • getToolTip

      public abstract String getToolTip()
      Returns the string to be displayed as a tooltip when the user hovers the mouse on this node in the tree
      Returns:
      the tooltip to be displayed

    • isLeaf

      public abstract boolean isLeaf()
      Returns true if this node never has children
      Returns:
      true if this node is a leaf

    • compareTo

      public int compareTo(GTreeNode node)
      Specified by:
      compareTo in interface Comparable<GTreeNode>

    • addNode

      public void addNode(GTreeNode node)
      Adds the given node as a child to this node. Note: this method may be inefficient so if you have many nodes to add, you should use either addNodes(List) or setChildren(List)
      Parameters:
      node - the node to add as a child

    • addNodes

      public void addNodes(List<GTreeNode> nodes)
      Adds the given nodes as children to this node
      Parameters:
      nodes - the nodes to add

    • addNode

      public void addNode(int index, GTreeNode node)
      Adds the given node at the given index as a child to this node
      Parameters:
      index - the index to place the node
      node - the node to add as a child of this node

    • getChildren

      public List<GTreeNode> getChildren()
      Returns all of the visible children of this node. If there are filtered nodes, then they will not be returned.
      Returns:
      all of the visible children of this node. If there are filtered nodes, then they will not be returned.

    • getChildCount

      public int getChildCount()
      Returns the number of visible children of this node. Does not include nodes that are current filtered out
      Returns:
      the number of visible children of this node

    • getChild

      public GTreeNode getChild(String name)
      Returns the child node of this node with the given name.
      Parameters:
      name - the name of the child to be returned
      Returns:
      the child with the given name

    • getChild

      public GTreeNode getChild(String name, Predicate<GTreeNode> filter)
      Returns the child node of this node with the given name which satisfies predicate filter.
      Parameters:
      name - the name of the child to be returned
      filter - predicate filter
      Returns:
      the child with the given name

    • getChild

      public GTreeNode getChild(int index)
      Returns the child node at the given index. Returns null if the index is out of bounds.
      Parameters:
      index - the index of the child to be returned
      Returns:
      the child at the given index

    • getNodeCount

      public int getNodeCount()
      Returns the total number of nodes in the subtree rooted at this node. Leaf nodes return 1.
      Returns:
      the number of nodes from this node downward

    • getLeafCount

      public int getLeafCount()
      Returns the total number of leaf nodes in the subtree from this node. Note that if any nodes are "lazy" (see GTreeLazyNode) and not currently loaded, then it will be considered as a leaf and return 1.
      Returns:
      the total number of leaf nodes in the subtree from this node

    • getIndexInParent

      public int getIndexInParent()
      Returns the index of this node within its parent node
      Returns:
      the index of this node within its parent node

    • getIndexOfChild

      public int getIndexOfChild(GTreeNode node)
      Returns the index of the given node within this node. -1 is returned if the node is not a child of this node.
      Parameters:
      node - whose index we want
      Returns:
      the index of the given node within this node

    • getTreePath

      public TreePath getTreePath()
      Returns the TreePath for this node
      Returns:
      the TreePath for this node

    • removeAll

      public void removeAll()
      Removes all children from this node. The children nodes will be disposed.

    • removeNode

      public void removeNode(GTreeNode node)
      Remove the given node from this node
      Parameters:
      node - the to be removed

    • setChildren

      public void setChildren(List<GTreeNode> childList)
      Sets the children on this node. Any existing current children will be dispose.
      Parameters:
      childList - this list of nodes to be set as children of this node

    • isAncestor

      public boolean isAncestor(GTreeNode node)
      Returns true if the given node is a child of this node or one of its children.
      Parameters:
      node - the potential descendant node to check
      Returns:
      true if the given node is a child of this node or one of its children

    • valueChanged

      public void valueChanged(Object newValue)
      Notification method called when a cell editor completes editing to notify this node that its value has changed. If you override this method you must also override isEditable().
      Parameters:
      newValue - the new value provided by the cell editor
      See Also:

    • isEditable

      public boolean isEditable()
      Returns true if this node is allowed to be edited in the tree. You must override this method to allow a node to be edited. You must also override valueChanged(Object) to handle the result of the edit.
      Returns:
      true if this node is allowed to be edited in the tree
      See Also:

    • getRoot

      public GTreeNode getRoot()
      Returns the rootNode for this tree or null if there is no parent path to a root node.
      Returns:
      the rootNode for a tree of nodes in a GTree

    • filter

      public GTreeNode filter(GTreeFilter filter, TaskMonitor monitor) throws CancelledException, CloneNotSupportedException
      Generates a filtered copy of this node and its children.

      A node will be included if it or any of its descendants are accepted by the filter. NOTE: the filter will only be applied to a nodes children if they are loaded. So to perform a filter on all the nodes in the tree, the loadAll(TaskMonitor) should be called before the filter call.

      Parameters:
      filter - the filter being applied
      monitor - a TaskMonitor for tracking the progress and cancelling
      Returns:
      A copy of this node and its children that matches the filter or null if this node and none of its children match the filter.
      Throws:
      CancelledException - if the operation is cancelled via the TaskMonitor
      CloneNotSupportedException - if any nodes in the tree explicitly prevents cloning

    • loadAll

      public int loadAll(TaskMonitor monitor) throws CancelledException
      Causes any lazy or slow loading nodes in the tree to load their children so that the tree is fully loaded. Nodes that are already loaded (including normal nodes which are always loaded) do nothing except recursively call loadAll(TaskMonitor) on their children.
      Parameters:
      monitor - the TaskMonitor to monitor progress and provide cancel checking
      Returns:
      the total number of nodes in the subtree of this node
      Throws:
      CancelledException - if the operation is cancelled using the monitor

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • stream

      public Stream<GTreeNode> stream(boolean depthFirst)
      Returns a stream of the GTree nodes in the subtree of this node
      Parameters:
      depthFirst - if true, the nodes will be streamed in depth-first order, otherwise breadth-first order
      Returns:
      a stream of the GTree nodes in the subtree of this node

    • iterator

      public Iterator<GTreeNode> iterator(boolean depthFirst)
      Returns an iterator of the GTree nodes in the subtree of this node
      Parameters:
      depthFirst - if true, the nodes will be returned in depth-first order, otherwise breadth-first order
      Returns:
      an iterator of the GTree nodes in the subtree of this node

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • fireNodeStructureChanged

      public void fireNodeStructureChanged()
      Notifies the tree that the node has different children.

    • fireNodeChanged

      public void fireNodeChanged()
      Notifies the tree that a node has changed, excluding its children. If it has gained or lost children, then use fireNodeStructureChanged() instead.

    • expand

      public void expand()
      Convenience method for expanding (opening) this node in the tree. If this node is not currently attached to a visible tree, then this call does nothing

    • isAutoExpandPermitted

      public boolean isAutoExpandPermitted()
      Determine if this node may be auto-expanded. Some special node cases may need to prevent or limit auto-expansion due to tree depth or other special conditions.
      Returns:
      true if this node allows auto-expansion, else false.

    • collapse

      public void collapse()
      Convenience method for collapsing (closing) this node in the tree. If this node is not currently attached to a visible tree, then this call does nothing

    • isExpanded

      public boolean isExpanded()
      Convenience method determining if this node is expanded in a tree. If the node is not currently attached to a visible tree, then this call returns false
      Returns:
      true if the node is expanded in a currently visible tree.

    • getParent

      public final GTreeNode getParent()
      Returns the parent of this node. Note: this method is deliberately not synchronized (See comments above)
      Returns:
      the parent of this node.

    • isRoot

      public final boolean isRoot()
      Returns true if this is a root node of a GTree
      Returns:
      true if this is a root node of a GTree

    • children

      protected final List<GTreeNode> children()

    • doSetChildrenAndFireEvent

      protected void doSetChildrenAndFireEvent(List<GTreeNode> childList)
      Sets the children of this node to the given list of child nodes and fires the appropriate tree event to kick the tree to update the display. Note: This method must be called from the swing thread because it will notify the underlying JTree.
      Parameters:
      childList - the list of child nodes to assign as children to this node
      See Also:

    • doSetChildren

      protected void doSetChildren(List<GTreeNode> childList)
      Sets the children of this node to the given list of child nodes, but does not notify the tree. This method does not have to be called from the swing thread. It is intended to be used by background threads that want to populate all or part of the tree, but wait until the bulk operations are completed before notifying the tree.
      Parameters:
      childList - the list of child nodes to assign as children to this node

    • doAddNode

      protected void doAddNode(GTreeNode node)
      Adds a node to this node's children. Must be called from the swing thread.
      Parameters:
      node - the node to add as a child to this node

    • doAddNode

      protected void doAddNode(int index, GTreeNode node)
      Adds a node to this node's children at the given index and notifies the tree. Must be called from the swing thread.
      Parameters:
      index - the index at which to add the new node
      node - the node to add as a child to this node

    • doRemoveNode

      protected void doRemoveNode(GTreeNode node)
      Removes the node from this node's children and notifies the tree. Must be called from the swing thread.
      Parameters:
      node - the node to remove

    • doAddNodes

      protected void doAddNodes(List<GTreeNode> nodes)
      Adds the given nodes to this node's children. Must be called from the swing thread.
      Parameters:
      nodes - the nodes to add to the children this node

    • clone

      public GTreeNode clone() throws CloneNotSupportedException
      Creates a clone of this node. The clone should contain a shallow copy of all the node's attributes except that the parent and children are null.
      Overrides:
      clone in class Object
      Returns:
      the clone of this object.
      Throws:
      CloneNotSupportedException - if some implementation prevents itself from being cloned.

    • dispose

      public void dispose()

    • isInProgress

      public final boolean isInProgress()
      Returns true if the node is in the process of loading its children. See GTreeSlowLoadingNode
      Returns:
      true if the node is in the process of loading its children.

    • isLoaded

      public boolean isLoaded()
      True if the children for this node have been loaded yet. Some GTree nodes are lazy in that they don't load their children until needed. Nodes that have the IN_PROGRESS node as it child is considered loaded if in the swing thread, otherwise they are considered not loaded.
      Returns:
      true if the children for this node have been loaded.

    • getTree

      public GTree getTree()
      Returns the GTree that this node is attached to
      Returns:
      the GTree that this node is attached to

    • doFireNodeAdded

      protected void doFireNodeAdded(GTreeNode newNode)

    • doFireNodeRemoved

      protected void doFireNodeRemoved(GTreeNode removedNode, int index)

    • doFireNodeStructureChanged

      protected void doFireNodeStructureChanged()

    • doFireNodeChanged

      protected void doFireNodeChanged()