Java Doc for JTree.java in  » 6.0-JDK-Core » swing » javax » swing » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A specific node in a tree can be identified either by a TreePath (an object that encapsulates a node and all of its ancestors), or by its display row, where each row in the display area displays one node. An expanded node is a non-leaf node (as identified by TreeModel.isLeaf(node) returning false) that will displays its children when all its ancestors are expanded. A collapsed node is one which hides them. A hidden node is one which is under a collapsed ancestor. All of a viewable nodes parents are expanded, but may or may not be displayed. A displayed node is both viewable and in the display area, where it can be seen.

The following JTree methods use "visible" to mean "displayed":

• isRootVisible()
• setRootVisible()
• scrollPathToVisible()
• scrollRowToVisible()
• getVisibleRowCount()
• setVisibleRowCount()

The next group of JTree methods use "visible" to mean "viewable" (under an expanded parent):

• isVisible()
• makeVisible()

If you are interested in knowing when the selection changes implement the TreeSelectionListener interface and add the instance using the method addTreeSelectionListener. valueChanged will be invoked when the selection changes, that is if the user clicks twice on the same node valueChanged will only be invoked once.

If you are interested in detecting either double-click events or when a user clicks on a node, regardless of whether or not it was selected, we recommend you do the following:

 final JTree tree = ...;
 MouseListener ml = new MouseAdapter() {
 public void mousePressed(MouseEvent e) {
 int selRow = tree.getRowForLocation(e.getX(), e.getY());
 TreePath selPath = tree.getPathForLocation(e.getX(), e.getY());
 if(selRow != -1) {
 if(e.getClickCount() == 1) {
 mySingleClick(selRow, selPath);
 }
 else if(e.getClickCount() == 2) {
 myDoubleClick(selRow, selPath);
 }
 }
 }
 };
 tree.addMouseListener(ml);
 

To use JTree to display compound nodes (for example, nodes containing both a graphic icon and text), subclass TreeCellRenderer and use JTree.setCellRenderer to tell the tree to use it. To edit such nodes, subclass TreeCellEditor and use JTree.setCellEditor .

Like all JComponent classes, you can use InputMap and ActionMap to associate an Action object with a KeyStroke and execute the action under specified conditions.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder .
version:
   1.203, 05/05/07
author:
   Rob Davis
author:
   Ray Ryan
author:
   Scott Violet

A handle is a small icon that displays adjacent to the node which allows the user to click once to expand or collapse the node.

• an array of Objects,
• a Hashtable, or
• a Vector

NOTE: For JTree to properly display tooltips of its renderers, JTree must be a registered component with the ToolTipManager.

This is a bound property.

This is a bound property.

This is a bound property.

This is a bound property.

This is a bound property.

This is a bound property.

This is a bound property.

This is a bound property.

This is a bound property.

This value is only a suggestion to the UI. Not all UIs will take advantage of it. Default value is false.

A handle is a small icon that displays adjacent to the node which allows the user to click once to expand or collapse the node. A common interface shows a plus sign (+) for a node which can be expanded and a minus sign (-) for a node which can be collapsed. Handles are always shown for nodes below the topmost level.

If the rootVisible setting specifies that the root node is to be displayed, then that is the only node at the topmost level. If the root node is not displayed, then all of its children are at the topmost level of the tree. Handles are always displayed for nodes other than the topmost.

If the root node isn't visible, it is generally a good to make this value true. Otherwise, the tree looks exactly like a list, and users may not know that the "list entries" are actually tree nodes.
See Also:   JTree.rootVisible

The parameters are not order dependent. That is, addSelectionInterval(x, y) is equivalent to addSelectionInterval(y, x) .
Parameters:
  index0 - the first index in the range to add to the selection
Parameters:
  index1 - the last index in the range to add to the selection

Note that JTree does not allow duplicate nodes to exist as children under the same parent -- each sibling must be a unique object.
Parameters:
  path - the TreePath to add

Note that JTree does not allow duplicate nodes to exist as children under the same parent -- each sibling must be a unique object.
Parameters:
  paths - an array of TreePath objects that specifiesthe nodes to add

If row is < 0 or >= getRowCount this will have no effect.
Parameters:
  row - an integer specifying a display row, where 0 is thefirst row in the display

• an array of Objects,
• a Hashtable, or
• a Vector

For more information on what expanded state means, see the JTree description above.

If row is < 0 or >= getRowCount this will have no effect.
Parameters:
  row - an integer specifying a display row, where 0 is thefirst row in the display

This method is not meant for querying the drop location from a TransferHandler , as the drop location is only set after the TransferHandler 's canImport has returned and has allowed for the location to be shown.

When this property changes, a property change event with name "dropLocation" is fired by the component. the drop location
See Also:   JTree.setDropMode
See Also:   TransferHandler.canImport(TransferHandler.TransferSupport)
since:
   1.6

The parameters are not order dependent. That is, getPathBetweenRows(x, y) is equivalent to getPathBetweenRows(y, x) .

An empty array is returned if the row count is 0 , or the specified indices do not bound the viewable set of rows.
Parameters:
  index0 - the first index in the range
Parameters:
  index1 - the last index in the range the paths (inclusive) between the specified row indices

