path: root/projects/net.wotonomy.ui.swing/src/main/java/net/wotonomy/ui/swing/ComboBoxAssociation.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.event.ActionEvent;
import java.awt.event.ActionListener;
import java.awt.event.FocusEvent;
import java.awt.event.FocusListener;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.List;

import javax.swing.AbstractListModel;
import javax.swing.ComboBoxModel;
import javax.swing.JComboBox;

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;

/**
* ComboBoxAssociation binds JComboBoxes to
* display groups.  Bindings are:
* <ul>
*
* <li>value: optional - a property of the selected object in the
* display group that will be bind to the item the user
* selects or the text that the user enters in the field.
* If the value aspect is not bound, then the combo box works
* as an "overview" assocation and changing the selected object
* in the combobox will modify the selection of the display group
* bound to the objects or the titles display groups (in that order).</li>
*
* <li>titles: optional - a property of the objects in the bound
* display group that will appear in the list.  If the
* objects aspect is not bound, this property is also
* used to populate the value binding.  If the titles
* aspect itself is not bound, the items already in the
* combobox will be used to update the value in the
* selected object in the bound display group.</li>
*
* <li>objects: optional - if specified, when the user
* selects a title in the list, the property of the
* object at the corresponding index of the bound display
* group will be used to populate the value binding.
* If the objects aspect is used with an editable combo
* box, any value entered that does not match one of the
* titles in the list will produce a null value.</li>
*
* <li>enabled: optional - a boolean property of the
* selected object in the display group that determines whether
* the user can edit the field.</li>
*
* </ul>
*
* @author michael@mpowers.net
* @author $Author: cgruber $
* @version $Revision: 904 $
*/
public class ComboBoxAssociation extends EOAssociation
    implements FocusListener, ActionListener
{
    static final NSArray aspects =
        new NSArray( new Object[] {
            TitlesAspect, ValueAspect,
            ObjectsAspect, EnabledAspect
        } );
    static final NSArray aspectSignatures =
        new NSArray( new Object[] {
            AttributeToOneAspectSignature,
            AttributeToOneAspectSignature,
            AttributeToOneAspectSignature,
            AttributeToOneAspectSignature
        } );
    static final NSArray objectKeysTaken =
        new NSArray( new Object[] {
            "text"
        } );

    private boolean wasNull;
    private static final String EMPTY_STRING = "";

   /**
    * Constructor specifying the object to be controlled by this
    * association.  Does not establish connection.
    */
    public ComboBoxAssociation ( 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;
    }

    /**
    * 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 JComboBox );
    }

    /**
    * 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 ) );
    }

    /**
    * Establishes a connection between this association
    * and the controlled object.  Subclasses should begin
    * listening for events from their controlled object here.
    */
    public void establishConnection ()
    {
        super.establishConnection();

        // prepopulate titles
        EODisplayGroup displayGroup =
            displayGroupForAspect( TitlesAspect );
        if ( displayGroup != null )
        {
            String key = displayGroupKeyForAspect( TitlesAspect );
            populateTitles( displayGroup, key );
        }
        addAsListener();
        subjectChanged();
    }

    protected void addAsListener()
    {
        component().addActionListener( this );
        component().addFocusListener( this );
    }

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

    protected void removeAsListener()
    {
        component().removeActionListener( this );
        component().removeFocusListener( this );
    }

    /**
    * Called when either the selection or the contents
    * of an associated display group have changed.
    */
    public void subjectChanged ()
    {
        removeAsListener();

        JComboBox component = component();
        EODisplayGroup displayGroup;
        String key;

        // titles aspect
        displayGroup = displayGroupForAspect( TitlesAspect );
        if ( displayGroup != null )
        {
            ComboBoxModel model = component().getModel();
            // if first time, or if backing group has changed
//          if ( ( ! ( model instanceof ComboBoxAssociationModel ) )
//          || ( displayGroup.contentsChanged() ) )
//          {
                key = displayGroupKeyForAspect( TitlesAspect );
                populateTitles( displayGroup, key );
//          }
        }

        // value aspect
        displayGroup = displayGroupForAspect( ValueAspect );
        if ( displayGroup != null )
        {
            key = displayGroupKeyForAspect( ValueAspect );
            component.setEnabled( 
                    displayGroup.enabledToSetSelectedObjectValueForKey( key ) );
            //Object value = displayGroup.selectedObjectValueForKey( key );
            Object value;


            if ( displayGroup.selectedObjects().size() > 1 )
            {

                Object previousValue;

                Iterator indexIterator = displayGroup.selectionIndexes().
                                          iterator();

                // get value for the first selected object.
                int initialIndex = ( (Integer)indexIterator.next() ).intValue();
                previousValue = displayGroup.valueForObjectAtIndex(
                                          initialIndex, key );
                value = null;

                // go through the rest of the selected objects, compare each
                // value with the previous one. continue comparing if two
                // values are equal, break the while loop if they're different.
                // the final value will be the common value of all selected objects
                // if there is one, or be blank if there is not.
                while ( indexIterator.hasNext() )
                {
                    int index = ( (Integer)indexIterator.next() ).intValue();
                    Object currentValue = displayGroup.valueForObjectAtIndex(
                                          index, key );

                    if ( currentValue != null && !currentValue.equals( previousValue ) )
                    {
                        value = null;
                        break;
                    }
                    else
                    {
                        // currentValue is the same as the previous one
                        value = currentValue;
                    }

                } // end while

            } else {
                // if there's only one object selected.
                value = displayGroup.selectedObjectValueForKey( key );
            } // end checking the size of selected objects in displayGroup


            // objects aspect
            EODisplayGroup objectsDisplayGroup =
                displayGroupForAspect( ObjectsAspect );
            if ( ( objectsDisplayGroup != null ) && ( value != null ) )
            {
                String objectKey = displayGroupKeyForAspect( ObjectsAspect );
                Object match;
                int index = NSArray.NotFound;
                int count = objectsDisplayGroup.displayedObjects().count();
                for ( int i = 0; i < count; i++ )
                {
                    match = objectsDisplayGroup.valueForObjectAtIndex( i, objectKey );
                                        if ( value.equals( match ) )
                    {
                        index = i;
                    }
                }
                if ( index == NSArray.NotFound )
                {
                    if ( component.getSelectedItem() != null )
                    {
                        component.setSelectedItem( null );
                    }
                }
                else
                {
                    if ( component.getSelectedIndex() != index )
                    {
                        component.setSelectedIndex( index );
                    }
                }
            }
            else
            {
                component.setSelectedItem( value );
            }
        }
        else // values aspect not bound
        {
            // use objects group if specified
            EODisplayGroup sourceGroup =
                displayGroupForAspect( ObjectsAspect );
            if ( sourceGroup == null )
            {
                // fall back on titles group
                sourceGroup = displayGroupForAspect( TitlesAspect );
            }

            if ( sourceGroup != null )
            {
                List selection = sourceGroup.selectionIndexes();
                if ( ( selection != null ) && ( selection.size() > 0 ) )
                {
                    component.setSelectedIndex( ((Integer)selection.get(0)).intValue() );
                }
                else
                {
                    // the combo box model decides what to do with this value
                    component.setSelectedItem( null );
                }
            }
        }

        // enabled aspect
        displayGroup = displayGroupForAspect( EnabledAspect );
        if ( displayGroup != null )
        {
            key = displayGroupKeyForAspect( EnabledAspect );
            Object value =
                displayGroup.selectedObjectValueForKey( key );
            Boolean converted = null;
            if ( value != null ) 
            {
                converted = (Boolean)
                    ValueConverter.convertObjectToClass(
                        value, Boolean.class );
            }
            if ( converted == null ) converted = Boolean.FALSE;
            if ( converted.booleanValue() != component.isEnabled() )
            {
                component.setEnabled( converted.booleanValue() );
            }
        }

        addAsListener();
    }

    /**
    * Called to repopulate the title list from the
    * specified display group.
    */
    protected void populateTitles(
        EODisplayGroup displayGroup, String key )
    {
        component().setModel(
            new ComboBoxAssociationModel( displayGroup, key ) );
    }

    /**
    * Forces this association to cause the object to
    * stop editing and validate the user's input.
    * @return false if there were problems validating,
    * or true to continue.
    */
    public boolean endEditing ()
    {
        return writeValueToDisplayGroup();
    }

    /**
    * Writes the value currently in the component
    * to the selected object in the display group
    * bound to the value aspect.
    * @return false if there were problems validating,
    * or true to continue.
    */
    protected boolean writeValueToDisplayGroup()
    {
        JComboBox component = component();
        EODisplayGroup displayGroup;
        String key;

        // selected title aspect
        displayGroup = displayGroupForAspect( ValueAspect );
        if ( displayGroup != null )
        {
            key = displayGroupKeyForAspect( ValueAspect );
            Object value = null;

            // selected object aspect, if any
            EODisplayGroup objectsGroup =
                displayGroupForAspect( ObjectsAspect );
            if ( objectsGroup != null )
            {
                try
                {
                    String objectKey = displayGroupKeyForAspect( ObjectsAspect );
                    int index = component.getSelectedIndex();
                    if ( index != -1 )
                    {
                        value = objectsGroup
                            .valueForObjectAtIndex( index, objectKey );
                    }
                    else // selected index is -1
                    {
                        // the combo box is probably editable,
                        // so there is no corresponding object.
                        value = null;
                    }
                }
                catch ( NullPointerException npe )
                {
                    // catches NPE on line 436 of JComboBox.java:
                    // this is a common developer error
                    throw new WotonomyException( "ComboBoxAssociation: " +
                    "The object in the VALUE property may not have been found in the " +
                    "objects in the TITLES group.", npe );
                }
            }
            else // just use the selected item
            {
                value = component.getSelectedItem();
            }

            boolean returnValue = true;
            if ( displayGroup.selectedObjects().size() == 1 )
            {   // displayGroup has only one object
                // only set value if changed
                Object existingValue = displayGroup.selectedObjectValueForKey( key );
                if ( value == existingValue ) return true;
                if ( ( existingValue != null ) && ( existingValue.equals( value ) ) ) return true;

                // value has changed: update the value.
                return displayGroup.setSelectedObjectValue( value, key );
            }
            else if ( displayGroup.selectedObjects().size() > 1 )
            {
                // displayGroup has more than one object
                Iterator selectedIterator = displayGroup.selectionIndexes().iterator();
                while ( selectedIterator.hasNext() )
                {
                    int index = ( (Integer)selectedIterator.next() ).intValue();

                    if ( !displayGroup.setValueForObjectAtIndex( value, index, key ) )
                    {
                        returnValue = false;
                    }
                }
                return returnValue;

            } // end checking size of displayGroup

        }
        else // values aspect not bound
        {
            // use objects group if specified
            EODisplayGroup sourceGroup =
                displayGroupForAspect( ObjectsAspect );
            if ( sourceGroup == null )
            {
                // fall back on titles group
                sourceGroup = displayGroupForAspect( TitlesAspect );
            }

            if ( sourceGroup != null )
            {
                int index = component.getSelectedIndex();
                if ( index != -1 )
                {
                    sourceGroup.setSelectionIndexes( new NSArray( new Integer( index ) ) );
                }
                else
                {
                    sourceGroup.setSelectedObject( null );
                }
                return true;
            }
        }

        return false;
    }

    // interface ActionListener

    /**
    * Updates object on action performed.
    */
    public void actionPerformed( ActionEvent evt )
    {
        writeValueToDisplayGroup();
    }

    // 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().isEditable() )
        {
            if ( endEditing() )
            {
                Object o;
                EODisplayGroup displayGroup;
                Enumeration e = aspects().objectEnumerator();
                while ( e.hasMoreElements() )
                {
                    displayGroup =
                    displayGroupForAspect( e.nextElement().toString() );
                    if ( displayGroup != null )
                    {
                        displayGroup.associationDidEndEditing( this );
                    }
                }
            }
        }
    }

    // convenience

    private JComboBox component()
    {
        return (JComboBox) object();
    }

    /**
    * Used as the data model for the controlled combo box.
    */
    private class ComboBoxAssociationModel extends AbstractListModel
                                implements ComboBoxModel
    {
        EODisplayGroup displayGroup;
        String key;
        Object selectedItem;

        ComboBoxAssociationModel(
            EODisplayGroup aDisplayGroup, String aKey )
        {
            displayGroup = aDisplayGroup;
            key = aKey;
            selectedItem = null;
        }

        public Object getElementAt(int index)
        {
            return displayGroup.valueForObjectAtIndex( index, key );
        }

        public int getSize()
        {
            return displayGroup.displayedObjects().count();
        }

        public void setSelectedItem(Object anItem)
        { //System.out.println( "setSelectedItem: " + anItem );
            selectedItem = anItem;

            // must do this to notify an editable combo,
            //   otherwise the wrong value appears.
            fireContentsChanged( this, -1, -1 );
        }

        public Object getSelectedItem()
        { //System.out.println( "getSelectedItem: " + selectedItem );
            return selectedItem;
        }
    }
}

