ptolemy.kernel.util
Class Location

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.kernel.util.SingletonAttribute
              ptolemy.kernel.util.Location

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Changeable, Debuggable, DebugListener, Derivable, Locatable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, Settable, Singleton

Direct Known Subclasses:

Vertex

public class Location
extends SingletonAttribute
implements Locatable

An attribute that represents a location of a node in a schematic.

By default, an instance of this class is not visible in a user interface. This is indicated to the user interface by returning NONE to the getVisibility() method. The location is specified by calling setExpression() with a string that has the form "x,y" or "[x,y]" or "{x,y}", where x and y can be parsed into doubles.

The default location is a two dimensional location with value {0.0, 0.0}. This class can also handle locations with greater than two dimensions.

Since:

Ptolemy II 2.1

Version:

$Id: Location.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Steve Neuendorffer and Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Green (cxh)

Proposed Rating:

Green (cxh)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Nested classes/interfaces inherited from interface ptolemy.kernel.util.Settable

Settable.Visibility

Field Summary

private java.lang.String	_default
private java.lang.String	_expression
private boolean	_expressionSet
private double[]	_location
private java.util.List	_valueListeners
private Settable.Visibility	_visibility

Fields inherited from class ptolemy.kernel.util.NamedObj

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

Fields inherited from interface ptolemy.kernel.util.Settable

EXPERT, FULL, NONE, NOT_EDITABLE

Constructor Summary

Location(NamedObj container, java.lang.String name)
Construct an attribute with the given container and name.

Location(Workspace workspace)
Construct an attribute in the specified workspace with an empty string as a name.

Method Summary

protected void	_propagateValue(NamedObj destination) Propagate the value of this object to the specified object.
private boolean	_setLocation(double[] location) Set the location without altering the modified status.
void	addValueListener(ValueListener listener) Add a listener to be notified when the value of this attribute changes.
java.lang.Object	clone(Workspace workspace) Clone the location into the specified workspace.
void	exportMoML(java.io.Writer output, int depth, java.lang.String name) Write a MoML description of this object.
java.lang.String	getDefaultExpression() Return the default value of this Settable, if there is one.
java.lang.String	getDisplayName() Return a name to present to the user, which is the same as the name returned by getName().
java.lang.String	getExpression() Get the value that has been set by setExpression() or by setLocation(), whichever was most recently called, or return an empty string if neither has been called.
double[]	getLocation() Get the location in some cartesian coordinate system.
java.lang.String	getValueAsString() Get the value of the attribute, which is the evaluated expression.
Settable.Visibility	getVisibility() Get the visibility of this attribute, as set by setVisibility().
void	removeValueListener(ValueListener listener) Remove a listener from the list of listeners that is notified when the value of this variable changes.
void	setExpression(java.lang.String expression) Set the value of the attribute by giving some expression.
void	setLocation(double[] location) Set the location in some cartesian coordinate system, and notify the container and any value listeners of the new location.
void	setVisibility(Settable.Visibility visibility) Set the visibility of this attribute.
java.lang.String	toString() Get a description of the class, which is the class name and the location in parentheses.
java.util.Collection	validate() Parse the location specification given by setExpression(), if there has been one, and otherwise set the location to 0.0, 0.0.

Methods inherited from class ptolemy.kernel.util.SingletonAttribute

setContainer

Methods inherited from class ptolemy.kernel.util.Attribute

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

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _description, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getFullName, getName, getName, setName

Field Detail

_default

private java.lang.String _default

_expression

private java.lang.String _expression

_expressionSet

private boolean _expressionSet

_location

private double[] _location

_valueListeners

private java.util.List _valueListeners

_visibility

private Settable.Visibility _visibility

Constructor Detail

Location

public Location(Workspace workspace)

Construct an attribute in the specified workspace with an empty string as a name. If the workspace argument is null, then use the default workspace. The object is added to the directory of the workspace. Increment the version number of the workspace.

Parameters:

workspace - The workspace that will list the attribute.

Location

public Location(NamedObj container,
                java.lang.String name)
         throws IllegalActionException,
                NameDuplicationException

Construct an attribute with the given container and name.

Parameters:

container - The container.

name - The name of the vertex.

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

addValueListener

public void addValueListener(ValueListener listener)

Add a listener to be notified when the value of this attribute changes. If the listener is already on the list of listeners, then do nothing.

Specified by:

addValueListener in interface Settable

Parameters:

listener - The listener to add.

See Also:

removeValueListener(ValueListener)

clone

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

Clone the location 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).

Overrides:

clone in class Attribute

Parameters:

workspace - The workspace for the cloned object.

