path: root/projects/net.wotonomy.ui.swing/src/main/java/net/wotonomy/ui/swing/TreeAssociation.java

/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2000 Intersect Software Corporation

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, see http://www.gnu.org
*/

package net.wotonomy.ui.swing;

import java.awt.EventQueue;
import java.awt.Rectangle;
import java.awt.event.FocusEvent;
import java.awt.event.FocusListener;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.Vector;

import javax.swing.JTree;
import javax.swing.event.TreeExpansionEvent;
import javax.swing.event.TreeExpansionListener;
import javax.swing.event.TreeSelectionEvent;
import javax.swing.event.TreeWillExpandListener;
import javax.swing.tree.ExpandVetoException;
import javax.swing.tree.TreePath;

import net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.NSMutableArray;
import net.wotonomy.ui.EODisplayGroup;

/**
 * TreeAssociation is a TreeModelAssociation further customized for JTrees. It
 * binds a JTree to a display group's list of displayable objects, each of which
 * may have a list of child objects managed by another display group, and so on.
 * TreeAssociation works exactly like a ListAssociation, with the additional
 * capability to specify a "Children" aspect, that will allow child objects to
 * be retrieved from a parent display group. Note that the children aspect
 * requires the bound display group to have a DataSource that can vend a
 * DataSource appropriate for the bound key That data source is then used to
 * create data sources for child nodes, and so on.
 *
 * <ul>
 *
 * <li>titles: a property convertable to a string for display in the nodes of
 * the tree. The objects in the bound display group will be used to populate the
 * initial root nodes of the tree (more accurately, children of the offscreen
 * root node in the tree).</li>
 *
 * <li>children: a property of a node value that returns zero, one or many
 * objects, each of which will correspond to a child node for the corresponding
 * node in the tree. The data source of the bound display group is replaced a
 * data source that populates the display group with the visible nodes in the
 * tree component as determined by calling fetchObjectsIntoChildrenGroup. If
 * this aspect is not bound, the tree behaves like a list. <br>
 * <br>
 * Binding this aspect with a null display group is the same as binding it with
 * the titles display group. In this configuration the contents of the titles
 * display group will be replaced with the visible nodes in the tree component,
 * as specified above, replacing the existing data source. <br>
 * <br>
 * In that case, the display groups for the nodes in the tree will still use the
 * original data source for resolving their children key, and programmatically
 * setting the contents of the display group will still repopulate the root
 * nodes of the tree.</li>
 *
 * <li>isLeaf: a property of a node value that returns a value convertable to a
 * boolean value (aside from an actual boolean value, zeroes evaluate to true,
 * as does any String containing "yes" or "true" or that is convertable to a
 * number equal to zero; other values evaluate to false). <br>
 * <br>
 * If the isLeaf aspect is not bound, the tree must force nodes to load their
 * children to determine whether they are leaf nodes (in effect loading the
 * grandchildren for any expanded node). If bound, child loading is deferred
 * until the node is actually expanded. <br>
 * <br>
 * For example, binding this value to a null display group and the key "false"
 * will result in a deferred-loading tree that works much like Windows
 * Explorer's network volume browser - all nodes appear with "pluses" until they
 * are expanded. <br>
 * <br>
 * Note that the display group is ignored: the property will be applied directly
 * to the object corresponding to the node.</li>
 *
 * </ul>
 *
 * All other usage is as TreeModelAssociation.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 904 $
 */
