ptolemy.actor.lib.gui
Class PlotterBase

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.gui.PlotterBase

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Placeable, Initializable, TypedActor, Changeable, Configurable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

HistogramPlotter, Plotter

public class PlotterBase
extends TypedAtomicActor
implements Configurable, Placeable

Base class for plotters. This class contains an instance of the PlotBox class from the Ptolemy plot package as a public member, although which subclass of PlotBox is created is left to derived classes. It provides a parameter that determines whether to fill the plot when wrapup is invoked. It also has a legend parameter, which gives a comma-separated list of labels to attach to each dataset. Normally, the number of elements in this list should equal the number of input channels, although this is not enforced.

Since:

Ptolemy II 2.1

Version:

$Id: PlotterBase.java 57046 2010-01-27 23:35:53Z cxh $

Author:

Edward A. Lee

See Also:

PlotBox, Serialized Form

Accepted Rating:

Green (cxh)

Proposed Rating:

Green (eal)

Nested Class Summary

protected class

PlotterBase.PlotWindowTableau Tableau that creates a PlotterPlotFrame.

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

Entity.ContainedObjectsIterator

Field Summary

protected java.net.URL	_base The base specified in configure().
private java.util.List<java.net.URL>	_configureBases
private java.lang.String	_configureSource
private java.util.List<java.lang.String>	_configureSources
private java.util.List<java.lang.String>	_configureTexts
protected java.awt.Container	_container Container into which this plot should be placed.
protected PlotTableauFrame	_frame Frame into which plot is placed, if any.
protected SizeAttribute	_plotSize A specification of the size of the plot if it's in its own window.
protected java.lang.String	_source The source specified in configure().
protected PlotterBase.PlotWindowTableau	_tableau The version of PlotWindowTableau that creates a Plot window.
protected java.lang.String	_text The text specified in configure().
protected WindowPropertiesAttribute	_windowProperties A specification for the window properties of the frame.
Parameter	automaticRescale If true, the plot will automatically rescale if necessary.
Parameter	fillOnWrapup If true, fill the plot when wrapup is called.
StringAttribute	legend A comma-separated list of labels to attach to each data set.
PlotBox	plot The plot object.

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

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

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

PlotterBase(CompositeEntity container, java.lang.String name)
Construct an actor with the given container and name.

Method Summary

protected void	_exportMoMLContents(java.io.Writer output, int depth) Write a MoML description of the contents of this object, which in this class is the configuration information.
protected void	_implementDeferredConfigurations() If configurations have been deferred, implement them now.
protected PlotBox	_newPlot() Create a new plot.
protected void	_propagateValue(NamedObj destination) Propagate the value of this object to the specified object.
private void	_remove() Remove the plot from the current container, if there is one.
void	attributeChanged(Attribute attribute) If the attribute is legend, then parse the string and set the legend.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	configure(java.net.URL base, java.lang.String source, java.lang.String text) Configure the object with data from the specified input source (a URL) and/or textual data, assumed to be in PlotML format.
java.lang.String	getConfigureSource() Return the input source that was specified the last time the configure method was called.
java.lang.String	getConfigureText() Return the text string that represents the current configuration of this object.
void	place(java.awt.Container container) Specify the container into which this plot should be placed.
void	preinitialize() Clear the plot, if there is one.
void	setContainer(CompositeEntity container) Override the base class to remove the plot from its graphical container if the argument is null.
void	setDisplayName(java.lang.String name) Set a name to present to the user.
void	setName(java.lang.String name) Set or change the name.
void	wrapup() If the fillOnWrapup parameter is true, rescale the plot so that all the data is visible.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, fire, getCausalityInterface, getDirector, getExecutiveDirector, getManager, initialize, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, postfire, prefire, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, stop, stopFire, terminate

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence

Methods inherited from class ptolemy.kernel.Entity

_description, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

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

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, 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, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, 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.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

fire, isFireFunctional, isStrict, iterate, postfire, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, removeInitializable

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

automaticRescale

public Parameter automaticRescale

If true, the plot will automatically rescale if necessary. This parameter has type BooleanToken, and default value false.

plot

public transient PlotBox plot

The plot object.

fillOnWrapup

public Parameter fillOnWrapup

If true, fill the plot when wrapup is called. This parameter has type BooleanToken, and default value true.

legend

public StringAttribute legend

A comma-separated list of labels to attach to each data set. This is always a string, with no enclosing quotation marks.

_base

protected java.net.URL _base

The base specified in configure().

_container

protected java.awt.Container _container

Container into which this plot should be placed.

_frame

protected transient PlotTableauFrame _frame

Frame into which plot is placed, if any.

_plotSize

protected SizeAttribute _plotSize

A specification of the size of the plot if it's in its own window.

_source

protected java.lang.String _source

The source specified in configure().

_tableau

protected PlotterBase.PlotWindowTableau _tableau

The version of PlotWindowTableau that creates a Plot window.

_text

protected java.lang.String _text

The text specified in configure().

_windowProperties

protected WindowPropertiesAttribute _windowProperties

A specification for the window properties of the frame.

_configureBases

private java.util.List<java.net.URL> _configureBases

_configureSources

private java.util.List<java.lang.String> _configureSources

_configureTexts

private java.util.List<java.lang.String> _configureTexts

