path: root/projects/net.wotonomy.ui.swing/src/main/java/net/wotonomy/ui/swing/TableColumnAssociation.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.Color;
import java.awt.Graphics;
import java.awt.Graphics2D;
import java.awt.Polygon;
import java.awt.Rectangle;
import java.awt.RenderingHints;
import java.util.Iterator;
import java.util.List;

import javax.swing.JTable;
import javax.swing.table.TableColumn;

import net.wotonomy.control.EOSortOrdering;
import net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.internal.ValueConverter;
import net.wotonomy.foundation.internal.WotonomyException;
import net.wotonomy.ui.EOAssociation;
import net.wotonomy.ui.EODisplayGroup;
import net.wotonomy.ui.swing.TableAssociation.TableAssociationModel;


/**
* TableColumnAssociation binds a column of a JTable
* to a property of the elements of a display group.  
* Bindings are: 
* <ul>
* <li>value: a property convertable to a string for
* display in the cells of the table column</li> 
* <li>editable: a property convertable to a boolean 
* that determines the editability of the corresponding
* cells in the column.</li> 
* </ul>

* Because TableColumns do not have a handle to their
* containing JTable, setTable() must be called before
* calling establishConnection().  This will add the 
* controlled TableColumn to the specified JTable.
*
* Columns appear in the table in the order in which
* setTable is called on the corresponding association.
* The original table model index is ignored.
*
* Column names appear in the table based on the value
* of TableColumn.getHeaderValue().
*
* @author michael@mpowers.net
* @author $Author: cgruber $
* @version $Revision: 904 $
*/
public class TableColumnAssociation extends EOAssociation
{
    static final NSArray aspects = 
        new NSArray( new Object[] {
            ValueAspect, EditableAspect
        } );
    static final NSArray aspectSignatures = 
        new NSArray( new Object[] {
            AttributeToOneAspectSignature
        } );
    static final NSArray objectKeysTaken = 
        new NSArray( new Object[] {
            "table" 
        } );

    static Color[] sortIndicatorColorList;
		
	EODisplayGroup valueDisplayGroup, editableDisplayGroup;
	String valueKey, editableKey;
    boolean sortable;
    boolean sortCaseSensitive;
    JTable table;
	
    /**
    * Constructor specifying the object to be controlled by this
    * association.  Throws an exception if the object is not
	* a TableColumn.  setTable() must be called before 
	* establishing the connection.
    */
    public TableColumnAssociation ( Object anObject )
    {
        super( anObject );
		valueDisplayGroup = null;
		valueKey = null;
		editableDisplayGroup = null;
		editableKey = null;
        sortable = true;
        sortCaseSensitive = true;
        table = null;
    }
	
	/**
	* Sets the table to be used for this column association.
	* If no TableAssociation exists for the specified table,
	* one will be created automatically.  The controlled
	* table column will be added to the table.  Note that
	* the table column's model index is ignored: table columns
	* appear in the table in the order in which setTable is
	* called on their corresponding associations.
	*/
	public void setTable( JTable aTable )
	{
        table = aTable;
        if ( table == null ) return;
        
        // creates table association if not existing
        getTableAssociation();        
	}
    
    /**
    * Returns the table association for this table column,
    * or null if no table has been set.  This method will
    * create the association if none exists for the table.
    */
    public TableAssociation getTableAssociation()
    {
        if ( table == null ) return null;
        
        TableAssociation result;        
		if ( ! ( table.getModel() instanceof TableAssociationModel ) )
		{
			result = new TableAssociation( table );
			result.bindAspect( 
				SourceAspect, displayGroupForAspect( ValueAspect ), "" );
		}
        else
        {
            result = ((TableAssociationModel)table.getModel()).getAssociation();
        }
        return result;
    }
    
    /**
    * 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;
    }
    
    /**
    * Returns a List of EOAssociation subclasses that,
    * for the objects that are usable for this association,
    * are less suitable than this association.
    */
    public static NSArray associationClassesSuperseded ()
    {
        return new NSArray();
    }
    