public class TreeAssociation extends TreeModelAssociation
		implements FocusListener, TreeExpansionListener, TreeWillExpandListener, Runnable {
	private boolean isExpanding;
	private Vector nodeQueue;
	private Vector structureQueue;
	private boolean isRunning;

	/**
	 * Constructor expecting a JTree.
	 */
	public TreeAssociation(Object anObject) {
		super(anObject);
		init();
	}

	/**
	 * Constructor expecting a JTree or similar component and specifying a label for
	 * the root node.
	 */
	public TreeAssociation(Object anObject, Object aRootLabel) {
		super(anObject);
		init();
		rootLabel = aRootLabel;
		rootNode.setUserObject(aRootLabel);
	}

	// convenience
	private JTree component() {
		return (JTree) object();
	}

	/**
	 * Called by both constructors.
	 */
	protected void init() {
		isExpanding = false;
		isRunning = false;
		nodeQueue = new Vector();
		structureQueue = new Vector();
		component().addFocusListener(this);
		component().addTreeExpansionListener(this);
		component().addTreeWillExpandListener(this);
	}

	/**
	 * Returns whether this class can control the specified object.
	 */
	public static boolean isUsableWithObject(Object anObject) {
		return (anObject instanceof JTree);
	}

	/**
	 * Overridden to not fire events during initial population.
	 */
	public void establishConnection() {
		isExpanding = true;
		super.establishConnection();
		isExpanding = false;
	}

	// interface TreeSelectionListener

	public void valueChanged(TreeSelectionEvent e) {
		if (!isListening)
			return;
// NOTE: This approach causes focus rectangle to perceptibly trail
// the selection rectangle, presumably because we're called after the
// new selection has been processed but before the focus is processed.
// Users don't like it, so we're going with a preference to use
// invokeLater.
		/*
		 * // paint immediately before updating the display group and // before any
		 * potentially lengthy second-order effects happen: // this improves
		 * user-perceived responsiveness of big apps if ( object() instanceof
		 * javax.swing.JComponent ) { javax.swing.JComponent component =
		 * (javax.swing.JComponent)object(); component.paintImmediately(
		 * component.getBounds() ); } selectFromSelectionModel();
		 */

// NOTE: This approach uses invoke later to cause the update of
// the display group (which could be lengthly if that in turn
// causes other things to update) to happen after the tree repaints.
// Users like this because it "feels faster", but developers have
// to remember that if they listen to tree selection events they
// will have to do a similar invoke later if they check the display
// group.

		Runnable select = new Runnable() {
			public void run() {
				selectFromSelectionModel();
			}
		};

		if (selectionPaintedImmediately) {
			if (object() instanceof java.awt.Component) {
				((java.awt.Component) object()).repaint();
			}
			EventQueue.invokeLater(select);
		} else {
			select.run();
		}
	}

	/**
	 * Overridden to check whether the node is visible in the tree on screen.
	 * Offscreen in a scrollpane does not count.
	 */
	public boolean isVisible(Object node) {
		JTree tree = (JTree) object();
		TreePath path = ((DisplayGroupNode) node).treePath();
		if (tree.isVisible(path)) {
			Rectangle rowRect = tree.getPathBounds(path);
			if (rowRect != null) {
				Rectangle visible = tree.getVisibleRect();
				if (visible != null) {
//System.out.println( "isVisible: intersects: " + visible.intersects( rowRect ) );        
					return visible.intersects(rowRect);
				}
			}
		}
//System.out.println( "isVisible: false" );        
		return false;
	}

	/**
	 * Fires a tree nodes changed event to all listeners. Provided as a convenience
	 * if you need to make manual changes to the tree model.
	 */
	public void fireTreeNodesChanged(final Object source, final Object[] path, final int[] childIndices,
			final Object[] children) {
		if (!isExpanding) {
			for (int i = 0; i < children.length; i++) {
				nodeQueue.add(children[i]);
			}
			if (!isRunning) {
				isRunning = true;
				EventQueue.invokeLater(this);
			}
		}
	}

	/**
	 * Fires a tree nodes inserted event to all listeners. Provided as a convenience
	 * if you need to make manual changes to the tree model.
	 */
	public void fireTreeNodesInserted(Object source, Object[] path, int[] childIndices, Object[] children) {
		if (!isExpanding) {
			super.fireTreeNodesInserted(source, path, childIndices, children);
			EventQueue.invokeLater(this);
		}
	}

	/**
	 * Fires a tree nodes removed event to all listeners. Provided as a convenience
	 * if you need to make manual changes to the tree model.
	 */
	public void fireTreeNodesRemoved(Object source, Object[] path, int[] childIndices, Object[] children) {
		if (!isExpanding) {
			super.fireTreeNodesRemoved(source, path, childIndices, children);
			EventQueue.invokeLater(this);
		}
	}

	/**
	 * Fires a tree structure changed event to all listeners. Provided as a
	 * convenience if you need to make manual changes to the tree model.
	 */
	public void fireTreeStructureChanged(Object source, Object[] path, int[] childIndices, Object[] children) {
		if (!isExpanding) {
			structureQueue.add(path[path.length - 1]);
			if (!isRunning) {
				isRunning = true;
				EventQueue.invokeLater(this);
			}
		}
	}

	/**
	 * Overridden to return all visible rows in the tree.
	 */
	public NSArray objectsFetchedIntoChildrenGroup() {
		JTree tree = (JTree) object();
		NSMutableArray objectList = new NSMutableArray();

		int count = tree.getRowCount();
		for (int i = 0; i < count; i++) {
			objectList.add(((DisplayGroupNode) tree.getPathForRow(i).getLastPathComponent()).object());
		}

//new net.wotonomy.ui.swing.util.StackTraceInspector( Integer.toString( objectList.size() )  );
		return objectList;
	}

	// interface FocusListener

	/**
	 * Notifies of beginning of edit.
	 */
	public void focusGained(FocusEvent evt) {
		Object o;
		EODisplayGroup displayGroup;
		Enumeration e = aspects().objectEnumerator();
		while (e.hasMoreElements()) {
			displayGroup = displayGroupForAspect(e.nextElement().toString());
			if (displayGroup != null) {
				displayGroup.associationDidBeginEditing(this);
			}
		}
	}

	/**
	 * Updates object on focus lost and notifies of end of edit.
	 */
	public void focusLost(FocusEvent evt) {
		if (!component().isEditing()) {
			Object o;
			EODisplayGroup displayGroup;
			Enumeration e = aspects().objectEnumerator();
			while (e.hasMoreElements()) {
				displayGroup = displayGroupForAspect(e.nextElement().toString());
				if (displayGroup != null) {
					displayGroup.associationDidEndEditing(this);
				}
			}
		}
	}

	// interface TreeWillExpandListener

	public void treeWillExpand(TreeExpansionEvent event) throws ExpandVetoException {
		isExpanding = true;
	}

	public void treeWillCollapse(TreeExpansionEvent event) throws ExpandVetoException {
		// do nothing
	}

	// interface TreeExpansionListener

	/**
	 * Updates the children display group, if any.
	 */
	public void treeExpanded(TreeExpansionEvent event) { // System.out.println( "treeExpanded: " +
															// event.getPath().getLastPathComponent() );
		isExpanding = false;
		if (childrenDisplayGroup != null) {
			removeAsListener(); // prevent data source refetch: see fetchObjects()
			childrenDisplayGroup.fetch();
			addAsListener();
		}
	}

	/**
	 * Updates the children display group, if any.
	 */
	public void treeCollapsed(TreeExpansionEvent event) {
		if (childrenDisplayGroup != null) {
			removeAsListener(); // prevent data source refetch: see fetchObjects()
			childrenDisplayGroup.fetch();
			addAsListener();
		}
	}

	// interface Runnable

	/**
	 * Fires any queued node changed and structure changed events. Typically invoked
	 * on a delayed event loop.
	 */
	public void run() {
		DisplayGroupNode node;
		int index;
		Iterator i;

		i = nodeQueue.iterator();
		while (i.hasNext()) {
			node = (DisplayGroupNode) i.next();
			index = ((DisplayGroupNode) node.parentGroup).getIndex(node);
			if ((index != -1) && (node.treePath().getParentPath() != null)) {
				super.fireTreeNodesChanged(node, node.treePath().getParentPath().getPath(), new int[] { index },
						new Object[] { node });
			}
		}
		nodeQueue.clear();

		i = structureQueue.iterator();
		while (i.hasNext()) {
			node = (DisplayGroupNode) i.next();
			super.fireTreeStructureChanged(node, node.treePath().getPath(), null, null);
		}
		structureQueue.clear();

		isRunning = false;
		/*
		 * EventQueue.invokeLater( new Runnable() { public void run() {
		 * ((JTree)object()).treeDidChange();
		 * ((JTree)object()).getParent().invalidate();
		 * ((JTree)object()).getParent().validate();
		 * ((JTree)object()).getParent().update( ((JTree)object()).getGraphics() );
		 * 
		 * // ((JTree)object()).getParent().doLayout(); //
		 * ((JTree)object()).getParent().repaint(); // ((JTree)object()).repaint(); //
		 * ((JTree)object()).updateUI(); } } );
		 */
	}
}

