Package ptolemy.actor.gui

Class Effigy

  • All Implemented Interfaces:
    java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    BrowserEffigy, DocEffigy, ExecShellEffigy, ExpressionShellEffigy, HTMLEffigy, ImageTokenEffigy, PtolemyEffigy, PythonShellEffigy, TclShellEffigy, TextEffigy, TokenEffigy
    public class Effigy
extends CompositeEntity
    An effigy represents model metadata, and is contained by the model directory or by another effigy. The effigy, for example, keeps track of where the model originated (from a URI or file) and whether the model has been modified since the URI or file was read. In design automation, such information is often called "metadata." When we began to design this class, we called it ModelModel, because it was a model of a Ptolemy II model. However, this name seemed awkward, so we changed it to Effigy. We also considered the name Proxy for the class. We rejected that name because of the common use of the word "proxy" in distributed object-oriented models.

    The Effigy class extends CompositeEntity, so an instance of Effigy can contain entities. By convention, an effigy contains all open instances of Tableau associated with the model. It also contains a string attribute named "identifier" with a value that uniquely identifies the model. A typical choice (which depends on the configuration) is the canonical URI for a MoML file that describes the model. In the case of an effigy contained by another, a typical choice is the URI of the parent effigy, a pound sign "#", and a name.

    An effigy may contain other effigies. The master effigy in such a containment hierarchy is typically associated with a URI or file. Contained effigies are associated with the same file, and represent structured data within the top-level representation in the file. The masterEffigy() method returns that master effigy. The topEffigy() method in this base class returns the same master effigy. However, in derived classes, a master effigy may be contained by another effigy, so the top effigy is not the same as the master effigy. The top effigy is directly contained by the ModelDirectory in the Configuration.

    NOTE: It might seem more natural for the identifier to match the name of the effigy rather than recording the identifier in a string attribute. But in Ptolemy II, an entity name cannot have periods in it, and a URI typically does have periods in it.

    To determine the Effigy of a NamedObj, use Configuration.findEffigy(NamedObj).

    Since:
    Ptolemy II 1.0
    Version:
    $Id$
    Author:
    Steve Neuendorffer and Edward A. Lee
    See Also:
    ModelDirectory, Tableau
    Pt.AcceptedRating:
    Yellow (celaine)
    Pt.ProposedRating:
    Green (eal)

    • Field Detail

      • identifier

        public StringAttribute identifier
        The identifier for the effigy. The default value is "Unnamed".

      • uri

        public URIAttribute uri
        The URI for the effigy. The default value is null.

    • Constructor Detail

      • Effigy

        public Effigy​(Workspace workspace)
        Create a new effigy in the specified workspace with an empty string for its name.
        Parameters:
        workspace - The workspace for this effigy.

    • Method Detail

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        If the argument is the identifier parameter, then set the title of all contained Tableaux to the value of the parameter; if the argument is the uri parameter, then check to see whether it is writable, and call setModifiable() appropriately.
        Overrides:
        attributeChanged in class NamedObj
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the base class throws it.

      • closeTableaux

        public boolean closeTableaux()
        Close all tableaux contained by this effigy, and by any effigies it contains.
        Returns:
        False if the user cancels on a save query, and true if all tableaux are successfully closed.

      • findToplevelEffigy

        public static Effigy findToplevelEffigy​(NamedObj object)
                                 throws IllegalActionException
        Find the effigy associated with the top level of the object, and if not found but the top level has a ContainmentExtender attribute, use that attribute to find the containment extender of the top level and continue the search.
        Parameters:
        object - The object.
        Returns:
        The effigy, or null if not found.
        Throws:
        IllegalActionException - If attributes cannot be retrieved, or the container that an attribute points to is invalid.

      • getTableauFactory

        public TableauFactory getTableauFactory()
        Get a tableau factory that offers views of this effigy, or null if none has been specified. The tableau factory can be used to create visual renditions of or editors for the associated model. It can be used to find out what sorts of views are available for the model.
        Returns:
        A tableau factory offering multiple views.
        See Also:
        setTableauFactory(TableauFactory)

      • getWritableFile

        public java.io.File getWritableFile()
        Return a writable file for the URI given by the uri parameter of this effigy, if there is one, or return null if there is not. This will return null if the file does not exist, or it exists and is not writable, or the uri parameter has not been set.
        Returns:
        A writable file, or null if one cannot be created.

      • isModifiable

        public boolean isModifiable()
        Return whether the model data is modifiable. This is delegated to the effigy returned by masterEffigy(). If this is the master effigy, then whether the data is modifiable depends on whether setModifiable() has been called, and if not, on whether there is a URI associated with this effigy and whether that URI is writable.
        Returns:
        False to indicate that the model is not modifiable.
        See Also:
        masterEffigy()

      • isModified

        public boolean isModified()
        Return the data associated with the master effigy (as returned by masterEffigy()) has been modified. This method is intended to be used to keep track of whether the data in the file or URI associated with this data has been modified. The method is called by an instance of TableauFrame to determine whether it is safe to close.
        Returns:
        True if the data has been modified.
        See Also:
        masterEffigy(), setModifiable(boolean)

      • isSystemEffigy

        public boolean isSystemEffigy()
        Return whether this effigy is a system effigy. System effigies are not automatically removed when they have no tableaux.
        Returns:
        True if the model is a system effigy.

      • masterEffigy

        public Effigy masterEffigy()
        Return the effigy that is "in charge" of this effigy. In this base class, this is the same as calling topEffigy(). But in derived classes, particularly PtolemyEffigy, it will be different.
        Returns:
        The effigy in charge of this effigy.
        See Also:
        topEffigy()

      • numberOfOpenTableaux

        public int numberOfOpenTableaux()
        Return the total number of open tableau for this effigy effigy and all effigies it contains.
        Returns:
        A non-negative integer giving the number of open tableaux.

      • setContainer

        public void setContainer​(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException
        Override the base class so that tableaux contained by this object are removed before this effigy is removed from the ModelDirectory. This causes the frames associated with those tableaux to be closed. Also, if the argument is null and there is a URI associated with this model, then purge any record of the model that the MoMLParser class is keeping so that future efforts to open the model result in re-parsing.
        Overrides:
        setContainer in class CompositeEntity
        Parameters:
        container - The directory in which to list this effigy.
        Throws:
        IllegalActionException - If the proposed container is not an instance of ModelDirectory, or if the superclass throws it.
        NameDuplicationException - If the container already has an entity with the specified name.
        See Also:
        ComponentEntity.getContainer()

      • setModifiable

        public void setModifiable​(boolean flag)
        If the argument is false, the specify that that the model is not modifiable, even if the URI associated with this effigy is writable. This always sets a flag in the master effigy (as returned by masterEffigy()). If the argument is true, or if this method is never called, then whether the model is modifiable is determined by whether the URI can be written to. Notice that this does not automatically result in any tableaux that are contained switching to being uneditable. But it will prevent them from writing to the URI.
        Parameters:
        flag - False to prevent writing to the URI.
        See Also:
        masterEffigy(), isModifiable(), isModified(), setModified(boolean)

      • setModified

        public void setModified​(boolean modified)
        Record whether the data associated with this effigy has been modified since it was first read or last saved. If you call this with a true argument, then subsequent calls to isModified() will return true. This is used by instances of TableauFrame. This is recorded in the entity returned by topEntity(), which is the one associated with a file. This always sets a flag in the master effigy (as returned by masterEffigy()).
        Parameters:
        modified - True if the data has been modified.
        See Also:
        masterEffigy(), isModifiable(), isModified(), setModifiable(boolean)

      • setSystemEffigy

        public void setSystemEffigy​(boolean isSystemEffigy)
        Set the effigy to be a system effigy if the given flag is true. System effigies are not removed automatically if they have no tableaux.
        Parameters:
        isSystemEffigy - True if this is to be a system effigy.

      • setTableauFactory

        public void setTableauFactory​(TableauFactory factory)
        Specify a tableau factory that offers multiple views of this effigy. This can be used by a contained tableau to set up a View menu.
        Parameters:
        factory - A tableau factory offering multiple views.
        See Also:
        getTableauFactory()

      • showTableaux

        public Tableau showTableaux()
        Make all tableaux associated with this effigy and any effigies it contains visible by raising or deiconifying them. If there is no tableau contained directly by this effigy, then create one by calling createPrimaryTableau() in the configuration.
        Returns:
        The first tableau encountered, or a new one if there are none.

      • topEffigy

        public Effigy topEffigy()
        Return the top-level effigy that (deeply) contains this one. If this effigy is contained by another effigy, then return the result of calling this method on that other effigy; otherwise, return this effigy.
        Returns:
        The top-level effigy that (deeply) contains this one.

      • writeFile

        public void writeFile​(java.io.File file)
               throws java.io.IOException
        Write the model associated with this effigy to the specified file. This base class throws an exception, since it does not know how to write model data. Derived classes should override this method to write model data.
        Parameters:
        file - The file to write to.
        Throws:
        java.io.IOException - If the write fails.

      • _checkContainer

        protected void _checkContainer​(CompositeEntity container)
                        throws IllegalActionException
        Check that the specified container is of a suitable class for this entity, i.e., ModelDirectory or Effigy.
        Parameters:
        container - The proposed container.
        Throws:
        IllegalActionException - If the container is not of an acceptable class.

      • _removeEntity

        protected void _removeEntity​(ComponentEntity entity)
        Remove the specified entity from this container. If this effigy is a system effigy and there are no remaining tableaux contained by this effigy or any effigy it contains, then remove this object from its container.
        Overrides:
        _removeEntity in class CompositeEntity
        Parameters:
        entity - The tableau to remove.