javax.swing.tree Documentation Differences

This file contains all the changes in documentation in the package javax.swing.tree as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

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. A future release of Swing will provide support for long term persistence. @version 1.6 0810 02/2802/9800 @author Scott Violet

A DefaultMutableTreeNode is a general-purpose node in a tree data structure. For examples of using default mutable tree nodes see How to Use Trees in The Java Tutorial.

A tree node may have at most one parent and 0 or more children. DefaultMutableTreeNode provides operations for examining and modifying a node's parent and children and also operations for examining the tree that the node is a part of. A node's tree is the set of all nodes that can be reached by starting at the node and following all the possible links to parents and children. A node with no parent is the root of its tree; a node with no children is a leaf. A tree may consist of many subtrees each node acting as the root for its own subtree.

This class provides enumerations for efficiently traversing a tree or subtree in various orders or for following the path between two nodes. A DefaultMutableTreeNode may also hold a reference to a user object the use of which is left to the user. Asking a DefaultMutableTreeNode for its string representation with toString() returns the string representation of its user object.

This is not a thread safe class.If you intend to use a DefaultMutableTreeNode (or a tree of TreeNodes) in more than one thread you need to do your own synchronizing. A good convention to adopt is synchronizing on the root node of a tree.

While DefaultMutableTreeNode implements the MutableTreeNode interface and will allow you to add in any implementation of MutableTreeNode not all of the methods in DefaultMutableTreeNode will be applicable to all MutableTreeNodes implementations. Especially with some of the enumerations that are provided using some of these methods assumes the DefaultMutableTreeNode contains only DefaultMutableNode instances. All of the TreeNode/MutableTreeNode methods will behave as defined no matter what implementations are added.

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. A future release of Swing will provide support for long term persistence. @see MutableTreeNode @version 1.11 0815 02/2802/9800 @author Rob Davis

A TreeCellEditor. You need to supply an instance of DefaultTreeCellRenderer so that the icons can be obtained. You can optionaly supply a TreeCellEditor that will be layed out according to the icon in the DefaultTreeCellRenderer. If you do not supply a TreeCellEditor a TextField will be used. Editing is started on a triple mouse click or after a click pause click and a delay of 1200 miliseconds.

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. A future release of Swing will provide support for long term persistence. @see javax.swing.JTree @version 1.14 0417 02/2202/9900 @author Scott Violet

Displays an entry in a tree. See How to Use Trees in The Java Tutorial for examples of customizing node display using this class.

Implementation Note: This class overrides validate revalidate repaint and firePropertyChange solely to improve performance. If not overridden these frequently called methods would execute code paths that are unnecessary for the default tree cell renderer. If you write your own renderer take care to weigh the benefits and drawbacks of overriding these methods.

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. A future release of Swing will provide support for long term persistence. @version 1.31 0440 02/2202/9900 @author Rob Davis @author Ray Ryan @author Scott Violet

Configures the renderer based on the passed in components. The value is set from messaging valuethe tree with convertValueToText which ultimately invokes toString() on value. The foreground color is set based on the selection and the icon is set based on on leaf and expanded.

SupportOverridden for deferredperformance automatic layout. Calls invalidate() and then adds this components validateRoot to a list of components that need to be validated. Validation will occur after all currently pending events have been dispatched. In other words after this method is called the first validateRoot (if any) found when walking up the containment hierarchy of this component will be validated. By default JRootPane JScrollPane and JTextField return true from isValidateRoot(). This method will automatically be called on this component when a property value changes such that size location or internal layout of this component has been affectedreasons. ThisSee automatic updating differs from the AWT because programs generally no longer need to invoke validate() to get the contents of the GUI to update. Implementation @seeNote java.awt.Component#invalidatefor @seemore java.awtinformation.Container#validate @see #isValidateRoot @see RepaintManager#addInvalidComponent

Subclassed to onlymap acceptColorUIResources to null. If color is null or a ColorUIResource this has the effect of letting the background color of the JTree show through. On the other hand if itcolor is isn'tnon-null and not a ColorUIResource the background becomes color.