    /**
    * Returns whether this class can control the specified 
    * object. 
    */
    public static boolean isUsableWithObject ( Object anObject )
    {
        return ( anObject instanceof TableColumn );
    }
    
    /**
    * Returns a List of properties of the controlled object
    * that are controlled by this class.  For example,
    * "stringValue", or "selected".
    */
    public static NSArray objectKeysTaken ()
    {
        return objectKeysTaken;
    }
    
    /**
    * Returns the aspect that is considered primary
    * or default.  This is typically "value" or somesuch.
    */
    public static String primaryAspect ()
    {
        return ValueAspect;
    }
        
    /**
    * Returns whether this association can bind to the
    * specified display group on the specified key for
    * the specified aspect.  
    */
    public boolean canBindAspect ( 
        String anAspect, EODisplayGroup aDisplayGroup, String aKey)
    {
        return ( aspects.containsObject( anAspect ) );
    }
    
    /**
    * 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 ( ValueAspect.equals( anAspect ) )
		{
			valueDisplayGroup = aDisplayGroup;	
			valueKey = aKey;
		}
		if ( EditableAspect.equals( anAspect ) )
		{
			editableDisplayGroup = aDisplayGroup;
			editableKey = aKey;
		}
		super.bindAspect( anAspect, aDisplayGroup, aKey );
	}
	
    /**
    * Establishes a connection between this association
    * and the controlled object.  Subclasses should begin
    * listening for events from their controlled object here.
    */
    public void establishConnection ()
    {
        addAsListener();
        
        if ( table == null ) throw new WotonomyException(
            "A table must be specified by calling setTable()" );

		// add association to model
		TableAssociationModel model = 
			(TableAssociationModel) table.getModel();
        model.addColumnAssociation( this );
        
        super.establishConnection();
    }
    
    /**
    * Breaks the connection between this association and 
    * its object.  Override to stop listening for events
    * from the object.
    */
    public void breakConnection ()
    {
        removeAsListener();

        if ( table == null ) throw new WotonomyException(
            "TableColumnAssociation's table may not be null" );

		// remove association from model
		TableAssociationModel model = 
			(TableAssociationModel) table.getModel();
		model.removeColumnAssociation( this );
        
        super.breakConnection();
    }

    protected void addAsListener()
    {
    }

    protected void removeAsListener()
    {
    }
	
	/**
	* Returns the value to be displayed at the specified index.
	* This method is called by the TableAssocation to populate
	* the table model.
	* This implementation simply retrieves the value from the
	* display group bound to the value aspect.
	*/
	public Object valueAtIndex( int aRowIndex )
	{
		if ( valueDisplayGroup != null )
		{
			return valueDisplayGroup.valueForObjectAtIndex( 
				aRowIndex, valueKey );
		}
		return null;
	}
	
	/**
	* Sets a value for the specified index.  This method is 
	* called by the TableAssocation after a cell has been
	* edited.
	* This implementation simply sets the value in the 
	* display group bound to the value aspect.
	*/
	public void setValueAtIndex( Object aValue, int aRowIndex )
	{
		if ( valueDisplayGroup != null )
		{
			valueDisplayGroup.setValueForObjectAtIndex( 
				aValue, aRowIndex, valueKey );
		}
	}
    
    /**
    * Returns whether this column should be sorted when the
    * user clicks on the column header.  Defaults to true.
    */
    public boolean isSortable()
    {
        return sortable;
    }
    
    /**
    * Sets whether this column should be sorted when the
    * user clicks on the column header.
    */
    public void setSortable( boolean isSortable )
    {
        sortable = isSortable;   
    }

    /**
    * Returns whether this column should be sorted 
    * in a case sensitive manner.  Defaults to true.
    */
    public boolean isSortCaseSensitive()
    {
        return sortCaseSensitive;
    }
    
