ptolemy.vergil.icon
Class EditorIcon

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.util.Attribute
          extended byptolemy.vergil.icon.EditorIcon
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable
Direct Known Subclasses:
DynamicEditorIcon, SVGIcon

public class EditorIcon
extends Attribute

An icon is the visual representation of an entity or attribute. The visual representation is a Diva Figure. This class is an attribute that serves as a factory for such figures. This base class creates the figure by composing the figures of any contained attributes that have icons. If there are no such contained attributes, then it creates a default figure that is a white rectangle. This class also provides a facility for generating a Swing icon (i.e. an instance of javax.swing.Icon) from that figure (the createIcon() method).

The icon consists of a background figure, created by the createBackgroundFigure() method, and a decorated version, created by the createFigure() method. The decorated version has, in this base class, a label showing the name of the entity, unless the entity contains an attribute called "_hideName". The swing icon created by createIcon() does not include the decorations, but rather is only the background figure.

Derived classes may simply populate this attribute with other visible attributes (attributes that contain icons), or they can override the createBackgroundFigure() method. This will affect both the Diva Figure and the Swing Icon representations. Derived classes can also create the figure or the icon in a different way entirely (for example, starting with a Swing icon and creating the figure using a SwingWrapper) by overriding both createBackgroundFigure() and createIcon(). However, the icon editor provided by EditIconFrame and EditIconTableau will only show (and allow editing) of those icon components created by populating this attribute with other visible attributes.

This attribute contains another attribute that is an instance of EditIconTableau. This has the effect that an instance of Configuration, when it attempts to open an instance of this class, will use EditIconTableau, which in turn uses EditIconFrame to provide an icon editor.

Since:
Ptolemy II 2.0
Version:
$Id: EditorIcon.java,v 1.33.2.1 2004/06/18 00:49:30 cxh Exp $
Author:
Steve Neuendorffer, John Reekie, Edward A. Lee
See Also:
EditIconFrame, EditIconTableau, Configuration, Serialized Form
Accepted Rating:
Red (johnr)
Proposed Rating:
Yellow (neuendor)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Field Summary
protected  NamedObj _containerToBe
          The container to be eventually the container for this icon.
protected  javax.swing.Icon _iconCache
          The cached Swing icon.
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Constructor Summary
EditorIcon(NamedObj container, java.lang.String name)
          Create a new icon with the given name in the given container.
EditorIcon(Workspace workspace, java.lang.String name)
          Construct an icon in the specified workspace and name.
 
Method Summary
protected  Figure _createDefaultBackgroundFigure()
          Create a new default background figure, which is a white box.
protected  void _recreateFigure()
          Recreate the figure.
 java.lang.Object clone(Workspace workspace)
          Clone the object into the specified workspace.
 Figure createBackgroundFigure()
          Create a new background figure.
 Figure createFigure()
          Create a new Diva figure that visually represents this icon.
 javax.swing.Icon createIcon()
          Create a new Swing icon.
 void exportMoML(java.io.Writer output, int depth, java.lang.String name)
          Write a MoML description of this object.
 Nameable getContainerOrContainerToBe()
          Return the container of this object, if there is one, or if not, the container specified by setContainerToBe(), if there is one, or if not, null.
 void setContainerToBe(NamedObj container)
          Indicate that the container of this icon will eventually be the specified object.
 
Methods inherited from class ptolemy.kernel.util.Attribute
_getContainedObject, _propagateExistence, getContainer, setContainer, setName
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _description, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, uniqueName, validateSettables, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_containerToBe

protected NamedObj _containerToBe
The container to be eventually the container for this icon.


_iconCache

protected javax.swing.Icon _iconCache
The cached Swing icon.

Constructor Detail

EditorIcon

public EditorIcon(Workspace workspace,
                  java.lang.String name)
           throws IllegalActionException
Construct an icon in the specified workspace and name. This constructor is typically used in conjunction with setContainerToBe() and createFigure() to create an icon and generate a figure without having to have write access to the workspace. If the workspace argument is null, then use the default workspace. The object is added to the directory of the workspace.

Parameters:
workspace - The workspace that will list the attribute.
Throws:
IllegalActionException - If the specified name contains a period.
See Also:
Increment the version number of the workspace.

EditorIcon

public EditorIcon(NamedObj container,
                  java.lang.String name)
           throws IllegalActionException,
                  NameDuplicationException
Create a new icon with the given name in the given container.