Subclassed to onlymap acceptFontUIResources to null. If font is null or a FontUIResource this has the effect of letting the font of the JTree show through. On the other hand if itfont is non-null isn'tand not a FontUIResource the font becomes font.

Validates this containerOverridden for performance and all of its subcomponentsreasons. AWT uses validate to cause a container to laySee out its subcomponents again after the components it containsImplementation haveNote been addedfor more to or modifiedinformation. @see #validate @see Component#invalidate

A simple tree data model that uses TreeNodes. For further information and examples that use DefaultTreeModel see How to Use Trees in The Java Tutorial.

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. A future release of Swing will provide support for long term persistence. @version 1.37 0441 02/2202/9900 @author Rob Davis @author Ray Ryan @author Scott Violet

ImplementationDefault implementation of TreeSelectionModel. Listeners are notified whenever the paths in the selection change not the rows. In order to be able to track row changes you may wish to become a listener for expansion events on the tree and test for changes from there.

resetRowSelection is called from any of the methods that update the selected paths. If you subclass andany of these methods to filter what is allowed to be selected be sure and message resetRowSelection if you do not message super.

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. A future release of Swing will provide support for long term persistence. @see javax.swing.JTree @version 1.25 1137 02/1702/9800 @author Scott Violet

Creates a new instance of DefaultTreeSelectionModel that is empty andwith having a selection mode of DISCONTIGUOUS_TREE_SELECTION.

AddAdds a PropertyChangeListener to the listener list. The listener is registered for all properties.

A PropertyChangeEvent will get fired inwhen response to an explicit setFont setBackground or SetForeground on the current component. Note that if the current component is inheriting its foreground background orselection fontmode from its container then no event will be fired in response to a change in the inherited propertychanges. @param listener Thethe PropertyChangeListener to be added

Adds path to the current selection. If path is not currently in the selection the TreeSelectionListeners are notified. This has no effect if path is null. @param path the new path to add to the current selection.

Adds paths to the current selection. If any of the paths in paths are not currently in the selection the TreeSelectionListeners are notified. This has no effect if paths is null.

The lead path is set to the last element in paths.

If the selection mode is CONTIGUOUS_TREE_SELECTION and adding the new paths would make the selection discontiguous. Then two things can result: if the TreePaths in paths are contiguous then the selection becomes these TreePaths otherwise the TreePaths aren't contiguous and the selection becomes the first TreePath in paths. @param path the new path to add to the current selection.

Adds x to the list of listeners that are notified each time the selectionset of selected TreePaths changes. @param x the new listener to be added.

Returns true if the paths are contiguous or this object has no RowMapper.

ReturnsUsed trueto test if thea pathsparticular set of TreePaths can be added. This will return true if paths is null (or empty) or this object has without breakingno RowMapper or nothing is currently selected or the continuityselection ofmode is DISCONTIGUOUS_TREE_SELECTION or adding the paths to the modelcurrent selection still results in a contiguous set of TreePaths.

Returns a clone of the recieverthis object with the same selection. selectionListeners andThis PropertyListeners aremethod does not duplicated. @exception CloneNotSupportedException ifduplicate the receiver doesselection not bothlisteners and (a)property implementlisteners. the@exception Cloneable interface andCloneNotSupportedException never thrown (b)by define ainstances of clonethis method.class

Returns the last path that was added. This may differ from the leadSelectionPath property maintained by the JTree.

GetsReturns the lastlargest value obtained from the RowMapper for the current set of selected TreePaths. If nothing is selected rowor there is no RowMapper this will return -1.

GetsReturns the firstsmallest value obtained from the RowMapper for the current set of selected TreePaths. If nothing is selected rowor there is no RowMapper this will return -1.

Returns the RowMapper instance that is able to map a pathTreePath to a row.

Returns the selection mode one of SINGLE_TREE_SELECTION DISCONTIGUOUS_TREE_SELECTION or CONTIGUOUS_TREE_SELECTION.

Returns the first path in the selection. This is useful if there if only one item currently selected.

Returns the paths in the selection. This will return null (or an empty array) if nothing is currently selected.

Returns all of the currently selected rows. This will return null (or an empty array) if there are no selected TreePaths or a RowMapper has not been set. This may return an array of length less that than of the selected TreePaths if some of the rows are not visible (that is the RowMapper returned -1 for the row corresponding to the TreePath).