    /**
    * Sets whether this column should be sorted when
    * in a case sensitive manner.
    * If false, the column contents should be string values.
    */
    public void setSortCaseSensitive( boolean isCaseSensitive )
    {
        sortCaseSensitive = isCaseSensitive;   
    }

	/**
	* Called by the TableAssociation to determine whether 
	* the value at the specified row is editable.
	* This is determined by the binding of the Editable aspect,
	* looking at the value of the corresponding index in that
	* display group.  Note: because the display group may
	* not have the same number if items, the selected index is
	* used if the editable display group is not the same as the
	* the value display group.
	*/
	public boolean isEditableAtRow( int aRowIndex )
	{
		if ( editableKey == null ) return false;
		Object value = null;
		if ( editableDisplayGroup != null )
		{
			// if using the same group for both, return the value for the index
			if ( editableDisplayGroup.equals( valueDisplayGroup ) )
			{
				value =
					editableDisplayGroup.valueForObjectAtIndex( aRowIndex, editableKey );
			}
			else // using an external display group to determine editability
			{
				// ignore index and use the selected object value from display group
				value =
					editableDisplayGroup.selectedObjectValueForKey( editableKey );
			}
		}
		else
		{
			// treat bound key without display group as a value
			value = editableKey;	
		}
		if ( value == null ) return false; // null defaults to false
		Boolean result = (Boolean)
			ValueConverter.convertObjectToClass( value, Boolean.class );
		if ( result == null ) return true; // non-null defaults to true
		return result.booleanValue();
	}
		
    // convenience

    private TableColumn component()
    {
        return (TableColumn) object();
    }
    
    /**
    * Called by TableAssociation to get a EOSortOrdering suitable 
    * for the information in this column.
    * This implementation returns a EOSortOrdering with the key
    * equal to the value aspect's key and the appropriate selector
    * for the specified ascending value and the case sensitivity
    * of this column.
    * Override to customize the sort for your column.
    */
    public EOSortOrdering getSortOrdering( boolean isAscending )
    {
        if ( isAscending )
        {
            if ( isSortCaseSensitive() )
            {
                return new EOSortOrdering(
                    valueKey, 
                    EOSortOrdering.CompareAscending ) ;
            }
            else
            {
                return new EOSortOrdering(
                    valueKey, 
                    EOSortOrdering.CompareCaseInsensitiveAscending ) ;
            }
        }
        else
        {
            if ( isSortCaseSensitive() )
            {
                return new EOSortOrdering(
                    valueKey, 
                    EOSortOrdering.CompareDescending ) ;
            }
            else
            {
                return new EOSortOrdering(
                    valueKey, 
                    EOSortOrdering.CompareCaseInsensitiveDescending ) ;
            }
        }
    }
    
    /**
    * Returns the one-based index of this assocation's sort ordering
    * in the specified list of orderings.  If the sign of the returned
    * value is negative, the ordering is descending.  If the return
    * value is zero, no matching ordering was found.
    */
    protected int getIndexOfMatchingOrdering( List orderings )
    {
        // find index of matching ordering
        int index = 0;
        EOSortOrdering ordering = null;
        Iterator i = orderings.iterator();
        while ( i.hasNext() )
        {
            index++;
            ordering = (EOSortOrdering) i.next();
            if ( ordering.key().equals( valueKey ) )
            {
                // determine ascending or descending 
                if ( getSortOrdering( true ).equals( ordering ) )
                {
                    return index;
                }
                else
                if ( getSortOrdering( false ).equals( ordering ) )
                {
                    return -index;
                }
            }
        }
        return 0;
        
    }
    