/*
 * $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.13  2004/01/28 18:34:57  mpowers
 * Better handling for enabling.
 * Now respecting enabledToSetSelectedObjectValueForKey from display group.
 *
 * Revision 1.12  2003/08/06 23:07:52  chochos
 * general code cleanup (mostly, removing unused imports)
 *
 * Revision 1.11  2001/07/30 16:32:55  mpowers
 * Implemented support for bulk-editing.  Detail associations will now
 * apply changes to all selected objects.
 *
 * Revision 1.10  2001/07/23 20:17:56  mpowers
 * Now works as an overview association if the values aspect is not bound.
 *
 * Revision 1.9  2001/06/30 14:57:29  mpowers
 * Removed a println.
 *
 * Revision 1.8  2001/06/29 22:28:19  mpowers
 * Tabs to spaces.
 *
 * Revision 1.7  2001/06/29 22:17:31  mpowers
 * Now updating the component on establishConnection.
 *
 * Revision 1.6  2001/05/14 15:24:49  mpowers
 * Only updating if change was made.  Feels like I had fixed this here before.
 *
 * Revision 1.5  2001/04/09 21:41:08  mpowers
 * Fixed a bug I thought that I had fixed before.
 *
 * Revision 1.4  2001/03/01 20:37:17  mpowers
 * Updated docs to emphasize that titles aspect is optional.
 *
 * Revision 1.3  2001/02/17 16:52:05  mpowers
 * Changes in imports to support building with jdk1.1 collections.
 *
 * Revision 1.2  2001/01/10 17:01:08  mpowers
 * Caught a common developer error.
 *
 * Revision 1.1.1.1  2000/12/21 15:48:43  mpowers
 * Contributing wotonomy.
 *
 * Revision 1.8  2000/12/20 16:25:40  michael
 * Added log to all files.
 *
 *
 */