ptolemy.vergil.icon

Class EditorIcon

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.vergil.icon.EditorIcon

All Implemented Interfaces:

java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, IconAttribute, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

DynamicEditorIcon, NameIcon, SVGIcon, TransformationAttributeIcon

public class EditorIcon
extends Attribute
implements IconAttribute

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 a parameter called "_hideName" with value true. The swing icon created by createIcon() does not include the decorations, but rather is only the background figure.

The decorated version can also optionally show parameter values below the icon. If the preference named "_showParameters" has value "All", then all parameters are shown. If it has value "Overridden parameters only", then it will show only overridden parameters. In either case, only parameters that are visible and settable (see the Settable interface) will be shown, regardless of whether they are overridden.

When the preference "_showParameters" has value "Overridden parameters only", then some parameter values may be suppressed even if they are overridden. In particular, if an attribute contains a parameter named "_hide" with value true, then that parameter is not shown even if requested. If the container of the attribute contains a parameter named "_hideAllParameters" with value true, then none of its parameters are shown. This is useful, for example, if the icon itself shows the parameter, as with decorative visual elements.

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$

Author:

Steve Neuendorffer, John Reekie, Edward A. Lee

See Also:

EditIconFrame, EditIconTableau, Configuration

Pt.AcceptedRating:

Red (johnr)

Pt.ProposedRating:

Yellow (neuendor)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
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, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
protected Figure	_createDefaultBackgroundFigure() Create a new default background figure, which is a white box.
protected boolean	_isPropertySet(NamedObj object, java.lang.String name) Return true if the property of the specified name is set for the specified object.
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.
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

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setContainer, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _description, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeChanged, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, 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.

name - The name of this 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

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

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 a parameter called "_hideName" with value true. If the container has an attribute called "_centerName" with value true, 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.

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.

Returns:

The container of this object, if there is one, or if not hte container specified by setContainerToBe().

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.

_isPropertySet

protected boolean _isPropertySet(NamedObj object,
                                 java.lang.String name)

Return true if the property of the specified name is set for the specified object. A property is specified if the specified object contains an attribute with the specified name and that attribute is either not a boolean-valued parameter, or it is a boolean-valued parameter with value true.

Parameters:

object - The object.

name - The property name.

Returns:

True if the property is set.

_recreateFigure

protected void _recreateFigure()

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