UsefulMakes sure the currently selected TreePaths are valid for the current selection mode. If the selection mode is CONTIGUOUS_TREE_SELECTION. Ifand a RowMapper exists this will make sure all the rows that are selectedcontiguous. are notIf the contiguousselection isn't thencontiguous the selection is reset to becontain the first set of contiguous paths. Or if

If the selection mode is single selectionSINGLE_TREE_SELECTION and more than one thisTreePath is selected the selection is reset to contain the first path currently selected.

InsuresThis method that all the elements in pathis obsolete and its implementation is arenow a uniquenoop. ThisIt's does not check for a nullstill called by setSelectionPaths and addSelectionPaths selectionbut only for backwards compatability.

Returns true if the path path is in the current selection.

RemoveRemoves a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties. @param listener Thethe PropertyChangeListener to be removed

Removes path from the selection. If path is in the selection The TreeSelectionListeners are notified. This has no effect if path is null. @param path the path to remove from the selection.

Removes paths from the selection. If any of the paths in paths are in the selection the TreeSelectionListeners are notified. This has no effect if paths is null. @param path the path to remove from the selection.

Removes x from the list of listeners that are notified each time the selectionset of selected TreePaths changes. @param x the listener to remove.

Recalculates whatUpdates this object's mapping from TreePath to rows. are selected by askingThis should be invoked when the RowMappermapping from TreePaths to integers has changed (for theexample a node has been rowexpanded).

You do not normally have to call this JTree and its associated Listeners will invoke this for eachyou. If you are implementing your own View class then you will have to invoke this.

This will invoke insureRowContinuity to make sure the currently selected TreePaths are still valid based on the selection pathmode.

Sets the RowMapper instance. This instance is used to determine whatthe row correspondsfor to what patha particular TreePath.

Sets the selection model which must be one of SINGLE_TREE_SELECTION CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION. If mode is not one of the defined value DISCONTIGUOUS_TREE_SELECTION is assumed.

This may change the selection if the current selection is not valid for the new mode. For example if three TreePaths are selected when the mode is changed to SINGLE_TREE_SELECTION only one TreePath will remain selected. It is up to the particular implementation to decide what TreePath remains selected.

Setting the mode to something other than the defined types will result in the mode becoming DISCONTIGUOUS_TREE_SELECTION.

Sets the selection to path. If this represents a change then the TreeSelectionListeners are notified. If path is null this has the same effect as invoking clearSelection. @param path new path to select

Sets the selection to the paths in paths. If this represents a change the TreeSelectionListeners are notified. Potentially paths will be held by thethis recieverobject; in other words don't change any of the objects in the array once passed in.

If paths is null this has the same effect as invoking clearSelection.

The lead path is set to the last path in pPaths.

If the selection mode is CONTIGUOUS_TREE_SELECTION and adding the new paths would make the selection discontiguous the selection is reset to the first TreePath in paths. @param paths new selection.

Handles maintaining the list selection model. The RowMapper is used to map from a TreePath to a row and the value is then placed here.

Exception used to stop and expand/collapse from happening. See How to Write a Tree-Will-Expand Listener in The Java Tutorial for further information and examples. @version 1.4 087 02/2602/9800 @author Scott Violet

NOTE: This will become more open in a future release.

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. A future release of Swing will provide support for long term persistence. @version 1.10 0413 02/2202/9900 @author Scott Violet

Defines the requirements for a tree node object that can change -- by adding or removing child nodes or by changing the contents of a user object stored in the node. @see DefaultMutableTreeNode @see javax.swing.JTree @version 1.5 098 02/2102/9800 @author Rob Davis @author Scott Violet

Defines the requirements for an object that translates paths in the tree into display rows. @version 1.8 0910 02/2102/9800 @author Scott Violet

Adds to CellEditor the extensions necessary to configure an editor in a tree. @see javax.swing.JTree @version 1.7 0910 02/2102/9800 @author Scott Violet

Defines the requirements for an object that displays a tree node. See How to Use Trees in The Java Tutorial for an example of implementing a tree cell renderer that displays custom icons. @version 1.13 0916 02/2102/9800 @author Rob Davis @author Ray Ryan @author Scott Violet

