/*
* $Id: TreeModelSupport.java 3100 2008-10-14 22:33:10Z rah003 $
*
* Copyright 2004 Sun Microsystems, Inc., 4150 Network Circle,
* Santa Clara, California 95054, U.S.A. All rights reserved.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
package org.jdesktop.swingx.tree;
import javax.swing.event.EventListenerList;
import javax.swing.event.TreeModelEvent;
import javax.swing.event.TreeModelListener;
import javax.swing.tree.TreeModel;
import javax.swing.tree.TreePath;
import org.jdesktop.swingx.util.Contract;
/**
* Support for change notification, usable by {@code TreeModel}s.
*
* The changed/inserted/removed is expressed in terms of a {@code TreePath},
* it's up to the client model to build it as appropriate.
*
* This is inspired by {@code AbstractTreeModel} from Christian Kaufhold,
* www.chka.de.
*
* TODO - implement and test precondition failure of added/removed notification
*
* @author JW
*/
public final class TreeModelSupport {
protected EventListenerList listeners;
private TreeModel treeModel;
/**
* Creates the support class for the given {@code TreeModel}.
*
* @param model the model to support
* @throws NullPointerException if {@code model} is {@code null}
*/
public TreeModelSupport(TreeModel model) {
if (model == null)
throw new NullPointerException("model must not be null");
listeners = new EventListenerList();
this.treeModel = model;
}
//---------------------- structural changes on subtree
/**
* Notifies registered TreeModelListeners that the tree's root has
* been replaced. Can cope with a null root.
*/
public void fireNewRoot() {
Object root = treeModel.getRoot();
/*
* Undocumented. I think it is the only reasonable/possible solution to
* use use null as path if there is no root. TreeModels without root
* aren't important anyway, since JTree doesn't support them (yet).
*/
TreePath path = (root != null) ? new TreePath(root) : null;
fireTreeStructureChanged(path);
}
/**
* Call when a node has changed its leaf state.<p>
*
* PENDING: rename? Do we need it?
* @param path the path to the node with changed leaf state.
*/
public void firePathLeafStateChanged(TreePath path) {
fireTreeStructureChanged(path);
}
/**
* Notifies registered TreeModelListeners that the structure
* below the node identified by the given path has been
* completely changed.
* <p>
* NOTE: the subtree path maybe null if the root is null.
* If not null, it must contain at least one element (the root).
*
* @param subTreePath the path to the root of the subtree
* whose structure was changed.
* @throws NullPointerException if the path is not null but empty
* or contains null elements.
*/
public void fireTreeStructureChanged(TreePath subTreePath) {
if (subTreePath != null) {
Contract.asNotNull(subTreePath.getPath(),
"path must not contain null elements");
}
Object[] pairs = listeners.getListenerList();
TreeModelEvent e = null;
for (int i = pairs.length - 2; i >= 0; i -= 2) {
if (pairs[i] == TreeModelListener.class) {
if (e == null)
e = createStructureChangedEvent(subTreePath);
((TreeModelListener) pairs[i + 1]).treeStructureChanged(e);
}
}
}
//----------------------- node modifications, no mutations
/**
* Notifies registered TreeModelListeners that the
* the node identified by the given path has been modified.
*
* @param path the path to the node that has been modified,
* must not be null and must not contain null path elements.
*
*/
public void firePathChanged(TreePath path) {
Object node = path.getLastPathComponent();
TreePath parentPath = path.getParentPath();
if (parentPath == null)
fireChildrenChanged(path, null, null);
else {
Object parent = parentPath.getLastPathComponent();
fireChildChanged(parentPath, treeModel
.getIndexOfChild(parent, node), node);
}
}
/**
* Notifies registered TreeModelListeners that the given child of
* the node identified by the given parent path has been modified.
* The parent path must not be null, nor empty nor contain null
* elements.
*
* @param parentPath the path to the parent of the modified children.
* @param index the position of the child
* @param child child node that has been modified, must not be null
*/
public void fireChildChanged(TreePath parentPath, int index, Object child) {
fireChildrenChanged(parentPath, new int[] { index },
new Object[] { child });
}
/**
* Notifies registered TreeModelListeners that the given children of
* the node identified by the given parent path have been modified.
* The parent path must not be null, nor empty nor contain null
* elements. Note that the index array must contain the position of the
* corresponding child in the the children array. The indices must be in
* ascending order. <p>
*
* The exception to these rules is if the root itself has been
* modified (which has no parent by definition). In this case
* the path must be the path to the root and both indices and children
* arrays must be null.
*
* @param parentPath the path to the parent of the modified children.
* @param indices the positions of the modified children
* @param children the modified children
*/
public void fireChildrenChanged(TreePath parentPath, int[] indices,
Object[] children) {
Contract.asNotNull(parentPath.getPath(),
"path must not be null and must not contain null elements");
Object[] pairs = listeners.getListenerList();
TreeModelEvent e = null;
for (int i = pairs.length - 2; i >= 0; i -= 2) {
if (pairs[i] == TreeModelListener.class) {
if (e == null)
e = createTreeModelEvent(parentPath, indices, children);
((TreeModelListener) pairs[i + 1]).treeNodesChanged(e);
}
}
}
//------------------------ mutations (insert/remove nodes)
/**
* Notifies registered TreeModelListeners that the child has been added to
* the the node identified by the given parent path at the given position.
* The parent path must not be null, nor empty nor contain null elements.
*
* @param parentPath the path to the parent of added child.
* @param index the position of the added children
* @param child the added child
*/
public void fireChildAdded(TreePath parentPath, int index, Object child) {
fireChildrenAdded(parentPath, new int[] { index },
new Object[] { child });
}
/**
* Notifies registered TreeModelListeners that the child has been removed
* from the node identified by the given parent path from the given position.
* The parent path must not be null, nor empty nor contain null elements.
*
* @param parentPath the path to the parent of removed child.
* @param index the position of the removed children before the removal
* @param child the removed child
*/
public void fireChildRemoved(TreePath parentPath, int index, Object child) {
fireChildrenRemoved(parentPath, new int[] { index },
new Object[] { child });
}
/**
* Notifies registered TreeModelListeners that the given children have been
* added to the the node identified by the given parent path at the given
* locations. The parent path and the child array must not be null, nor
* empty nor contain null elements. Note that the index array must contain
* the position of the corresponding child in the the children array. The
* indices must be in ascending order.
* <p>
*
* @param parentPath the path to the parent of the added children.
* @param indices the positions of the added children.
* @param children the added children.
*/
public void fireChildrenAdded(TreePath parentPath, int[] indices,
Object[] children) {
Object[] pairs = listeners.getListenerList();
TreeModelEvent e = null;
for (int i = pairs.length - 2; i >= 0; i -= 2) {
if (pairs[i] == TreeModelListener.class) {
if (e == null)
e = createTreeModelEvent(parentPath, indices, children);
((TreeModelListener) pairs[i + 1]).treeNodesInserted(e);
}
}
}
/**
* Notifies registered TreeModelListeners that the given children have been
* removed to the the node identified by the given parent path from the
* given locations. The parent path and the child array must not be null,
* nor empty nor contain null elements. Note that the index array must
* contain the position of the corresponding child in the the children
* array. The indices must be in ascending order.
* <p>
*
* @param parentPath the path to the parent of the removed children.
* @param indices the positions of the removed children before the removal
* @param children the removed children
*/
public void fireChildrenRemoved(TreePath parentPath, int[] indices,
Object[] children) {
Object[] pairs = listeners.getListenerList();
TreeModelEvent e = null;
for (int i = pairs.length - 2; i >= 0; i -= 2) {
if (pairs[i] == TreeModelListener.class) {
if (e == null)
e = createTreeModelEvent(parentPath, indices, children);
((TreeModelListener) pairs[i + 1]).treeNodesRemoved(e);
}
}
}
//------------------- factory methods of TreeModelEvents
/**
* Creates and returns a TreeModelEvent for structureChanged
* event notification. The given path may be null to indicate
* setting a null root. In all other cases, the first path element
* must contain the root and the last path element the rootNode of the
* structural change. Specifically, a TreePath with a single element
* (which is the root) denotes a structural change of the complete tree.
*
* @param parentPath the path to the root of the changed structure,
* may be null to indicate setting a null root.
* @return a TreeModelEvent for structureChanged notification.
*
* @see javax.swing.event.TreeModelEvent
* @see javax.swing.event.TreeModelListener
*/
private TreeModelEvent createStructureChangedEvent(TreePath parentPath) {
return createTreeModelEvent(parentPath, null, null);
}
/**
* Creates and returns a TreeModelEvent for changed/inserted/removed
* event notification.
*
* @param parentPath path to parent of modified node
* @param indices the indices of the modified children (before the change)
* @param children the array of modified children
* @return a TreeModelEvent for changed/inserted/removed notification
*
* @see javax.swing.event.TreeModelEvent
* @see javax.swing.event.TreeModelListener
*/
private TreeModelEvent createTreeModelEvent(TreePath parentPath,
int[] indices, Object[] children) {
return new TreeModelEvent(treeModel, parentPath, indices, children);
}
//------------------------ handling listeners
public void addTreeModelListener(TreeModelListener l) {
listeners.add(TreeModelListener.class, l);
}
public TreeModelListener[] getTreeModelListeners() {
return listeners.getListeners(TreeModelListener.class);
}
public void removeTreeModelListener(TreeModelListener l) {
listeners.remove(TreeModelListener.class, l);
}
}