/*
 * @(#)GeneralView.java    2.3  3 December 2003
 *
 * Copyright 2004
 * 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.*;
import edu.neu.ccs.filter.*;

import java.awt.event.*;

/**
 * <P>Interface to be implemented by a class of interface objects whose
 * view state may be appropriate for input of various classes of model
 * objects.</P>
 *
 * <P>Most classes that implement this interface should also implement
 * the <CODE>{@link Fragile Fragile}</CODE> interface, but this is not
 * a requirement.</P>
 *
 * <P>It is expected that a <CODE>GeneralView</CODE> will extend
 * <CODE>JComponent</CODE> so that it may installed in a GUI and
 * so that it may fire property change events.  This requirement
 * is stronger than that for <CODE>Displayable</CODE>.</P>
 *
 * <P>A <CODE>GeneralView</CODE> is a powerful and general input
 * component that must be capable of instantiating any
 * <CODE>Stringable</CODE> class of objects.
 *
 * <P>A class of input component that can only instantiate a single
 * class of <CODE>Stringable</CODE> objects should implement the
 * base <CODE>TypedView</CODE> interface.</P>
 *
 * @author  Jeff Raab
 * @author  Richard Rasala
 * @version 2.3
 * @since   1.0
 * @see Fragile
 */
public interface GeneralView extends TypedView {
    
    /**
     * Sets the current class of objects returned when a model object is
     * demanded or requested.
     *
     * @param  dataType the new class of objects for model objects
     * @throws Error if the given data type is not assignable from
     *         the <CODE>Stringable</CODE> reference type
     */    
    void setDataType(Class dataType);
    
    
    /**
     * <P>Returns a copy of this <CODE>GeneralView</CODE>.</P>
     *
     * <P>The purpose of this method is to provide a copy of the view
     * that may be used in error handling dialogs.  The copy should,
     * as far as possible, have the same screen size and internal
     * settings.  Each <CODE>GeneralView</CODE> should describe what
     * its <CODE>makeCopy</CODE> method actually does.</P>
     *
     * <P>The copy should NOT share its internal document model with
     * the original view.  This will allow the copy to operate in an
     * independent fashion from the original.</P>
     *
     * @return a copy of this view
     */
    GeneralView makeCopy();
    
    
    /**
     * Sets the current filter used by the view to the given StringableFilter.
     *
     * @param filter the filter to be used
     */
    void setFilter(StringableFilter filter);
    
    
    /**
     * Returns the current filter used by this view.
     *
     * @return the current filter
     */
    StringableFilter getFilter();
    
    
    /**
     * Returns a <CODE>Stringable</CODE> object based on the view state
     * of the view, the temporary filter, and the mandatory model.
     *
     * @param  filter the temporary filter to use
     * @return a <CODE>Stringable</CODE> model object
     * @see    #demandObject()
     * @see    #requestObject(Class, StringableFilter)
     */
    Stringable demandObject(StringableFilter filter);
    
    
    /**
     * Returns a <CODE>Stringable</CODE> object based on the view state
     * of the view, the temporary filter, and the optional model.
     *
     * @param  filter the temporary filter to use
     * @return a <CODE>Stringable</CODE> model object
     * @see    #requestObject()
     * @see    #demandObject(Class, StringableFilter)
     * @throws <CODE>CancelledException</CODE> if the user cancelled
     *         after an error was detected
     */
    Stringable requestObject(StringableFilter filter)
        throws CancelledException;
    
    
    /**
     * Returns a <CODE>Stringable</CODE> object based on the view state
     * of the view, the temporary data type and filter, and the mandatory
     * model.
     *
     * @return a <CODE>Stringable</CODE> model object
     * @see    #demandObject()
     * @see    #requestObject(Class, StringableFilter)
     */
    Stringable demandObject(Class dataType, StringableFilter filter);
    
    
    /**
     * Returns a <CODE>Stringable</CODE> object based on the view state
     * of the view, the temporary data type and filter, and the optional
     * model.
     *
     * @return a <CODE>Stringable</CODE> model object
     * @see    #requestObject()
     * @see    #demandObject(Class, StringableFilter)
     * @throws <CODE>CancelledException</CODE> if the user cancelled
     *         after an error was detected
     */
    Stringable requestObject(Class dataType, StringableFilter filter)
        throws CancelledException;
    
    
    /**
     * Sets the three input property <CODE>String</CODE>s for an error
     * dialog in a single method.
     *
     * @param  errorPrompt the error prompt of an error dialog
     * @param  dialogTitle the dialog title of an error dialog
     * @param  suggestion the suggestion for an error dialog
     */
    void setErrorPromptTitleSuggestion(
        String errorPrompt,
        String dialogTitle,
        String suggestion );
    
    
    /**
     * 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);
    
}