_configureSource

private java.lang.String _configureSource

Constructor Detail

PlotterBase

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

Construct an actor with the given container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

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

NameDuplicationException - If the container already has an actor with this name.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the attribute is legend, then parse the string and set the legend.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the superclass throws it.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the actor into the specified workspace. This calls the base class and then creates new ports and parameters.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class has an attribute that cannot be cloned.

See Also:

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

configure

public void configure(java.net.URL base,
                      java.lang.String source,
                      java.lang.String text)
               throws java.lang.Exception

Configure the object with data from the specified input source (a URL) and/or textual data, assumed to be in PlotML format. If this is called before the plotter has been created (by calling place() or initialize()), then the configuration is deferred until the plotter is created.

Specified by:

configure in interface Configurable

Parameters:

base - The base relative to which references within the input are found, or null if this is not known, or there is none.

source - The input source, which specifies a URL.

text - Configuration information given as text.

Throws:

java.lang.Exception - If the configuration source cannot be read or if the configuration information is incorrect.

getConfigureSource

public java.lang.String getConfigureSource()

Return the input source that was specified the last time the configure method was called.

Specified by:

getConfigureSource in interface Configurable

Returns:

The string representation of the input URL.

getConfigureText

public java.lang.String getConfigureText()

Return the text string that represents the current configuration of this object. Note that any configuration that was previously specified using the source attribute need not be returned here. This returns a null string if there is no associated plot.

Specified by:

getConfigureText in interface Configurable

Returns:

The text string that represent the current configuration.

place

public void place(java.awt.Container container)

Specify the container into which this plot should be placed. This method needs to be called before the first call to initialize(). Otherwise, the plot will be placed in its own frame. The size of the plot, unfortunately, cannot be effectively determined from the size of the container because the container may not yet be laid out (its size will be zero). Thus, you will have to explicitly set the size of the plot by calling plot.setSize(). The background of the plot is set equal to that of the container (unless it is null).

If configure() has been called (prior to the plot getting created), then the configurations that it specified have been deferred. Those configurations are performed at this time.

Specified by:

place in interface Placeable

Parameters:

container - The container into which to place the plot, or null to specify that a new plot should be created.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Clear the plot, if there is one. Notice that unlike initialize(), this clears the entire plot.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If the parent class throws it.

See Also:

AtomicActor.initialize()

setContainer

public void setContainer(CompositeEntity container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class to remove the plot from its graphical container if the argument is null.

Overrides:

setContainer in class AtomicActor

Parameters:

container - The proposed container.

Throws:

IllegalActionException - If the base class throws it.

NameDuplicationException - If the base class throws it.

See Also:

ComponentEntity.getContainer()

setDisplayName

public void setDisplayName(java.lang.String name)

Set a name to present to the user.

If the Plot window has been rendered, then the title of the Plot window will be updated to the value of the name parameter.

Overrides:

setDisplayName in class NamedObj

Parameters:

name - A name to present to the user.

See Also:

NamedObj.getDisplayName()

setName

public void setName(java.lang.String name)
             throws IllegalActionException,
                    NameDuplicationException

Set or change the name. If a null argument is given the name is set to an empty string. Increment the version of the workspace. This method is write-synchronized on the workspace.

If the Plot window has been rendered, then the title of the Plot window will be updated to the value of the name parameter.

Specified by:

setName in interface Nameable

Overrides:

setName in class ComponentEntity

Parameters:

name - The new name.

Throws:

IllegalActionException - If the name contains a period or if the object is a derived object and the name argument does not match the current name.

NameDuplicationException - Not thrown in this base class. May be thrown by derived classes if the container already contains an object with this name.

See Also:

NamedObj.getName(), NamedObj.getName(NamedObj)

wrapup

public void wrapup()
            throws IllegalActionException

If the fillOnWrapup parameter is true, rescale the plot so that all the data is visible.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - If the superclass throws it.

_exportMoMLContents

protected void _exportMoMLContents(java.io.Writer output,
                                   int depth)
                            throws java.io.IOException

Write a MoML description of the contents of this object, which in this class is the configuration information. This method is called by exportMoML(). Each description is indented according to the specified depth and terminated with a newline character.

Overrides:

_exportMoMLContents in class Entity

Parameters:

output - The output stream to write to.

depth - The depth in the hierarchy, to determine indenting.

Throws:

java.io.IOException - If an I/O error occurs.

See Also:

NamedObj.exportMoML(Writer, int)

_implementDeferredConfigurations

protected void _implementDeferredConfigurations()

If configurations have been deferred, implement them now. Also, configure the plot legends, if appropriate.

_newPlot

protected PlotBox _newPlot()

Create a new plot. In this base class, it is an instance of Plot. In derived classes, it can be classes derived from Plot.

Returns:

A new plot object.

_propagateValue

protected void _propagateValue(NamedObj destination)
                        throws IllegalActionException

Propagate the value of this object to the specified object. The specified object is required to be an instance of the same class as this one, or a ClassCastException will be thrown.

Overrides:

_propagateValue in class NamedObj

Parameters:

destination - Object to which to propagate the value.

Throws:

IllegalActionException - If the value cannot be propagated.

_remove

private void _remove()

Remove the plot from the current container, if there is one.