001/* Interface for implementing platform dependent parts of the display actor.
002
003 @Copyright (c) 1998-2014 The Regents of the University of California.
004 All rights reserved.
005
006 Permission is hereby granted, without written agreement and without
007 license or royalty fees, to use, copy, modify, and distribute this
008 software and its documentation for any purpose, provided that the
009 above copyright notice and the following two paragraphs appear in all
010 copies of this software.
011
012 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
013 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
014 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
015 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
016 SUCH DAMAGE.
017
018 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
019 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
021 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
022 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
023 ENHANCEMENTS, OR MODIFICATIONS.
024
025 PT_COPYRIGHT_VERSION 2
026 COPYRIGHTENDKEY
027 */
028package ptolemy.actor.lib.gui;
029
030import ptolemy.actor.injection.PortableContainer;
031import ptolemy.kernel.util.IllegalActionException;
032import ptolemy.kernel.util.NameDuplicationException;
033
034///////////////////////////////////////////////////////////////////
035////DisplayInterface
036
037/**
038 Interface for implementing platform dependent parts of the display actor.
039
040@author Ishwinder Singh
041@version $Id$
042@since Ptolemy II 10.0
043@Pt.ProposedRating Yellow (ishwinde)
044@Pt.AcceptedRating Yellow (ishwinde)
045 */
046public interface DisplayInterface {
047
048    /** Free up memory when closing. */
049    public void cleanUp();
050
051    /** Append the string value of the token to the text area
052     *  on the screen.  Each value is terminated with a newline
053     *  character.
054     *  @param tokenValue The string to be displayed
055     */
056    public void display(String tokenValue);
057
058    /** Return the object of the containing text area.
059     *  @return the text area.
060     */
061    public Object getTextArea();
062
063    /** Set the number of rows for the text area.
064     * @param display Object of the display actor.
065     * @exception IllegalActionException If the entity cannot be contained
066     * by the proposed container.
067     * @exception NameDuplicationException If the container already has an
068     * actor with this name.
069     */
070    public void init(Display display)
071            throws IllegalActionException, NameDuplicationException;
072
073    /** Open the display window if it has not been opened.
074     *  @exception IllegalActionException If there is a problem creating
075     *  the effigy and tableau.
076     */
077    public void openWindow() throws IllegalActionException;
078
079    /** Specify the container in which the data should be displayed.
080     *  An instance of JTextArea will be added to that container.
081     *  This method needs to be called before the first call to initialize().
082     *  Otherwise, an instance of JTextArea will be placed in its own frame.
083     *  The text area is also placed in its own frame if this method
084     *  is called with a null argument.
085     *  The background of the text area is set equal to that of the container
086     *  (unless it is null).
087     *
088     *  @param container The container into which to place the text area, or
089     *   null to specify that there is no current container.
090     */
091    public void place(PortableContainer container);
092
093    /** Remove the display from the current container, if there is one.
094     */
095    public void remove();
096
097    /** Set the desired number of columns of the textArea, if there is one.
098     *
099     *  @param numberOfColumns The new value of the attribute.
100     *  @exception IllegalActionException If the specified attribute
101     *   is <i>rowsDisplayed</i> and its value is not positive.
102     */
103    public void setColumns(int numberOfColumns) throws IllegalActionException;
104
105    /** Set the desired number of rows of the textArea, if there is one.
106     *
107     *  @param numberOfRows The new value of the attribute.
108     *  @exception IllegalActionException If the specified attribute
109     *   is <i>rowsDisplayed</i> and its value is not positive.
110     */
111    public void setRows(int numberOfRows) throws IllegalActionException;
112
113    /** Set the title of the window.
114     *
115     *  <p>If the <i>title</i> parameter is set to the empty string,
116     *  and the Display window has been rendered, then the title of
117     *  the Display window will be updated to the value of the name
118     *  parameter.</p>
119     *
120     * @param stringValue The title to be set.
121     * @exception IllegalActionException If the title cannot be set.
122     */
123    public void setTitle(String stringValue) throws IllegalActionException;
124}