The interface that defines a suitable data model for a JTree. For further information on tree models including an example of a custom implementation see How to Use Trees in The Java Tutorial. @version 1.13 0816 02/2602/9800 @author Rob Davis @author Ray Ryan

Defines the requirements for an object that can be used as a tree node in a JTree.

For further information and examples of using tree nodes see How to Use Tree Nodes in The Java Tutorial. @version 1.14 0917 02/2102/9800 @author Rob Davis @author Scott Violet

Represents a path to a node. A TreePath is an array of Objects that are vended from a TreeModel. The elements of the array are ordered such that the root is always the first element (index 0) of the array. TreePath is Serializable but if any components of the path are not serializable it will not be written out.

For further information and examples of using tree paths see How to Use Trees in The Java Tutorial.

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. A future release of Swing will provide support for long term persistence. @version 1.20 0825 02/2802/9800 @author Scott Violet @author Philip Milne

Primarily provided for subclasses that don'trepresent wish topaths in use thea path ivardifferent manner. If a subclass uses this constructor it should also subclassoverride the getPath() getPathCount() and getPathComponent() methods and possibly the equals method.

Constructs a TreePath whencontaining thereonly a single element. This is onlyusually used to itemconstruct ina TreePath for the paththe root of the TreeModel.

@param singlePath an Object representing the path to a node @see #TreePath(Object[])

Constructs a new TreePath thiswhich is the combination of all the path elements inidentified by parent withending a last path component ofin lastElement.

Tests two TreePaths for equality by checking each element of the paths for equality. Two paths are considered equal if they are of the same length and contain the same elements (.equals). @param o the Object to compare

Returns the last component of this path. For a path returned by the DefaultTreeModel that is the TreeNode object forthis the node specified by the pathwill return an instance of TreeNode. @return the Object at the end of the path @see #TreePath(Object[])

Returns a path containing all the elements of the receiver acceptthis object except the last path component.

Returns an ordered array of Objects containing the components of this TreePath. The first element (index 0) is the root. @return an array of Objects representing the TreePath @see #TreePath(Object[])

Returns true if the specified nodeaTreePath is a descendant of this TreePath. A TreePath childP1 is a descendent of anothera TreePath parentP2 if childP1 contains all of the components that make up parentP2's path. For example if this object has the path [a b] and aTreePath has the path [a b c] then aTreePath is a descendant of this object. However if aTreePath has the path [a] then it is not a descendant of this object. @return true if aTreePath is a descendant of thethis receiver.path

Returns a new path containing all the elements of this receiverobject plus child. child will be the last element of the newly created TreePath. This will throw a NullPointerException if child is null.

This interface represents the current state of the selection for the tree component. It will keep trackFor information and examples of theusing selectedtree selection rowsmodels butsee How to Use Trees in orderThe Java Tutorial.

The state of the tree selection is characterized by a set of TreePaths and optionally a set of integers. The mapping from TreePath to selectinteger is done by rowway of an instance of RowMapper. It is not necessary for a TreeSelectionModel to have a RowMapper to correctly operate but without a youRowMapper getSelectionRows will needreturn null.

A TreeSelectionModel can be configured to allow only one path (SINGLE_TREE_SELECTION) a number of continguous paths (CONTIGUOUS_TREE_SELECTION) or a number of discontiguous paths (DISCONTIGUOUS_TREE_SELECTION). A RowMapper is used to godetermine if TreePaths are contiguous. In the absence of a RowMapper CONTIGUOUS_TREE_SELECTION and DISCONTIGUOUS_TREE_SELECTION behave the same that is they allow any number of directlypaths to be contained in the treeTreeSelectionModel.

resetRowSelection is calledFor a fromselection model of CONTIGUOUS_TREE_SELECTION any time the paths are changed (setSelectionPath addSelectionPath ...) the TreePaths are again checked to make they are contiguous. A check of the methodsTreePaths can also be forced by invoking resetRowSelection. How a set of discontiguous TreePaths is mapped to a contiguous set is left to implementors of this interface to enforce a particular policy.

