/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2002 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 javax.swing.JTree;
import javax.swing.table.TableColumn;

import net.wotonomy.foundation.NSArray;
import net.wotonomy.ui.EODisplayGroup;
import net.wotonomy.ui.swing.components.TreeTableCellRenderer;

/**
 * TreeColumnAssociation is a TableColumnAssocation that works like a
 * TreeAssociation, allowing any table to display hierarchical data in a tabular
 * format. This class is mainly a convenience for connecting a TreeAssociation
 * to a JTree to a TreeTableCellRenderer to a TableColumn.<br>
 * <br>
 * 
 * Like TableColumnAssociation, you must call setTable() to specify the JTable
 * to be used. (The corresponding table association will direct all column
 * header sorting to the root node of the tree association.)
 *
 * You may also optionally call setTree() to specify a customized JTree to be
 * used. If not specified, a slightly customized JTree will be used (see
 * createTree() and configureColumn()).
 * 
 * TreeColumnAssociation supports the following bindings, just as
 * TableColumnAssociation does:
 * <ul>
 * <li>value: a property convertable to a string for display in the cells of the
 * table column. This binding is equivalent to the titles binding of
 * TreeAssociation.</li>
 *
 * <li>editable: a property convertable to a boolean that determines the
 * editability of the corresponding cells in the column.</li>
 * </ul>
 *
 * TreeColumnAssociation additionally supports the following bindings, just as
 * TreeAssociation does, except that the value binding is used instead of the
 * titles binding.
 * <ul>
 * <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. If this aspect is not bound, the tree behaves like a
 * list.</li>
 *
 * <li>isLeaf: a property of a node value that returns a value convertable to a
 * boolean value. If the isLeaf aspect is not bound, the tree will force nodes
 * to load their children to determine whether they are leaf nodes (in effect
 * loading the grandchildren for any expanded node).</li>
 * </ul>
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 904 $
 */
public class TreeColumnAssociation extends TableColumnAssociation {
	static final NSArray aspects = new NSArray(
			new Object[] { ValueAspect, EditableAspect, ChildrenAspect, IsLeafAspect });
	static final NSArray aspectSignatures = new NSArray(new Object[] { AttributeToOneAspectSignature });
	static final NSArray objectKeysTaken = new NSArray(new Object[] { "table" });

	EODisplayGroup childrenDisplayGroup, leafDisplayGroup;
	String childrenKey, leafKey;

	TreeModelAssociation treeAssociation;
	JTree tree;

	/**
	 * Constructor specifying the object to be controlled by this association.
	 * Throws an exception if the object is not a TableColumn.
	 */
	public TreeColumnAssociation(Object anObject) {
		super(anObject);
	}

	/**
	 * Returns a List of aspect signatures whose contents correspond with the
	 * aspects list. Each element is a string whose characters represent a
	 * capability of the corresponding aspect.
	 * <ul>
	 * <li>"A" attribute: the aspect can be bound to an attribute.</li>
	 * <li>"1" to-one: the aspect can be bound to a property that returns a single
	 * object.</li>
	 * <li>"M" to-one: the aspect can be bound to a property that returns multiple
	 * objects.</li>
	 * </ul>
	 * An empty signature "" means that the aspect can bind without needing a key.
	 * This implementation returns "A1M" for each element in the aspects array.
	 */
	public static NSArray aspectSignatures() {
		return aspectSignatures;
	}

	/**
	 * Returns a List that describes the aspects supported by this class. Each
	 * element in the list is the string name of the aspect. This implementation
	 * returns an empty list.
	 */
	public static NSArray aspects() {
		return aspects;
	}

	/**
	 * Binds the specified aspect of this association to the specified key on the
	 * specified display group.
	 */
	public void bindAspect(String anAspect, EODisplayGroup aDisplayGroup, String aKey) {
		if (ChildrenAspect.equals(anAspect)) {
			childrenDisplayGroup = aDisplayGroup;
			childrenKey = aKey;
		}
		if (IsLeafAspect.equals(anAspect)) {
			leafDisplayGroup = aDisplayGroup;
			leafKey = aKey;
		}
		super.bindAspect(anAspect, aDisplayGroup, aKey);
	}

