Package ptolemy.vergil.icon

Class DynamicEditorIcon

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.vergil.icon.EditorIcon

ptolemy.vergil.icon.DynamicEditorIcon

All Implemented Interfaces:

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

Direct Known Subclasses:

ImageIcon, PDFIcon, ShapeIcon, TableIcon, TextIcon, XMLIcon

public class DynamicEditorIcon
extends EditorIcon

An icon that provides for the possibility that figures may be dynamically updated. While some icons are generally 'static' and it is simplest to regenerate new figures when their attributes change, other icons are more 'dynamic'. For instance, some icons might display live video or a live plot. This icon provides some basic infrastructure for dealing with such cases. The main difficulty is that, by design, an icon cannot keep track of the figures it creates, otherwise there is a possibility for memory leaks or inconsistencies in the case of multiple views. This class solves the problem by using a WeakReferences to keep track of generated figures. These references do not prevent objects from being garbage collected. This class also provides a 'safe' iterator that can be used to traverse the weak references without the normal associated nastiness.

Since:

Ptolemy II 4.0

Version:

$Id$

Author:

Steve Neuendorffer

Pt.AcceptedRating:

Red (johnr)

Pt.ProposedRating:

Yellow (eal)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field	Description
protected java.util.List	_figures	A list of weak references to figures that this has created.

Fields inherited from class ptolemy.vergil.icon.EditorIcon

_containerToBe, _iconCache

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	Description
DynamicEditorIcon(NamedObj container, java.lang.String name)	Create a new icon with the given name in the given container.
DynamicEditorIcon(Workspace workspace, java.lang.String name)	Construct an icon in the specified workspace and name.

Method Summary

Modifier and Type	Method	Description
protected void	_addLiveFigure(Figure newFigure)	Add the figure to the list of figures managed by this icon.
protected java.util.Iterator	_liveFigureIterator()	Return a regular iterator over the figures created by this icon which have not been garbage collected.
protected void	_trimLiveFigures()	Trim the list of figures to discard entries that are no longer live.
java.lang.Object	clone(Workspace workspace)	Clone the object into the specified workspace.

Methods inherited from class ptolemy.vergil.icon.EditorIcon

_createDefaultBackgroundFigure, _isPropertySet, _recreateFigure, createBackgroundFigure, createFigure, createIcon, getContainerOrContainerToBe, setContainerToBe

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

_figures

protected java.util.List _figures

A list of weak references to figures that this has created.

Constructor Detail

DynamicEditorIcon

public DynamicEditorIcon(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.

DynamicEditorIcon

public DynamicEditorIcon(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 EditorIcon

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)

_addLiveFigure

protected void _addLiveFigure(Figure newFigure)

Add the figure to the list of figures managed by this icon. A WeakReference object will be created that points to the figure which will not prevent it from being garbage collected. This method should be called in the createBackgroundFigure method with the figure that will be returned.

Parameters:

newFigure - A newly manufactured figure.

_liveFigureIterator

protected java.util.Iterator _liveFigureIterator()

Return a regular iterator over the figures created by this icon which have not been garbage collected. The objects returned by the iterator are Figures, not WeakReferences. Furthermore, the objects returned by this iterator are guaranteed to not be null.

Returns:

an iterator.

_trimLiveFigures

protected void _trimLiveFigures()

Trim the list of figures to discard entries that are no longer live.