Package ptolemy.vergil.icon

Class 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)

    • 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.

    • 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.