ptolemy.actor.gui

Class Effigy

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.InstantiableNamedObj

ptolemy.kernel.Entity<T>

ptolemy.kernel.ComponentEntity

ptolemy.kernel.CompositeEntity

ptolemy.actor.gui.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)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.CompositeEntity

CompositeEntity.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
StringAttribute	identifier The identifier for the effigy.
URIAttribute	uri The URI for the effigy.

Fields inherited from class ptolemy.kernel.CompositeEntity

_levelCrossingLinks

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

Constructors

Constructor and Description
Effigy(CompositeEntity container, java.lang.String name) Construct an effigy with the given name and container.
Effigy(Workspace workspace) Create a new effigy in the specified workspace with an empty string for its name.

Method Summary

Modifier and Type	Method and Description
protected void	_checkContainer(CompositeEntity container) Check that the specified container is of a suitable class for this entity, i.e., ModelDirectory or Effigy.
protected void	_removeEntity(ComponentEntity entity) Remove the specified entity from this container.
void	attributeChanged(Attribute attribute) 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.
boolean	closeTableaux() Close all tableaux contained by this effigy, and by any effigies it contains.
static Effigy	findToplevelEffigy(NamedObj object) 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.
TableauFactory	getTableauFactory() Get a tableau factory that offers views of this effigy, or null if none has been specified.
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.
boolean	isModifiable() Return whether the model data is modifiable.
boolean	isModified() Return the data associated with the master effigy (as returned by masterEffigy()) has been modified.
boolean	isSystemEffigy() Return whether this effigy is a system effigy.
Effigy	masterEffigy() Return the effigy that is "in charge" of this effigy.
int	numberOfOpenTableaux() Return the total number of open tableau for this effigy effigy and all effigies it contains.
void	setContainer(CompositeEntity container) Override the base class so that tableaux contained by this object are removed before this effigy is removed from the ModelDirectory.
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.
void	setModified(boolean modified) Record whether the data associated with this effigy has been modified since it was first read or last saved.
void	setSystemEffigy(boolean isSystemEffigy) Set the effigy to be a system effigy if the given flag is true.
void	setTableauFactory(TableauFactory factory) Specify a tableau factory that offers multiple views of this effigy.
Tableau	showTableaux() Make all tableaux associated with this effigy and any effigies it contains visible by raising or deiconifying them.
Effigy	topEffigy() Return the top-level effigy that (deeply) contains this one.
void	writeFile(java.io.File file) Write the model associated with this effigy to the specified file.

Methods inherited from class ptolemy.kernel.CompositeEntity

_addEntity, _addRelation, _adjustDeferrals, _containedDecorators, _deepOpaqueEntityList, _description, _exportMoMLContents, _finishedAddEntity, _removeRelation, _validateSettables, allAtomicEntityList, allowLevelCrossingConnect, classDefinitionList, clone, connect, connect, containedObjectsIterator, deepCompositeEntityList, deepEntityList, deepGetEntities, deepNamedObjList, deepOpaqueEntityList, deepRelationSet, entityList, entityList, exportLinks, exportMoML, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, isOpaque, lazyAllAtomicEntityList, lazyAllCompositeEntityList, lazyAllCompositeTransparentAndOpaqueEntityList, lazyClassDefinitionList, lazyDeepEntityList, lazyEntityList, lazyRelationList, newRelation, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, setClassDefinition, statistics, uniqueName

Methods inherited from class ptolemy.kernel.ComponentEntity

_checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, newPort, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_addPort, _removePort, connectedPortList, connectedPorts, connectionsChanged, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getDisplayName, getFullName, getName, getName

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.

Effigy

public Effigy(CompositeEntity container,
              java.lang.String name)
       throws IllegalActionException,
              NameDuplicationException

Construct an effigy with the given name and container.

Parameters:

container - The container.

name - The name of the effigy.

Throws:

IllegalActionException - If the entity cannot be contained by the proposed container.

NameDuplicationException - If the name coincides with an entity already in the container.

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.