Returns:

A new Location.

Throws:

java.lang.CloneNotSupportedException - If the base class throws it.

See Also:

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

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 non-persistent, then nothing is written.

Specified by:

exportMoML in interface MoMLExportable

Overrides:

exportMoML in class NamedObj

Parameters:

output - The output writer 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:

NamedObj.isPersistent()

getDefaultExpression

public java.lang.String getDefaultExpression()

Return the default value of this Settable, if there is one. If this is a derived object, then the default is the value of the object from which this is derived (the "prototype"). If this is not a derived object, then the default is the first value set using setExpression(), or null if setExpression() has not been called.

Specified by:

getDefaultExpression in interface Settable

Returns:

The default value of this attribute, or null if there is none.

See Also:

setExpression(String)

getDisplayName

public java.lang.String getDisplayName()

Return a name to present to the user, which is the same as the name returned by getName().

Specified by:

getDisplayName in interface Nameable

Specified by:

getDisplayName in interface Settable

Overrides:

getDisplayName in class NamedObj

Returns:

A name to present to the user.

See Also:

NamedObj.setDisplayName(String)

getExpression

public java.lang.String getExpression()

Get the value that has been set by setExpression() or by setLocation(), whichever was most recently called, or return an empty string if neither has been called.

If setExpression(String value) was called, then the return value is exactly what ever was passed in as the argument to setExpression. This means that there is no guarantee that the return value of getExpression() is a well formed Ptolemy array expression.

If setLocation(double[] location) was called, then the return value is a well formed Ptolemy array expression that starts with "{" and ends with "}", for example "{0.0, 0.0}"

Specified by:

getExpression in interface Settable

Returns:

The expression.

See Also:

setExpression(String)

getLocation

public double[] getLocation()

Get the location in some cartesian coordinate system.

Specified by:

getLocation in interface Locatable

Returns:

The location.

See Also:

setLocation(double[])

getValueAsString

public java.lang.String getValueAsString()

Get the value of the attribute, which is the evaluated expression.

Specified by:

getValueAsString in interface Settable

Returns:

The same as getExpression().

See Also:

getExpression()

getVisibility

public Settable.Visibility getVisibility()

Get the visibility of this attribute, as set by setVisibility(). The visibility is set by default to NONE.

Specified by:

getVisibility in interface Settable

Returns:

The visibility of this attribute.

See Also:

setVisibility(Settable.Visibility)

removeValueListener

public void removeValueListener(ValueListener listener)

Remove a listener from the list of listeners that is notified when the value of this variable changes. If no such listener exists, do nothing.

Specified by:

removeValueListener in interface Settable

Parameters:

listener - The listener to remove.

See Also:

addValueListener(ValueListener)

setExpression

public void setExpression(java.lang.String expression)

Set the value of the attribute by giving some expression. This expression is not parsed until validate() is called, and the container and value listeners are not notified until validate() is called. See the class comment for a description of the format.

Specified by:

setExpression in interface Settable

Parameters:

expression - The value of the attribute.

See Also:

getExpression()

setLocation

public void setLocation(double[] location)
                 throws IllegalActionException

Set the location in some cartesian coordinate system, and notify the container and any value listeners of the new location. Setting the location involves maintaining a local copy of the passed parameter. No notification is done if the location is the same as before. This method propagates the value to any derived objects.

Specified by:

setLocation in interface Locatable

Parameters:

location - The location.

Throws:

IllegalActionException - If throw when attributeChanged() is called.

See Also:

getLocation()

setVisibility

public void setVisibility(Settable.Visibility visibility)

Set the visibility of this attribute. The argument should be one of the public static instances in Settable.

Specified by:

setVisibility in interface Settable

Parameters:

visibility - The visibility of this attribute.

See Also:

getVisibility()

toString

public java.lang.String toString()

Get a description of the class, which is the class name and the location in parentheses.

Overrides:

toString in class NamedObj

Returns:

A string describing the object.

validate

public java.util.Collection validate()
                              throws IllegalActionException

Parse the location specification given by setExpression(), if there has been one, and otherwise set the location to 0.0, 0.0. Notify the container and any value listeners of the new location, if it has changed. See the class comment for a description of the format.

Specified by:

validate in interface Settable

Returns:

Null, indicating that no other instances of Settable are validated.

Throws:

IllegalActionException - If the expression is invalid.

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

_setLocation

private boolean _setLocation(double[] location)
                      throws IllegalActionException

Set the location without altering the modified status.

Parameters:

location - The location.

Returns:

True if the location was modified.

Throws:

IllegalActionException - If the call to attributeChanged() throws it.