Parameters:
container - The container.
name - The name of the attribute.
Throws:
IllegalActionException - If the attribute is not of an acceptable class for the container.
NameDuplicationException - If the name coincides with an attribute already in the container.
Method Detail

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is an object with no container.

Overrides:
clone in class Attribute
Parameters:
workspace - The workspace for the cloned object.
Returns:
The new Attribute.
Throws:
java.lang.CloneNotSupportedException - Not thrown in this base class

createBackgroundFigure

public Figure createBackgroundFigure()
Create a new background figure. This figure is a composition of the figures of any contained visible attributes. If there are no such visible attributes, then this figure is a simple white box. If you override this method, keep in mind that this method is expected to manufacture a new figure each time, since figures are inexpensive and contain their own location and transformations. This method should never return null.

Returns:
A new figure.

createFigure

public Figure createFigure()
Create a new Diva figure that visually represents this icon. The figure will be an instance of CompositeFigure with the figure returned by createBackgroundFigure() as its background. This method adds a LabelFigure to the CompositeFigure that contains the name of the container of this icon, unless the container has an attribute called "_hideName". If the container has an attribute called "_centerName", then the name is rendered in the center of the background figure, rather than above it. This method should never return null, even if the icon has not been properly initialized.

Returns:
A new CompositeFigure consisting of the background figure and a label.

createIcon

public javax.swing.Icon createIcon()
Create a new Swing icon. In this base class, this icon is created from the background figure returned by createBackgroundFigure(). Note that the background figure does NOT include a label for the name. This method might be suitable, for example, for creating a small icon for use in a library.

Returns:
A new Swing Icon.

exportMoML

public void exportMoML(java.io.Writer output,
                       int depth,
                       java.lang.String name)
                throws java.io.IOException
Write a MoML description of this object. MoML is an XML modeling markup language. In this class, the object is identified by the "property" element, with "name", "class", and "value" (XML) attributes. The body of the element, between the "<property>" and "</property>", is written using the _exportMoMLContents() protected method, so that derived classes can override that method alone to alter only how the contents of this object are described. The text that is written is indented according to the specified depth, with each line (including the last one) terminated with a newline. If this object is not persistent, then write nothing.

Specified by:
exportMoML in interface MoMLExportable
Overrides:
exportMoML in class NamedObj
Parameters:
output - The output stream to write to.
depth - The depth in the hierarchy, to determine indenting.
name - The name to use instead of the current name.
Throws:
java.io.IOException - If an I/O error occurs.
See Also:
MoMLExportable, NamedObj.clone(Workspace), NamedObj.isPersistent(), NamedObj.getDerivedLevel()

getContainerOrContainerToBe

public Nameable getContainerOrContainerToBe()
Return the container of this object, if there is one, or if not, the container specified by setContainerToBe(), if there is one, or if not, null. This rather specialized method is used to create an icon and generate a figure without having to have write access to the workspace. To use it, use the constructor that takes a workspace and a name, then call setContainerToBe() to indicate what the container will be. You can then call createFigure() or createBackgroundFigure(), and the appropriate figure for the container specified here will be used. Then queue a ChangeRequest that sets the container to the same specified container. Once the container has been set by calling setContainer(), then the object specified to this method is no longer relevant.

See Also:
setContainerToBe(NamedObj)

setContainerToBe

public void setContainerToBe(NamedObj container)
Indicate that the container of this icon will eventually be the specified object. This rather specialized method is used to create an icon and generate a figure without having to have write access to the workspace. To use it, use the constructor that takes a workspace and a name, then call this method to indicate what the container will be. You can then call createFigure() or createBackgroundFigure(), and the appropriate figure for the container specified here will be used. Then queue a ChangeRequest that sets the container to the same specified container. Once the container has been set by calling setContainer(), then the object specified to this method is no longer relevant.

Parameters:
container - The container that will eventually be set.
See Also:
getContainerOrContainerToBe()

_createDefaultBackgroundFigure

protected Figure _createDefaultBackgroundFigure()
Create a new default background figure, which is a white box. Subclasses of this class should generally override the createBackgroundFigure method instead. This method is provided so that subclasses are always able to create a default figure even if an error occurs or the subclass has not been properly initialized.

Returns:
A figure representing a rectangular white box.

_recreateFigure

protected void _recreateFigure()
Recreate the figure. Call this to cause createIcon() to call createBackgroundFigure() to obtain a new figure.