	/**
	 * Overridden to call createTree if necessary, call configureColumn, call
	 * createTreeAssociation if necessary, and then call to super.
	 */
	public void establishConnection() {
		if (tree == null) {
			tree = createTree();
		}

		configureColumn((TableColumn) object());

		if (treeAssociation == null) {
			treeAssociation = createTreeAssociation(tree);
		}

		treeAssociation.bindAspect(TitlesAspect, valueDisplayGroup, valueKey);
		if (childrenKey != null) {
			treeAssociation.bindAspect(ChildrenAspect, childrenDisplayGroup, childrenKey);
		}
		if (leafKey != null) {
			treeAssociation.bindAspect(IsLeafAspect, leafDisplayGroup, leafKey);
		}

		// ensure table association's source is tree asssociation's child group
		getTableAssociation().bindAspect(SourceAspect, treeAssociation.childrenDisplayGroup, "");

		treeAssociation.establishConnection();

		table.setRowHeight(tree.getRowHeight());

		super.establishConnection();

		// cause sort ordering to apply to root node of tree
		if (childrenKey != null) {
			getTableAssociation().sortTarget = (EODisplayGroup) treeAssociation.getRoot();
		}
	}

	/**
	 * Breaks the connection between this association and its object. Override to
	 * stop listening for events from the object.
	 */
	public void breakConnection() {
		super.breakConnection();
		treeAssociation.breakConnection();

		// restore original source display group
		getTableAssociation().sortTarget = null;
	}

	/**
	 * Called by establishConnection if setTree was not called. This implementation
	 * returns a stock JTree. Override to provide your own customized JTree. Note
	 * that TreeTableCellRenderer will further customize this tree when
	 * configureColumn is called.
	 */
	protected JTree createTree() {
		return new JTree();
	}

	/**
	 * Called by establishConnection to create a tree association only if no tree
	 * association has already been created. This implementation returns a stock
	 * TreeAssociation. Override to return your own customized TreeAssociation.
	 */
	protected TreeModelAssociation createTreeAssociation(JTree aTree) {
		return new TreeAssociation(aTree);
	}

	/**
	 * Called by establishConnection to configure the column with a
	 * TreeTableCellRenderer using the current JTree. Override to further customize
	 * the column, or customize your column yourself after the call to
	 * establishConnection.
	 */
	protected void configureColumn(TableColumn aColumn) {
		aColumn.setCellRenderer(new TreeTableCellRenderer(tree));
	}

	/**
	 * Gets the JTree currently used for the column renderer. If not specified,
	 * returns null.
	 */
	public JTree getTree() {
		return tree;
	}

	/**
	 * Gets the TreeModelAssociation currently used for the tree. If not tree is not
	 * specified, returns null.
	 */
	public TreeModelAssociation getTreeModelAssociation() {
		if (tree == null)
			return null;
		if (!(tree.getModel() instanceof TreeModelAssociation))
			return null;
		return (TreeModelAssociation) tree.getModel();
	}

	/**
	 * Sets the JTree to be used for the column renderer. If not specified,
	 * createTree() will be called to create a JTree.
	 */
	public void setTree(JTree aTree) {
		tree = aTree;
	}

}

/*
 * $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.9 2003/08/06 23:07:52 chochos general code cleanup (mostly,
 * removing unused imports)
 *
 * Revision 1.8 2002/05/03 21:31:50 mpowers Actually works better without
 * selectionPaintedImmediately.
 *
 * Revision 1.7 2002/04/12 21:05:58 mpowers Now distinguishing changes in titles
 * group even better.
 *
 * Revision 1.6 2002/03/08 23:18:48 mpowers Added accessor for tree association.
 *
 * Revision 1.5 2002/03/07 23:04:36 mpowers Refining TreeColumnAssociation.
 *
 * Revision 1.4 2002/03/06 13:04:16 mpowers Implemented cascading qualifiers in
 * tree nodes.
 *
 * Revision 1.3 2002/03/05 23:18:28 mpowers Added documentation. Added
 * isSelectionPaintedImmediate and isSelectionTracking attributes to
 * TableAssociation. Added getTableAssociation to TableColumnAssociation.
 *
 * Revision 1.2 2002/03/04 22:48:22 mpowers Now working with table association
 * to sort the root node.
 *
 * Revision 1.1 2002/03/01 23:42:09 mpowers Implemented TreeColumnAssociation,
 * and updated documentation.
 *
 *
 */