Implementations should combine duplicate TreePaths that updateare added to the selectedselection. For example the following code

 TreePath[] paths = new TreePath[] { treePath treePath }; treeSelectionModel.setSelectionPaths(paths); 

should result in only one path being selected: treePath and not two copies of treePath.

The lead TreePath is the last path that was added (or set). The lead row is then the row that corresponds to the TreePath as determined from the RowMapper. @version 1.13 1119 02/1702/9800 @author Scott Violet

AddAdds a PropertyChangeListener to the listener list. The listener is registered for all properties.

A PropertyChangeEvent will get fired inwhen response to an explicit setFont setBackground or SetForeground on the current component. Note that if the current component is inheriting its foreground background orselection fontmode from its container then no event will be fired in response to a change in the inherited propertychanges. @param listener Thethe PropertyChangeListener to be added

Adds path to the current selection. If path is not currently in the selection the TreeSelectionListeners are notified. This has no effect if path is null. @param path the new path to add to the current selection.

Adds paths to the current selection. If any of the paths in paths are not currently in the selection the TreeSelectionListeners are notified. This has no effect if paths is null. @param path the new path to add to the current selection.

Adds x to the list of listeners that are notified each time the selectionset of selected TreePaths changes. @param x the new listener to be added.

Returns the last path that was added. This may differ from the leadSelectionPath property maintained by the JTree.

GetsReturns the lastlargest value obtained from the RowMapper for the current set of selected TreePaths. If nothing is selected rowor there is no RowMapper this will return -1.

GetsReturns the firstsmallest value obtained from the RowMapper for the current set of selected TreePaths. If nothing is selected rowor there is no RowMapper this will return -1.

Returns the RowMapper instance that is able to map a pathTreePath to a row.

Returns the current selection mode one of SINGLE_TREE_SELECTION CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.

Returns the first path in the selection. How first is defined is up to implementors and may not necessarily be the TreePath with the smallest integer value as determined from the RowMapper.

Returns the paths in the selection. This will return null (or an empty array) if nothing is currently selected.

Returns all of the currently selected rows. This will return null (or an empty array) if there are no selected TreePaths or a RowMapper has not been set.

Returns true if the path path is in the current selection.

RemoveRemoves a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties. @param listener Thethe PropertyChangeListener to be removed

Removes path from the selection. If path is in the selection The TreeSelectionListeners are notified. This has no effect if path is null. @param path the path to remove from the selection.

Removes paths from the selection. If any of the paths in paths are in the selection the TreeSelectionListeners are notified. This method has no effect if paths is null. @param pathpaths the path to remove from the selection.

Removes x from the list of listeners that are notified each time the selectionset of selected TreePaths changes. @param x the listener to remove.

Updates whatthis rowsobject's aremapping from TreePaths to selectedrows. This canshould be externally called in case the location of the paths changeinvoked when the mapping from TreePaths to integers has changed but(for notexample thea node actualhas pathsbeen expanded).

You do not normally needhave to call this; JTree and its associated listeners will invoke this for you. If you are implementing your own view class then you will have to invoke this.

Sets the RowMapper instance. This instance is used to determine whatthe row correspondsfor to what patha particular TreePath.

Sets the selection model which must be one of SINGLE_TREE_SELECTION CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.

This may change the selection if the current selection is not valid for the new mode. For example if three TreePaths are selected when the mode is changed to SINGLE_TREE_SELECTION only one TreePath will remain selected. It is up to the particular implementation to decide what TreePath remains selected.

Sets the selection to path. If this represents a change then the TreeSelectionListeners are notified. If path is null this has the same effect as invoking clearSelection. @param path new path to select

Sets the selection to the the pathspath. If this represents a change then the TreeSelectionListeners are notified. If paths is null this has the same effect as invoking clearSelection. @param paths new selection.

Selection can only be contiguous. This will only be enforced if a RowMapper instance is provided. That is if no RowMapper is set this behaves the same as DISCONTIGUOUS_TREE_SELECTION.

NOTE: This will become more open in a future release.

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. A future release of Swing will provide support for long term persistence. @version 1.11 0413 02/2202/9900 @author Rob Davis @author Ray Ryan @author Scott Violet