    /**
    * Called by TableAssociation to draw some indicator in the
    * specified rectangle using the specified graphics to indicate
    * the specified sort state.  The rectangle corresponds to the
    * bounds of the column header.
    * This implementation draws a small transparent gray triangle at
    * the right edge of the bounding rectangle.
    * Override to do something different or to do nothing at all.
    */ 
    protected void drawSortIndicator( Rectangle aBoundingRectangle,
        Graphics aGraphicsContext, List orderings )
    {
        int index = getIndexOfMatchingOrdering( orderings );
        if ( index == 0 ) return;
        
        boolean isAscending = ( index > 0 );
        index = Math.abs( index );
        
        // turn on anti-aliasing
        if ( aGraphicsContext instanceof Graphics2D )
        {
            ((Graphics2D)aGraphicsContext).setRenderingHint( 
                RenderingHints.KEY_ANTIALIASING, 
                RenderingHints.VALUE_ANTIALIAS_ON );
        }
        
        Rectangle r = new Rectangle( aBoundingRectangle );
        
        // resize to a right-justified square, sides equal to height
        r.setBounds( r.x + r.width - r.height, r.y, r.height, r.height );
        
        // resize to about a third smaller
        int portion = r.height / 3;
        r.grow( -portion, -portion );
        
        // transparencies cause java2d printing to rasterize,
        //   resulting in excessive memory usage and print time.
        // aGraphicsContext.setColor( new Color( 0, 0, 0, 255 / (index*2) ) );
        aGraphicsContext.setColor( getSortIndicatorColor( index ) );
        
        Polygon triangle;
        if ( !isAscending )
        {
            triangle = new Polygon( 
                new int[] { r.x, r.x+r.width/2, r.x+r.width },
                new int[] { r.y, r.y+r.height, r.y }, 3 );            
        }
        else
        {
            triangle = new Polygon( 
                new int[] { r.x, r.x+r.width/2, r.x+r.width },            
                new int[] { r.y+r.height, r.y, r.y+r.height }, 3 );
        }                
        aGraphicsContext.fillPolygon( triangle );
    }
    
    /**
     * Returns a color to be used by the sort indicator based on the index
     * of the sorting column.  The goal of this method is to make the color
     * appear lighter and lighter, the "less" primary the sort order for this
     * column is.  This can be acheives simply though a "transparent" color,
     * however, during printing of the corresponding table, java print
     * kicks into "raster" based printing when printing a component with
     * a transparent color instead of "vector" based printing.  Raster
     * based printing can take up to 20-30 times longer to print than
     * vector printing and consume several times the amount of memory.
     * Raster-based printing should be avoided at all costs if the a component
     * is to be printed (as of Java 1.3.1).
     * @param index The "sort" index of the associated table column.  The higher
     *        the index, the lighter the color will be.  An index of 0 will
     *        return null.
     * @return The color to use when rendering the sort indicator.
     */
    protected static Color getSortIndicatorColor( int index )
    {
        if ( index == 0 ) return null;

        // Create the color list if not already created.
        if ( sortIndicatorColorList == null )
        {
            // Default size to 13 elements, it would be extremely rare that a
            // user sorts more than 12 columns at a time (although possible).
            // (Index 0 is not used.)
            sortIndicatorColorList = new Color[ 13 ];
        }

        // Get the color out of the color list.  Use the index directly as
        // an index into an ordered list.  If the color has already been
        // created for that index, then return it, otherwise create the color.
        if ( ( index < sortIndicatorColorList.length ) &&
             ( sortIndicatorColorList[ index ] != null ) )
        {
            return sortIndicatorColorList[ index ];
        }

        // The following logic performs the same affect as the above
        // transparent color, without actually using a transparent color.
        // Start with the table header's background color and derive a color
        // that is "darker" than that color.  Any color this logic creates will
        // be between those two colors.
        Color lightColor = java.awt.SystemColor.control;
        Color darkColor = lightColor.darker().darker();

        // Make the light color (the upper bound) a little darker, so that even
        // the lightest triangle will still be slightly visible.
        lightColor = new Color(
            Math.max( ( int )( lightColor.getRed() * 0.9), 0 ),
            Math.max( ( int )( lightColor.getGreen() * 0.9), 0 ),
            Math.max( ( int )( lightColor.getBlue() * 0.9), 0) );

        // Subtract the light color from the dark color.  This is the range
        // between the two colors.
        Color difference = new Color( lightColor.getRed() - darkColor.getRed(),
            lightColor.getGreen() - darkColor.getGreen(),
            lightColor.getBlue() - darkColor.getBlue() );

        // If the index is 1, user the dark color as is.  Otherwise scale the
        // color closer and closer to the lighter color as the index gets
        // biggger and bigger.
        if ( index > 1 )
        {
            float factor = ( float )Math.pow( 0.5, ( index - 1 ) );
            darkColor = new Color(
                Math.max( lightColor.getRed() - ( int )( difference.getRed() * factor ), 0 ),
                Math.max( lightColor.getGreen() - ( int )( difference.getGreen() * factor ), 0 ),
                Math.max( lightColor.getBlue() - ( int )( difference.getBlue() * factor ), 0 ) );
        }

        // Cache the created color in the color list for this index.
        if ( index >= sortIndicatorColorList.length )
        {
            // The color list is too small, create a new larger list with
            // some padding for even larger indicies.
            Color[] oldList = sortIndicatorColorList;
            sortIndicatorColorList = new Color[ index + 5 ];
            System.arraycopy( oldList, 0, sortIndicatorColorList, 0, oldList.length );
        }
        sortIndicatorColorList[ index ] = darkColor;

        return darkColor;
    } 
}

