Package docking.widgets.tree

Class GTree

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
docking.widgets.tree.GTree
All Implemented Interfaces:
BusyListener, ImageObserver, MenuContainer, Serializable, Accessible
Direct Known Subclasses:
DataTree
public class GTree extends JPanel implements BusyListener
Class for creating a JTree that supports filtering, threading, and a progress bar.

Note: when calling methods on this class to select nodes, if those nodes are threaded, or extend from GTreeSlowLoadingNode, then you must first expand the paths you wish to select. You can do this by calling expandAndSelectPaths(List). The various select methods of this class will not expand nodes, but they will trigger children to be loaded. If those nodes are not threaded, then the tree will add and expand the children by default. When using threaded nodes, the delay in loading prevents the tree from correctly expanding the paths.

See Also:

  • Constructor Details

    • GTree

      public GTree(GTreeNode root)
      Creates a GTree with the given root node. The created GTree will use a threaded model for performing tasks, which allows the GUI to be responsive for reaaaaaaaaly big trees.
      Parameters:
      root - The root node of the tree.

  • Method Details

    • setEnabled

      public void setEnabled(boolean enabled)
      Overrides:
      setEnabled in class JComponent

    • setEventsEnabled

      public void setEventsEnabled(boolean b)
      Turns tree event notifications on/off
      Parameters:
      b - true to enable events, false to disable events

    • setDragNDropHandler

      public void setDragNDropHandler(GTreeDragNDropHandler dragNDropHandler)

    • setTransferHandler

      public void setTransferHandler(TransferHandler handler)
      Overrides:
      setTransferHandler in class JComponent

    • getDragNDropHandler

      public GTreeDragNDropHandler getDragNDropHandler()

    • setAccessibleNamePrefix

      public void setAccessibleNamePrefix(String namePrefix)
      Sets an accessible name on the GTree. This prefix will be used to assign meaningful accessible names to the tree, filter text field and the filter options button such that screen readers will properly describe them.

      This prefix should be the base name that describes the type of items in the tree. This method will then append the necessary information to name the text field and the button.

      Parameters:
      namePrefix - the accessible name prefix to assign to the filter component. For example if the tree contains fruits, then "Fruits" would be an appropriate prefix name.

    • setCellRenderer

      public void setCellRenderer(GTreeRenderer renderer)

    • getCellRenderer

      public GTreeRenderer getCellRenderer()

    • dispose

      public void dispose()

    • isDisposed

      public boolean isDisposed()

    • cancelWork

      public void cancelWork()
      Signals that any multithreaded work should be cancelled.

    • filterChanged

      public void filterChanged()

    • updateModelFilter

      protected void updateModelFilter()

    • createMouseListenerDelegate

      protected JTreeMouseListenerDelegate createMouseListenerDelegate()

    • getTreeState

      public GTreeState getTreeState()
      Returns a state object that allows this tree to later restore its expanded and selected state.

      Note: See the usage note at the header of this class concerning how tree state is used relative to the equals() method.

      Returns:
      the saved state

    • getTreeState

      public GTreeState getTreeState(GTreeNode node)

    • restoreTreeState

      public void restoreTreeState(GTreeState state)
      Restores the expanded and selected state of this tree to that contained in the given state object.

      Note: See the usage note at the header of this class concerning how tree state is used relative to the equals() method.

      Parameters:
      state - the state to restore
      See Also:

    • setFilterRestoreState

      protected void setFilterRestoreState(GTreeState state)
      Sets the filter restore state. This method is a way to override the tree's filtering behavior, which is usually set by a call to saveFilterRestoreState(). Most clients will never need to call this method.
      Parameters:
      state - the state to set

    • getPreferenceKey

      public String getPreferenceKey()
      Returns the key that this tree uses to store preferences.
      Returns:
      the key that this tree uses to store preferences.

    • expandedStateRestored

      public void expandedStateRestored(TaskMonitor taskMonitor)
      A method that subclasses can use to be notified when tree state has been restored. This method is called after a major structural tree change has happened and the paths that should be opened have been opened. Thus any other nodes are closed and can be disposed, if desired.
      Parameters:
      taskMonitor - the TaskMonitor

    • getExpandedPaths

      public List<TreePath> getExpandedPaths()

    • getExpandedPaths

      public List<TreePath> getExpandedPaths(GTreeNode node)

    • expandTree

      public void expandTree(GTreeNode node)

    • expandAll

      public void expandAll()

    • collapseAll

      public void collapseAll(GTreeNode node)

    • expandPath

      public void expandPath(GTreeNode node)

    • expandPath

      public void expandPath(TreePath path)

    • expandPaths

      public void expandPaths(TreePath[] paths)

    • expandPaths

      public void expandPaths(List<TreePath> paths)

    • clearSelectionPaths

      public void clearSelectionPaths()

    • expandAndSelectPaths

      public void expandAndSelectPaths(List<TreePath> paths)
      Expands and then selects the given paths. You must use this method if your tree is using GTreeSlowLoadingNodes. Otherwise, if the given paths are not expanded, then the select will not work. More info at the class javadoc.
      Parameters:
      paths - the paths

    • setSelectedNode

      public void setSelectedNode(GTreeNode node)

    • setSelectedNodes

      public void setSelectedNodes(GTreeNode... nodes)

    • setSelectedNodes

      public void setSelectedNodes(Collection<GTreeNode> nodes)

    • setSelectionPaths

      public void setSelectionPaths(TreePath[] paths)

    • setSelectionPaths

      public void setSelectionPaths(List<TreePath> pathsList)

    • setSelectionPath

      public void setSelectionPath(TreePath path)

    • setSelectedNodeByNamePath

      public void setSelectedNodeByNamePath(String[] namePath)
      A convenience method to select a node by a path, starting with the tree root name, down each level until the desired node name.
      Parameters:
      namePath - The path to select

    • setSeletedNodeByName

      public void setSeletedNodeByName(GTreeNode parentNode, String childName)
      A convenience method that allows clients that have created a new child node to select that node in the tree, without having to lookup the actual GTreeNode implementation.
      Parameters:
      parentNode - The parent containing a child by the given name
      childName - The name of the child to select

    • setSelectedNodeByPathName

      public void setSelectedNodeByPathName(TreePath treePath)
      Selects the node that matches the each name in the given tree path. It is worth noting that the items in the tree path themselves are not used to identify nodes, but the toString() of those items will be used.
      Parameters:
      treePath - The path containing the names of the path of the node to select

    • setSelectionPaths

      public void setSelectionPaths(TreePath[] paths, GTreeSelectionEvent.EventOrigin origin)

    • setSelectionPaths

      public void setSelectionPaths(List<TreePath> paths, boolean expandPaths, GTreeSelectionEvent.EventOrigin origin)
      Selects the given paths, expanding them first if requested.
      Parameters:
      paths - the paths to select
      expandPaths - true to expand the paths first; this is only needed for multi-threaded nodes. Non-threaded nodes should use false, as it increase performance.
      origin - the event type; use GTreeSelectionEvent.EventOrigin.API_GENERATED if unsure

    • isCollapsed

      public boolean isCollapsed(TreePath path)

    • setHorizontalScrollPolicy

      public void setHorizontalScrollPolicy(int policy)

    • getScrollPane

      protected JScrollPane getScrollPane()

    • setScrollableUnitIncrement

      public void setScrollableUnitIncrement(int increment)
      Sets the size of the scroll when mouse scrolling or pressing the scroll up/down buttons. Most clients will not need this method, as the default behavior of the tree is correct, which is to scroll based upon the size of the nodes (which is usually uniform and a single row in size). However, some clients that have variable row height, with potentially large rows, may wish to change the scrolling behavior so that it is not too fast.
      Parameters:
      increment - the new (uniform) scroll increment.

    • getModel

      public GTreeModel getModel()
      Returns the model for this tree
      Returns:
      the model for this tree

    • getJTree

      protected final JTree getJTree()

    • getViewPosition

      public Point getViewPosition()
      Returns the current viewport position of the scrollable tree.
      Returns:
      the current viewport position of the scrollable tree.

    • setViewPosition

      public void setViewPosition(Point p)

    • getViewRect

      public Rectangle getViewRect()

    • getNodeForLocation

      public GTreeNode getNodeForLocation(int x, int y)

    • getModelNode

      public GTreeNode getModelNode(GTreeNode node)
      Gets the model node for the given node. This is useful if the node that is in the path has been replaced by a new node that is equal, but a different instance. One way this happens is if the tree is filtered and therefor the displayed nodes are clones of the model nodes. This can also happen if the tree nodes are rebuilt for some reason.
      Parameters:
      node - the node
      Returns:
      the corresponding model node in the tree. If the tree is filtered the viewed node will be a clone of the corresponding model node.

    • getModelNodeForPath

      public GTreeNode getModelNodeForPath(TreePath path)
      Gets the model node for the given path. This is useful if the node that is in the path has been replaced by a new node that is equal, but a different instance. One way this happens is if the tree is filtered and therefor the displayed nodes are clones of the model nodes. This can also happen if the tree nodes are rebuilt for some reason.
      Parameters:
      path - the path of the node
      Returns:
      the corresponding model node in the tree. If the tree is filtered the viewed node will be a clone of the corresponding model node.

    • getViewNode

      public GTreeNode getViewNode(GTreeNode node)
      Gets the view node for the given node. This is useful to translate to a tree path that is valid for the currently displayed tree. (Remember that if the tree is filtered, then the displayed nodes are clones of the model nodes.)
      Parameters:
      node - the node
      Returns:
      the current node in the displayed (possibly filtered) tree

    • getViewNodeForPath

      public GTreeNode getViewNodeForPath(TreePath path)
      Gets the view node for the given path. This is useful to translate to a tree path that is valid for the currently displayed tree. (Remember that if the tree is filtered, then the displayed nodes are clones of the model nodes.)
      Parameters:
      path - the path of the node
      Returns:
      the current node in the displayed (possibly filtered) tree

    • setActiveDropTargetNode

      public void setActiveDropTargetNode(GTreeNode node)

    • setFilterText

      public void setFilterText(String text)

    • getFilterProvider

      public GTreeFilterProvider getFilterProvider()

    • setFilterProvider

      public void setFilterProvider(GTreeFilterProvider filterProvider)

    • setFilterFieldEnabled

      public void setFilterFieldEnabled(boolean enabled)
      Disabled the filter text field, but allows the tree to still filter. This is useful if you want to allow programmatic filtering, but to not allow the user to filter.
      Parameters:
      enabled - True makes the filter field editable; false makes it uneditable
      See Also:

    • setFilteringEnabled

      public void setFilteringEnabled(boolean enabled)
      Disables all filtering performed by this tree. Also, the filter field of the tree will be disabled.

      Use this method to temporarily disable filtering.

      Parameters:
      enabled - True to allow normal filtering; false to disable all filtering
      See Also:

    • setFilterVisible

      public void setFilterVisible(boolean visible)
      Hides the filter field. Filtering will still take place, as defined by the GTreeFilterProvider.
      Parameters:
      visible - true to show the filter; false to hide it.
      See Also:

    • isFilteringEnabled

      public boolean isFilteringEnabled()

    • setDataTransformer

      public void setDataTransformer(FilterTransformer<GTreeNode> transformer)
      Sets a transformer object used to perform filtering. This object is responsible for turning the tree's nodes into a list of strings that can be searched when filtering.
      Parameters:
      transformer - the transformer to set

    • getFilterField

      public Component getFilterField()
      Returns the filter text field in this tree.
      Returns:
      the filter text field in this tree.

    • isMyJTree

      public boolean isMyJTree(JTree jTree)
      Returns true if the given JTree is the actual JTree used by this GTree.
      Parameters:
      jTree - the tree to test
      Returns:
      true if the given JTree is the actual JTree used by this GTree.

    • setRootNode

      public void setRootNode(GTreeNode rootNode)
      Sets the root node for this tree.

      NOTE: if this method is not called from the Swing thread, then the root node will be set later on the Swing thread. That is, this method will return before the work has been done.

      Parameters:
      rootNode - The node to set as the new root.

    • getModelRoot

      public GTreeNode getModelRoot()
      This method returns the root node that was provided to the tree by the client, whether from the constructor or from setRootNode(GTreeNode). This node represents the data model and always contains all the nodes regardless of any filter being applied. If a filter is applied to the tree, then this is not the actual root node being displayed by the JTree.
      Returns:
      the root node as provided by the client.

    • getViewRoot

      public GTreeNode getViewRoot()
      This method returns the root node currently being displayed by the JTree. If there are no filters applied, then this will be the same as the model root (See getModelRoot()). If a filter is applied, then this will be a clone of the model root that contains clones of all nodes matching the filter.
      Returns:
      the root node currently being display by the JTree

    • printEvent

      public static void printEvent(PrintWriter out, String name, TreeModelEvent e)
      This method is useful for debugging tree problems. Don't know where else to put it.
      Parameters:
      out - the output writer
      name - use this to indicate what tree event occurred ("node inserted" "node removed", etc.)
      e - the TreeModelEvent;

    • getSelectionModel

      public TreeSelectionModel getSelectionModel()

    • getGTSelectionModel

      public GTreeSelectionModel getGTSelectionModel()

    • setSelectionModel

      public void setSelectionModel(GTreeSelectionModel selectionModel)

    • getRowCount

      public int getRowCount()

    • getRowForPath

      public int getRowForPath(TreePath treePath)

    • getPathForRow

      public TreePath getPathForRow(int row)

    • getSelectionPath

      public TreePath getSelectionPath()

    • getSelectionPaths

      public TreePath[] getSelectionPaths()

    • getSelectedNodes

      public List<GTreeNode> getSelectedNodes()

    • isExpanded

      public boolean isExpanded(TreePath treePath)

    • isPathSelected

      public boolean isPathSelected(TreePath treePath)

    • isRootVisible

      public boolean isRootVisible()

    • setRootVisible

      public void setRootVisible(boolean b)

    • setShowsRootHandles

      public void setShowsRootHandles(boolean b)

    • scrollPathToVisible

      public void scrollPathToVisible(TreePath treePath)

    • getCellEditor

      public CellEditor getCellEditor()

    • getPathForLocation

      public TreePath getPathForLocation(int x, int y)

    • getPathBounds

      public Rectangle getPathBounds(TreePath path)

    • setRowHeight

      public void setRowHeight(int rowHeight)

    • addSelectionPath

      public void addSelectionPath(TreePath path)

    • addTreeExpansionListener

      public void addTreeExpansionListener(TreeExpansionListener listener)

    • removeTreeExpansionListener

      public void removeTreeExpansionListener(TreeExpansionListener listener)

    • addGTreeSelectionListener

      public void addGTreeSelectionListener(GTreeSelectionListener listener)

    • removeGTreeSelectionListener

      public void removeGTreeSelectionListener(GTreeSelectionListener listener)

    • addGTModelListener

      public void addGTModelListener(TreeModelListener listener)

    • removeGTModelListener

      public void removeGTModelListener(TreeModelListener listener)

    • setEditable

      public void setEditable(boolean editable)

    • whenNodeIsReady

      public void whenNodeIsReady(GTreeNode parent, Predicate<GTreeNode> matches, Consumer<GTreeNode> consumer)
      A specialized method that will get the child node from the given parent node when it becomes available to the model. This method will ensure that the matching child passes any current filter in order for the child to appear in the tree. This effect is temporary and will be undone when next the filter changes.

      This method is intended to be used by clients using an asynchronous node model, where new nodes will get created by application-level events. Such clients may wish to perform work when newly created nodes become available. This method simplifies the concurrent nature of the GTree, asynchronous nodes and the processing of asynchronous application-level events by providing a callback mechanism for clients. This method is non-blocking.

      Note: this method assumes that the given parent node is in the view and not filtered out of the view. This method makes no attempt to ensure the given parent node passes any existing filter.

      Note: this method will not wait forever for the given node to appear. It will eventually give up if the node never arrives.

      Parameters:
      parent - the model's parent node. If the view's parent node is passed, it will be translated to the model node.
      matches - the predicate that returns true when the given node is the desired node
      consumer - the consumer callback to which the child node will be given when available

    • whenNodeIsReady

      public void whenNodeIsReady(GTreeNode parent, String childName, Consumer<GTreeNode> consumer)
      A specialized method that will get the child node from the given parent node when it becomes available to the model. This method will ensure that the named child passes any current filter in order for the child to appear in the tree. This effect is temporary and will be undone when next the filter changes.

      This method is intended to be used by clients using an asynchronous node model, where new nodes will get created by application-level events. Such clients may wish to perform work when newly created nodes become available. This method simplifies the concurrent nature of the GTree, asynchronous nodes and the processing of asynchronous application-level events by providing a callback mechanism for clients. This method is non-blocking.

      Note: this method assumes that the given parent node is in the view and not filtered out of the view. This method makes no attempt to ensure the given parent node passes any existing filter.

      Note: this method will not wait forever for the given node to appear. It will eventually give up if the node never arrives.

      Note: if your parent node allows duplicate nodes then this method may not match the correct node. If that is the case, then use whenNodeIsReady(GTreeNode, Predicate, Consumer).

      Parameters:
      parent - the model's parent node. If the view's parent node is passed, it will be translated to the model node.
      childName - the name of the desired child
      consumer - the consumer callback to which the child node will be given when available

    • startEditing

      public void startEditing(GTreeNode parent, String childName)
      Requests that the node with the given name, in the given parent, be edited. This operation is asynchronous. This request will be buffered as needed to wait for the given node to be added to the parent, up to a timeout period.

      Note: if there are multiple nodes by the given name under the given parent, then no editing will take place. In that case, you can instead use startEditing(GTreeNode), if you have the node. If you have duplicates and do not yet have the node, then you will need to create your own mechanism for waiting for the desired node and then starting the edit.

      Parameters:
      parent - the parent node
      childName - the name of the child to edit

    • startEditing

      public void startEditing(GTreeNode node)
      Requests that the node be edited. This operation is asynchronous.
      Parameters:
      node - the node to edit

    • addMouseListener

      public void addMouseListener(MouseListener listener)
      Overrides:
      addMouseListener in class Component

    • removeMouseListener

      public void removeMouseListener(MouseListener listener)
      Overrides:
      removeMouseListener in class Component

    • getMouseListeners

      public MouseListener[] getMouseListeners()
      Overrides:
      getMouseListeners in class Component

    • setCellEditor

      public void setCellEditor(TreeCellEditor editor)

    • isPathEditable

      public boolean isPathEditable(TreePath path)

    • setPaintHandlesForLeafNodes

      public void setPaintHandlesForLeafNodes(boolean enable)
      Passing a value of false signals to disable the JTree's default behavior of showing handles for leaf nodes until they are opened.
      Parameters:
      enable - False to disable the default JTree behavior

    • isRootAllowedToCollapse

      public boolean isRootAllowedToCollapse()

    • setRootNodeAllowedToCollapse

      public void setRootNodeAllowedToCollapse(boolean allowed)

    • isBusy

      public boolean isBusy()

    • setBusy

      public void setBusy(boolean busy)
      Specified by:
      setBusy in interface BusyListener

    • refilterNow

      public void refilterNow()
      Causes the tree to refilter immediately (before this method returns)

    • refilterLater

      public void refilterLater()
      Causes the tree to refilter some time later

    • refilterLater

      public void refilterLater(GTreeNode newNode)
      Re-filters the tree if the newNode should be included in the current filter results. If the new node doesn't match the filter, there is no need to refilter the tree.
      Parameters:
      newNode - the node that may cause the tree to refilter.

    • getFilter

      public GTreeFilter getFilter()

    • isFiltered

      public boolean isFiltered()

    • hasFilterText

      public boolean hasFilterText()

    • getFilterText

      public String getFilterText()

    • clearFilter

      public void clearFilter()

    • runTask

      public void runTask(GTreeTask task)
      Used to run tree tasks. This method is not meant for general clients of this tree, but rather for tasks to tell the tree to perform subtasks.
      Parameters:
      task - the task to run

    • runTask

      public void runTask(MonitoredRunnable runnableTask)
      Used to run simple GTree tasks that can be expressed as a MonitoredRunnable (or a lambda taking a TaskMonitor).
      Parameters:
      runnableTask - TaskMonitor to watch and update with progress.

    • runBulkTask

      public void runBulkTask(GTreeBulkTask task)

    • isEditing

      public boolean isEditing()

    • stopEditing

      public void stopEditing()

    • cancelEditing

      public void cancelEditing()

    • setNodeEditable

      public void setNodeEditable(GTreeNode child)

    • toString

      public String toString()
      Overrides:
      toString in class Component

    • getToolTipText

      public String getToolTipText(MouseEvent event)
      Overrides:
      getToolTipText in class JComponent

    • clearSizeCache

      public void clearSizeCache()

    • isAddToPopup

      protected boolean isAddToPopup(DockingAction action)
      A method that subclasses can override to decide if the given action should appear in the popup menu. Most subclasses will not need to override this method. An example for overriding this method is one of the subclasses that have their own version of one of the built-in actions, such as Expand All. Some clients have a custom expand action. In that case, the client wants their action in the menu and not the built-in version.
      Parameters:
      action - the action
      Returns:
      true to have the action appear in the popup; the default is true

    • setDoubleClickExpansionEnabled

      public void setDoubleClickExpansionEnabled(boolean b)
      Enable or disable using double-click to open and close tree nodes. The default is true.
      Parameters:
      b - true to enable

    • createSharedActions

      public static void createSharedActions(Tool tool, ToolActions toolActions, String owner)