/*
 * $Log$ Revision 1.2 2006/02/18 23:19:05 cgruber Update imports and maven
 * dependencies.
 *
 * Revision 1.1 2006/02/16 13:22:22 cgruber Check in all sources in
 * eclipse-friendly maven-enabled packages.
 *
 * Revision 1.55 2004/02/05 02:18:50 mpowers Super was calling back into this
 * class before init() was called.
 *
 * Revision 1.54 2003/08/06 23:07:52 chochos general code cleanup (mostly,
 * removing unused imports)
 *
 * Revision 1.53 2003/06/03 14:49:48 mpowers Now correctly calculating isVisible
 * based on the component visible rect. Now deferring node changed events to a
 * later event queue to allow repaints to happen after all changes have taken
 * effect.
 *
 * Revision 1.52 2002/05/03 21:41:18 mpowers No longer clearing the selection
 * model when updating from display group: we now only modify if a change needs
 * to be made. No longer listening for selection change during firing of delete
 * events: delete events cause JTree's to update their selection model. Fix for
 * paintsSelectionImmediately: TreeAssociation.processRecentChanges() must
 * happen after the screen is painted, or the selection is not displayed.
 *
 * Revision 1.51 2002/04/19 21:18:45 mpowers Removed tree event coalescing,
 * which was causing way too many problems. The fireChangeEvent algorithm is way
 * faster than before, so we should still be better off than before. At least
 * now, we don't have to track whether the view component has encountered a
 * particular node.
 *
 * Revision 1.49 2002/04/12 21:05:58 mpowers Now distinguishing changes in
 * titles group even better.
 *
 * Revision 1.48 2002/04/12 20:36:31 mpowers Now distinguishing between changes
 * made on titles group by tree expansion versus external changes which should
 * cause us to repopulate root nodes.
 *
 * Revision 1.47 2002/04/10 21:20:04 mpowers Better handling for tree nodes when
 * working with editing contexts. Better handling for invalidation. No longer
 * broadcasting events when nodes have not been "registered" in the tree.
 *
 * Revision 1.46 2002/03/27 20:44:53 mpowers Added isVisible test for node.
 *
 * Revision 1.45 2002/03/08 23:19:57 mpowers Refactoring of
 * DelegatingTreeDataSource to facilitate binding of titles and children aspects
 * to the same display group.
 *
 * Revision 1.44 2002/03/07 23:04:36 mpowers Refining TreeColumnAssociation.
 *
 * Revision 1.43 2002/03/06 13:04:15 mpowers Implemented cascading qualifiers in
 * tree nodes.
 *
 * Revision 1.42 2002/03/05 23:18:28 mpowers Added documentation. Added
 * isSelectionPaintedImmediate and isSelectionTracking attributes to
 * TableAssociation. Added getTableAssociation to TableColumnAssociation.
 *
 * Revision 1.41 2002/03/01 23:42:08 mpowers Implemented TreeColumnAssociation,
 * and updated documentation.
 *
 * Revision 1.40 2002/03/01 20:41:39 mpowers Now a focus listener and an
 * expansion listener.
 *
 * Revision 1.39 2002/02/27 23:19:17 mpowers Refactoring of TreeAssociation to
 * create TreeModelAssociation parent.
 *
 *
 */