Note:
This method returns a valid rectangle, even if the specified node is not currently displayed.
Parameters:
  path - the TreePath identifying the node the Rectangle the node is drawn in,or null

NOTE: For JTree to properly display tooltips of its renderers, JTree must be a registered component with the ToolTipManager. This can be done by invoking ToolTipManager.sharedInstance().registerComponent(tree). This is not done automatically!
Parameters:
  event - the MouseEvent that initiated the ToolTip display a string containing the tooltip or nullif event is null

The parameters are not order dependent. That is, removeSelectionInterval(x, y) is equivalent to removeSelectionInterval(y, x) .
Parameters:
  index0 - the first row to remove from the selection
Parameters:
  index1 - the last row to remove from the selection

This is a bound property.
Parameters:
  newPath - the new anchor path
since:
   1.3

This is a bound property.
Parameters:
  cellEditor - the TreeCellEditor to use

This is a bound property.
Parameters:
  x - the TreeCellRenderer that is to render each cell

The job of honoring this property, and recognizing a user drag gesture, lies with the look and feel implementation, and in particular, the tree's TreeUI . When automatic drag handling is enabled, most look and feels (including those that subclass BasicLookAndFeel ) begin a drag and drop operation whenever the user presses the mouse button over an item and then moves the mouse a few pixels. Setting this property to true can therefore have a subtle effect on how selections behave.

If a look and feel is used that ignores this property, you can still begin a drag and drop operation by calling exportAsDrag on the tree's TransferHandler .
Parameters:
  b - whether or not to enable automatic drag handling
exception:
  HeadlessException - ifb is true andGraphicsEnvironment.isHeadless()returns true
See Also:   java.awt.GraphicsEnvironment.isHeadless
See Also:   JTree.getDragEnabled
See Also:   JTree.setTransferHandler
See Also:   TransferHandler
since:
   1.4

Let's say that on the first call to this method the component decides to save some state (because it is about to use the selection to show a drop index). It can return a state object to the caller encapsulating any saved selection state. On a second call, let's say the drop location is being changed to something else. The component doesn't need to restore anything yet, so it simply passes back the same state object to have the DnD system continue storing it. Finally, let's say this method is messaged with null. This means DnD is finished with this component for now, meaning it should restore state. At this point, it can use the state parameter to restore said state, and of course return null since there's no longer anything to store.
Parameters:
  location - the drop location (as calculated bydropLocationForPoint) or nullif there's no longer a valid drop location
Parameters:
  state - the state object saved earlier for this component,or null
Parameters:
  forDrop - whether or not the method is being called because anactual drop occurred any saved state for this component, or null if none

JTree supports the following drop modes:

• DropMode.USE_SELECTION
• DropMode.ON
• DropMode.INSERT
• DropMode.ON_OR_INSERT

The drop mode is only meaningful if this component has a TransferHandler that accepts drops.
Parameters:
  dropMode - the drop mode to use
throws:
  IllegalArgumentException - if the drop mode is unsupportedor null
See Also:   JTree.getDropMode
See Also:   JTree.getDropLocation
See Also:   JTree.setTransferHandler
See Also:   TransferHandler
since:
   1.6

This is a bound property.
Parameters:
  flag - a boolean value, true if the tree is editable

This will fail if a TreeWillExpandListener vetos it.

This is a bound property.
Parameters:
  newValue - the new value for expandsSelectedPaths
since:
   1.3

Fires a property change for the INVOKES_STOP_CELL_EDITING_PROPERTY.
Parameters:
  newValue - true means that stopCellEditing is invoked when editing is interrupted, and data is saved; false means thatcancelCellEditing is invoked, and changes are lost

This is a bound property.
Parameters:
  newValue - true to suggest a large model to the UI
See Also:   JTree.largeModel

This is a bound property.
Parameters:
  newPath - the new lead path
since:
   1.3

This is a bound property.
Parameters:
  newModel - the TreeModel that is to provide the data

This is a bound property.
Parameters:
  rootVisible - true if the root node of the tree is to be displayed
See Also:   JTree.rootVisible

This is a bound property.
Parameters:
  rowHeight - the height of each cell, in pixels

This is a bound property.
Parameters:
  newValue - false to disable scrolling on expansion;true to enable it
See Also:   JTree.getScrollsOnExpand

The parameters are not order dependent. That is, setSelectionInterval(x, y) is equivalent to setSelectionInterval(y, x) .
Parameters:
  index0 - the first index in the range to select
Parameters:
  index1 - the last index in the range to select

This is a bound property.
Parameters:
  selectionModel - the TreeSelectionModel to use,or null to disable selections
See Also:   TreeSelectionModel

This is a bound property.
Parameters:
  newValue - true if root handles should be displayed;otherwise, false
See Also:   JTree.showsRootHandles
See Also:   JTree.getShowsRootHandles

This is a bound property.
since:
   1.3

This is a bound property.
Parameters:
  ui - the TreeUI L&F object
See Also:   UIDefaults.getUI

This is a bound property.
Parameters:
  newCount - the number of rows to display

Note:
To make edit-saves automatic whenever the user changes their position in the tree, use JTree.setInvokesStopCellEditing .