ptolemy.vergil.actor

Class LayoutHint.LayoutHintItem

java.lang.Object

ptolemy.vergil.actor.LayoutHint.LayoutHintItem

Enclosing class:

LayoutHint

public static class LayoutHint.LayoutHintItem
extends java.lang.Object

A LayoutHintItem is the specification of layout information for one Link. As there are usually multiple links corresponding to one Relation, a LayoutHint is attached to a Relation and carries multiple of these LayoutHintItems corresponding to the links. As links are no persisted objects in Ptolemy, a link is identified by its head and tail objects, which are Ports or Relations.

The most important information such item carries is a list of bend points that can be used to explicitly route a link along these bend points instead of using a simple routing strategy like the ManhattanConnector. A router that uses the bend point information for example is the KielerLayoutConnector.

Such item can be serialized to the String representation of a Ptolemy Expression by getExpression(). This is used for persisting LayoutHintItems. However, the bend point data are absolute coordinates and therefore are only valid until the head and/or tail of the link are moved. Hence, the LayoutHintItem also stores the coordinates and optionally the multiport width of head and tail, which specify for which layout of nodes the bend point information is only valid. The revalidate() method is used to check the validity of the LayoutHintItem by comparing the stored positions with the actual positions in the diagram, i.e. checking whether head and/or tail have been moved or the width of a multiport has changed. If the LayoutHintItem is not valid anymore, its bend points should not be used.

A special case is when head and tail moved relatively exactly the same, which happens, if multiple elements are selected and moved together. In such case the bend points are still valid relatively, but not absolutely. Therefore the revalidate() method also checks this case and translates the bend point coordinates as well as the new head and tail locations making the LayoutHintItem valid again. This avoids invalidating bend points when whole model parts get moved.

An example for one LayoutHintItem's String representation is the following

 { head={"CompositeActor.port",20.0,200.0,2}, tail={"Discard.input",70.0,25.0}, points={135.0,25.0,135.0,125.0} }
 

The head contains the object's name, its coordinates in x and y and the width, because the port is a multiport. The width defaults to 1 as can be seen at the tail where it is omitted.

Constructor Summary

Constructors

Constructor and Description
LayoutHintItem(NamedObj head, NamedObj tail) Simple constructor specifying only head and tail for this LayoutHintItem.
LayoutHintItem(NamedObj head, NamedObj tail, java.awt.geom.Point2D.Double locationHead, java.awt.geom.Point2D.Double locationTail, int multiportWidthHead, int multiportWidthTail, java.awt.geom.Point2D.Double labelPosition) Constructor passing not only head and tail but also all required layout information for the conditions under which this LayoutHintItem is only valid.

Method Summary

Modifier and Type	Method and Description
protected void	_reverse() Reverse the list of bend points.
java.util.List<java.awt.geom.Point2D>	getBendPointList() Get a list of Point2D corresponding to the bend points stored in this item.
double[]	getBendPoints() Get the bend points stored in this hint as an array of doubles, where each two entries correspond to x and y of one bend point.
java.lang.String	getExpression() Get the String representation of the Ptolemy Expression by which this LayoutHint is persisted.
NamedObj	getHead() Get the head of this LayoutHint which is used to identify this hint.
java.awt.geom.Point2D.Double	getLabelLocation() A Point2D representing the position where a label of an edge should be positioned.
NamedObj	getTail() Get the tail of this LayoutHint which is used to identify this hint.
boolean	revalidate() Check if the head and tail objects have been moved.
void	setBendpoints(double[] bendPoints) Set a new list of bend points and update the current validation information such as the current location of head and tail and their port widths.
void	setLabelLocation(java.awt.geom.Point2D.Double labelLocation) Sets the position a label should be placed at.
java.lang.String	toString() Get a String representation of a LayoutHint which will be the same as getExpression().

Methods inherited from class java.lang.Object

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

Constructor Detail

LayoutHintItem

public LayoutHintItem(NamedObj head,
                      NamedObj tail)

Simple constructor specifying only head and tail for this LayoutHintItem. The current layout of head and tail that is required for validity checking is obtained from these objects automatically.

Parameters:

head - the head object of the corresponding link

tail - the tail object of the corresponding link

LayoutHintItem

public LayoutHintItem(NamedObj head,
                      NamedObj tail,
                      java.awt.geom.Point2D.Double locationHead,
                      java.awt.geom.Point2D.Double locationTail,
                      int multiportWidthHead,
                      int multiportWidthTail,
                      java.awt.geom.Point2D.Double labelPosition)

Constructor passing not only head and tail but also all required layout information for the conditions under which this LayoutHintItem is only valid.

Parameters:

head - the head object of the corresponding link

tail - the tail object of the corresponding link

locationHead - the location of the head as vector

locationTail - the location of the tail as vector

multiportWidthHead - the width of the head, which is relevant for multiports, 1, if no multiport

multiportWidthTail - the width of the tail, which is relevant for multiports, 1, if no multiport

labelPosition - The position of the label.

Method Detail

getBendPoints

public double[] getBendPoints()

Get the bend points stored in this hint as an array of doubles, where each two entries correspond to x and y of one bend point.

Returns:

array containing bend point coordinates

getBendPointList

public java.util.List<java.awt.geom.Point2D> getBendPointList()

Get a list of Point2D corresponding to the bend points stored in this item. If by setting the bend points with setBendpoints(double[]) the list of bend point coordinates is odd, the last coordinate is discarded, and a list of points without the dangling coordinate is returned.

Returns:

list of bend points

getLabelLocation

public java.awt.geom.Point2D.Double getLabelLocation()

A Point2D representing the position where a label of an edge should be positioned.

Returns:

the label location.

See Also:

setLabelLocation(Point2D.Double)

getExpression

public java.lang.String getExpression()

Get the String representation of the Ptolemy Expression by which this LayoutHint is persisted. See the class comment for the concrete specification.

Returns:

String representation of this LayoutHint

getHead

public NamedObj getHead()

Get the head of this LayoutHint which is used to identify this hint.

Returns:

head object of this LayoutHint

getTail

public NamedObj getTail()

Get the tail of this LayoutHint which is used to identify this hint.

Returns:

tail object of this LayoutHint

revalidate

public boolean revalidate()

Check if the head and tail objects have been moved. If this is the case but both have been moved while keeping the same relative position to each other, the bend points can be translated accordingly. In this case, update the bend points and the head and tail location. If they have been moved and the relative positions are different now, then return false. In that case the bend point list is no longer feasible and should not be used anymore, however, no update is done here.

Returns:

true if the relative positions of head and tail are the same as before, false otherwise

setBendpoints

public void setBendpoints(double[] bendPoints)

Set a new list of bend points and update the current validation information such as the current location of head and tail and their port widths. Hence, this LayoutHint will be valid until the head and tail are moved again.

Parameters:

bendPoints - new bend points

setLabelLocation

public void setLabelLocation(java.awt.geom.Point2D.Double labelLocation)

Sets the position a label should be placed at.

Parameters:

labelLocation - a Point2D with the position, may be null.

See Also:

getLabelLocation()

toString

public java.lang.String toString()

Get a String representation of a LayoutHint which will be the same as getExpression().

Overrides:

toString in class java.lang.Object

Returns:

String representation of this LayoutHint

See Also:

getExpression()

_reverse

protected void _reverse()

Reverse the list of bend points. This may be neces