/*
 * $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.16  2003/08/06 23:07:52  chochos
 * general code cleanup (mostly, removing unused imports)
 *
 * Revision 1.15  2002/08/22 15:42:49  mpowers
 * No longer using transparency to render sort indicator (see comments).
 *
 * Revision 1.14  2002/04/12 21:05:57  mpowers
 * Now distinguishing changes in titles group even better.
 *
 * Revision 1.13  2002/03/05 23:18:28  mpowers
 * Added documentation.
 * Added isSelectionPaintedImmediate and isSelectionTracking attributes
 * to TableAssociation.
 * Added getTableAssociation to TableColumnAssociation.
 *
 * Revision 1.12  2002/03/04 22:11:43  mpowers
 * Darkened the sort indicator to better differentiate the first sort.
 *
 * Revision 1.11  2002/03/04 03:58:17  mpowers
 * Refined table header click behavior.
 *
 * Revision 1.10  2002/03/01 15:42:00  mpowers
 * Table column headers now always show their sort indicator.
 * A third table-column click clears the sort for that column.
 *
 * Revision 1.9  2002/02/28 23:01:39  mpowers
 * TableColumnAssociations add and remove themselves from the TableAssociation
 * when their connection is established and broken respectively.
 * TableAssociations now break connection if they have no column associations.
 *
 * Revision 1.8  2001/06/05 16:03:56  mpowers
 * Flipped the triangle to be consistent with Aqua.
 *
 * Revision 1.7  2001/03/09 22:09:22  mpowers
 * Now better handling jdk1.1 for rendering the column header.
 *
 * Revision 1.6  2001/02/17 16:52:05  mpowers
 * Changes in imports to support building with jdk1.1 collections.
 *
 * Revision 1.5  2001/01/12 19:11:56  mpowers
 * Fixed table column click sorting.
 *
 * Revision 1.4  2001/01/12 17:20:30  mpowers
 * Moved EOSortOrdering creation to ColumnAssociation.
 *
 * Revision 1.3  2001/01/11 21:55:57  mpowers
 * Implemented sort indicator for table column headers.
 *
 * Revision 1.2  2001/01/11 20:34:26  mpowers
 * Implemented EOSortOrdering and added support in framework.
 * Added header-click to sort table columns.
 *
 * Revision 1.1.1.1  2000/12/21 15:49:03  mpowers
 * Contributing wotonomy.
 *
 * Revision 1.5  2000/12/20 16:25:41  michael
 * Added log to all files.
 *
 *
 */