/*
 * @(#)StringObjectView.java    2.3   2 May 2006
 *
 * Copyright 2006
 * College of Computer and Information Science
 * Northeastern University
 * Boston, MA  02115
 *
 * The Java Power Tools software may be used for educational
 * purposes as long as this copyright notice is retained intact
 * at the top of all source files.
 *
 * To discuss possible commercial use of this software, 
 * contact Richard Rasala at Northeastern University, 
 * College of Computer and Information Science,
 * 617-373-2462 or rasala@ccs.neu.edu.
 *
 * The Java Power Tools software has been designed and built
 * in collaboration with Viera Proulx and Jeff Raab.
 *
 * Should this software be modified, the words "Modified from 
 * Original" must be included as a comment below this notice.
 *
 * All publication rights are retained.  This software or its 
 * documentation may not be published in any media either
 * in whole or in part without explicit permission.
 *
 * This software was created with support from Northeastern 
 * University and from NSF grant DUE-9950829.
 */

package edu.neu.ccs.gui;

import edu.neu.ccs.util.*;

import java.awt.event.*;

/**
 * The interface for views designed to permit the selection of an object
 * using an associated string in a <CODE>StringObjectMap</CODE>.
 *
 * @author  Richard Rasala
 * @version 2.3
 * @since   2.3
 */
public interface StringObjectView
    extends JPTConstants 
{
    /** Bound property name for the view state. */
    public static final String VIEW_STATE = Displayable.VIEW_STATE;
    
    
    /**
     * Returns the currently selected string in the view.
     *
     * @return the selected string
     * @see #getSelectedObject()
     */
    String getSelectedString();
    
    
    /**
     * Returns the object corresponding to the currently
     * selected string in the view.
     *
     * @return the selected object
     * @see #getSelectedString()
     */
    Object getSelectedObject();
    
    
    /**
     * <P>Sets the view to the string provided that the
     * string is in the internal map.</P>
     *
     * <P>Does nothing if the string is <CODE>null</CODE>
     * or is not in the internal map.</P>
     *
     * <P>Does nothing if the view state will be unchanged.</P>
     *
     * @param string the string to use to set the view
     * @see #setSelectedObject(Object)
     */
    void setSelectedString(String string);
    
    
    /**
     * <P>Sets the view to the string corresponding to the
     * given object.</P>
     *
     * <P>Does nothing if the object is <CODE>null</CODE>
     * or is not in the internal map.</P>
     *
     * @param object the object to use to set the view
     * @see #setSelectedString(String)
     */
    void setSelectedObject(Object object);
    
    
    /**
     * Adds an <CODE>ActionListener</CODE>.
     *
     * @param listener the ActionListener that is to be notified
     * @see #removeActionListener(ActionListener)
     */
    void addActionListener(ActionListener listener);
    
    
    /**
     * Removes an <CODE>ActionListener</CODE>.
     *
     * @param listener the ActionListener to remove
     * @see #addActionListener(ActionListener)
     */
    void removeActionListener(ActionListener listener);
    
}