/*
 * @(#)TypedView.java    2.3  15 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.*;

/**
 * <P>Interface to be implemented by a class of interface objects
 * whose data state is appropriate for input 
 * of a particular class of model objects.  
 *
 * Certain classes that implement this interface should also
 * implement the <CODE>{@link Fragile Fragile}</CODE> interface, 
 * but this is not a requirement.</P>
 *
 * @author  Jeff Raab
 * @author  Richard Rasala
 * @version 2.3
 * @since   1.0
 * @see GeneralView
 */
public interface TypedView extends Displayable {
    
    /** 
     * Bound property name for the <CODE>Stringable</CODE> type returned
     * by a typed view or general view.
     */
    public static final String DATA_TYPE = "data.type";

    
    /**
     * Returns the current class of objects returned when a model object
     * is demanded or requested.
     *
     * @return the current class of a model object
     */    
    Class getDataType();
       

    /**
     * Returns a <CODE>Stringable</CODE> object based on the view state
     * of the view using the mandatory model.
     *
     * @return a <CODE>Stringable</CODE> model object
     * @see    #requestObject()
     */
    Stringable demandObject();
    
    
    /**
     * Returns a <CODE>Stringable</CODE> object based on the view state
     * of the view using the optional model; throws an exception if the
     * input operation is cancelled by the user.
     *
     * @return a <CODE>Stringable</CODE> model object
     * @throws <CODE>CancelledException</CODE> if the user cancelled
     *         after an error was detected
     * @see #demandObject()
     */
    Stringable requestObject() throws CancelledException;
    
    
    /**
     * <P>Sets the input properties for this view to the provided input
     * properties.</P>
     *
     * <P>If the given input properties list is <CODE>null</CODE>, the
     * property list for this view is set to the base property list
     * containing default property values.</P>
     *
     * @param properties the new input properties for the view
     * @see #getInputProperties()
     */
    void setInputProperties(InputProperties properties);
    
    
    /**
     * Returns the input properties for this view.
     *
     * @return the input properties
     * @see #setInputProperties(InputProperties)
     */
    InputProperties getInputProperties();
    
}