y.layout.router
Class OrthogonalSegmentDistributionStage

java.lang.Object
  y.layout.AbstractLayoutStage
      y.layout.router.OrthogonalSegmentDistributionStage

All Implemented Interfaces:

Layouter, LayoutStage

public class OrthogonalSegmentDistributionStage
extends AbstractLayoutStage

OrthogonalSegmentDistributionStage distributes overlapping edge segments of orthogonally routed edges. The edge segments are assigned to the so-called channels within which they are distributed. Those channels are defined by the surrounding graph elements.

The algorithm will not distribute the segments, whose endpoints connect to a node using a port that has a strong PortConstraint or a fixed PortCandidate.

Features

It is possible to define a preferred distance between distributed edge segments. This distance will only be applied if there is enough space in the according channel. In the case where there is not enough space, the preferred distance may be reduced for the edges. If the layout algorithm is not allowed to reduce the preferred distance, these edges won't be distributed.

Edges can be distributed on grid coordinates. The grid can only be considered if there is enough space in the according channel for at least as many grid lines as the number of segments. In the case where there is not enough space, the grid spacing may be reduced in this channel. If the layout algorithm is not allowed to reduce the grid spacing, these edges won't be distributed.

Method setLockFirstAndLastSegment(boolean) can be used to guarantee that the first and last segment of an edge won't be distributed. So, ports can easily be maintained without setting explicit strong PortConstraints or fixed PortCandidates.

OrthogonalSegmentDistributionStage is not capable of moving nodes. Hence, edges are only distributed if they keep the aforementioned settings or the layout algorithm is allowed to adjust those settings.

Field Summary

static java.lang.Object

AFFECTED_EDGES A DataProvider key for determining which edges are distributed.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

OrthogonalSegmentDistributionStage()
Creates a new instance of OrthogonalSegmentDistributionStage with default settings.

Method Summary

boolean	canLayout(LayoutGraph graph) Accepts all graphs that can be handled by the core layout algorithm.
void	doLayout(LayoutGraph graph) Distributes overlapping orthogonal segments after the core layout has been calculated.
java.lang.Object	getAffectedEdgesDPKey() Returns the key to register a DataProvider which determines the edges that shall be routed by this algorithm.
double	getGridOffsetX() Returns the x-coordinate of the origin of the grid.
double	getGridOffsetY() Returns the y-coordinate of the origin of the grid.
double	getGridWidth() Returns the spacing between two grid lines.
double	getPreferredDistance() Returns the preferred distance between each two segments.
boolean	isGridEnabled() Returns whether or not the orthogonal segments are distributed on grid coordinates.
boolean	isGridWidthAdjustable() Returns whether or not the grid spacing can be reduced if there is not enough space.
boolean	isLockFirstAndLastSegment() Returns whether or not the first and last segment of an edge will be distributed.
boolean	isPreferredDistanceAdjustable() Returns whether or not the preferred distance between edges can be reduced if there is not enough space.
void	setAffectedEdgesDPKey(java.lang.Object key) Specifies the key to register a DataProvider which determines the edges that shall be routed by this algorithm.
void	setGridEnabled(boolean gridEnabled) Specifies whether or not the orthogonal segments are distributed on grid coordinates.
void	setGridOffset(double offsetX, double offsetY) Specifies the coordinates of the origin of the grid.
void	setGridWidth(double gridSpacing) Specifies the spacing between two grid lines.
void	setGridWidthAdjustable(boolean gridSpacingAdjustable) Specifies whether or not the grid spacing can be reduced if there is not enough space.
void	setLockFirstAndLastSegment(boolean lockFirstAndLastSegment) Specifies whether or not the first and last segment of an edge will be distributed.
void	setPreferredDistance(double minimumDistance) Specifies the preferred distance between each two segments.
void	setPreferredDistanceAdjustable(boolean preferredDistanceAdjustable) Specifies whether or not the preferred distance between edges can be reduced if there is not enough space.

Methods inherited from class y.layout.AbstractLayoutStage

canLayoutCore, doLayoutCore, getCoreLayouter, setCoreLayouter

Methods inherited from class java.lang.Object

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

Field Detail

AFFECTED_EDGES

public static final java.lang.Object AFFECTED_EDGES

A DataProvider key for determining which edges are distributed.

Constructor Detail

OrthogonalSegmentDistributionStage

public OrthogonalSegmentDistributionStage()

Creates a new instance of OrthogonalSegmentDistributionStage with default settings.

Method Detail

canLayout

public boolean canLayout(LayoutGraph graph)

Accepts all graphs that can be handled by the core layout algorithm.

If there is no core layout algorithm, all graphs are accepted.

Parameters:

graph - the input graph

Returns:

true if there is no core layout algorithm or the core layout algorithm accepts the graph, false otherwise

See Also:

Layouter.doLayout(LayoutGraph)

doLayout

public void doLayout(LayoutGraph graph)

Distributes overlapping orthogonal segments after the core layout has been calculated.

Parameters:

graph - the input graph

See Also:

Layouter.canLayout(LayoutGraph)

setAffectedEdgesDPKey

public void setAffectedEdgesDPKey(java.lang.Object key)

Specifies the key to register a DataProvider which determines the edges that shall be routed by this algorithm.

Default Value:

The default value is AFFECTED_EDGES

Parameters:

key - the key to register a DataProvider which determines the edges to route

Throws:

java.lang.IllegalArgumentException - if the specified DataProvider key is null

getAffectedEdgesDPKey

public java.lang.Object getAffectedEdgesDPKey()

Returns the key to register a DataProvider which determines the edges that shall be routed by this algorithm.

Returns:

the key to register a DataProvider which determines the edges to route

See Also:

setAffectedEdgesDPKey(Object)

isPreferredDistanceAdjustable

public boolean isPreferredDistanceAdjustable()

Returns whether or not the preferred distance between edges can be reduced if there is not enough space.

The space between the nodes limits distributing the orthogonal segments while considering the preferred distance. In case this option is enabled, the layout algorithm may reduce the preferred distance, otherwise the algorithm will only distribute segments if there is enough space.

Preferred distances will not be maintained for segments connecting to nodes (first and last segment of an edge). The segments are distributed equidistant all along the node side, and thus they may lead to greater distances between segments.

Returns:

true if the layout algorithm is allowed to reduce the preferred distance, false if it should only distribute segments where there is enough space to maintain the preferred distance

See Also:

setPreferredDistanceAdjustable(boolean)

setPreferredDistanceAdjustable

public void setPreferredDistanceAdjustable(boolean preferredDistanceAdjustable)

Specifies whether or not the preferred distance between edges can be reduced if there is not enough space.

The space between the nodes restricts the distribution of the orthogonal segments while considering the preferred distance. In case this option is enabled, the layout algorithm may reduce the preferred distance, otherwise the algorithm will only distribute segments if there is enough space.

Preferred distances will not be maintained for segments connecting to nodes (first and last segment of an edge). The segments are distributed equidistant all along the node side, and thus they may lead to greater distances between segments.

Default Value:

The default value is true. The preferred distance will be reduced if necessary.

Parameters:

preferredDistanceAdjustable - true if the layout algorithm should be allowed to reduce the preferred distance, false if it only distributes segments where there is enough space to maintain the preferred distance

isGridWidthAdjustable

public boolean isGridWidthAdjustable()

Returns whether or not the grid spacing can be reduced if there is not enough space.

The space between the nodes limits the number of grid lines on which edges are placed. In case this option is enabled, the layout algorithm will divide the given grid spacing by 2 as long as there are not enough grid lines on which the segments can be distributed, otherwise the grid spacing remains unchanged.

Reducing the grid spacing by half until there are enough grid lines for the segments, will lead to more nicer results than taking some other value.

The grid spacing will only be adjusted for segments that cannot maintain the originally set grid width.

Returns:

true if the algorithm should be allowed to reduce the grid spacing, false otherwise

See Also:

setGridWidthAdjustable(boolean)

setGridWidthAdjustable

public void setGridWidthAdjustable(boolean gridSpacingAdjustable)

Specifies whether or not the grid spacing can be reduced if there is not enough space.

The space between the nodes limits the number of grid lines on which edges are placed. In case this option is enabled, the layout algorithm will divide the given grid spacing by 2 as long as there are not enough grid lines on which the segments can be distributed, otherwise the grid spacing remains unchanged.

Reducing the grid spacing by half until there are enough grid lines for the segments, will lead to more nicer results than taking some other value.

The grid spacing will only be adjusted for segments that cannot maintain the originally set grid width.

Default Value:

The default value is true. The layout algorithm is allowed to reduce the grid spacing.

Parameters:

gridSpacingAdjustable - true if the algorithm should be allowed to reduce the grid spacing, false otherwise

isGridEnabled

public boolean isGridEnabled()

Returns whether or not the orthogonal segments are distributed on grid coordinates.

Returns:

true if segments are distributed on grid coordinates, false otherwise

See Also:

setGridEnabled(boolean), setGridOffset(double, double), setGridWidth(double), setGridWidthAdjustable(boolean)

setGridEnabled

public void setGridEnabled(boolean gridEnabled)

Specifies whether or not the orthogonal segments are distributed on grid coordinates.

Default Value:

The default value is false. Edges are distributed where there is enough space.

Parameters:

gridEnabled - true if segments are distributed on grid coordinates, false otherwise

See Also:

setGridOffset(double, double), setGridWidth(double), setGridWidthAdjustable(boolean)

getGridWidth

public double getGridWidth()

Returns the spacing between two grid lines.

The spacing should be at least 0.

This option will only have an effect if grid distribution is enabled.

Returns:

the grid spacing

See Also:

setGridEnabled(boolean), setGridEnabled(boolean), setGridWidthAdjustable(boolean)

setGridWidth

public void setGridWidth(double gridSpacing)

Specifies the spacing between two grid lines.

The spacing should be at least 0.

This option will only have an effect if grid distribution is enabled.

Default Value:

The default value is 10.

Parameters:

gridSpacing - the grid spacing

Throws:

java.lang.IllegalArgumentException - if the specified spacing is negative

See Also:

setGridEnabled(boolean), setGridWidthAdjustable(boolean)

setGridOffset

public void setGridOffset(double offsetX,
                          double offsetY)

Specifies the coordinates of the origin of the grid.

The grid coordinates will be multiples of the grid spacing added to this origin.

This option will only have an effect if grid distribution is enabled.

Parameters:

offsetX - the x-coordinate of the grid origin

offsetY - the y-coordinate of the grid origin

See Also:

setGridEnabled(boolean)

getGridOffsetX

public double getGridOffsetX()

Returns the x-coordinate of the origin of the grid.

The grid coordinates will be multiples of the grid spacing added to this origin.

This option will only have an effect if grid distribution is enabled.

Returns:

the x-coordinate of the grid origin

See Also:

setGridOffset(double, double), setGridEnabled(boolean), getGridOffsetY()

getGridOffsetY

public double getGridOffsetY()

Returns the y-coordinate of the origin of the grid.

The grid coordinates will be multiples of the grid spacing added to this origin.

This option will only have an effect if grid distribution is enabled.

Returns:

the y-coordinate of the grid origin

See Also:

setGridOffset(double, double), setGridEnabled(boolean), getGridOffsetX()

isLockFirstAndLastSegment

public boolean isLockFirstAndLastSegment()

Returns whether or not the first and last segment of an edge will be distributed.

Enable this option to keep the ports that the core layout algorithm calculated.

Returns:

true if the first and last segments won't be distributed, false otherwise

See Also:

setLockFirstAndLastSegment(boolean)

setLockFirstAndLastSegment

public void setLockFirstAndLastSegment(boolean lockFirstAndLastSegment)

Specifies whether or not the first and last segment of an edge will be distributed.

Enable this option to keep the ports that the core layout algorithm calculated.

Default Value:

The default value is false. The first and last segments will be distributed.

Parameters:

lockFirstAndLastSegment - true if the first and last segments won't be distributed, false otherwise

getPreferredDistance

public double getPreferredDistance()

Returns the preferred distance between each two segments.

This value also applies to the distance between a segment and the border of the containing channel.

The preferred distance should be at least 0.

In the case where the preferred distance is adjustable, the preferred distance might be reduced to the maximum possible distance closest to the given value. This happens if the channel is not large enough to fit in all segments with the desired preferred distance.

Returns:

the preferred distance between two segments

See Also:

setPreferredDistance(double), setPreferredDistanceAdjustable(boolean)

setPreferredDistance

public void setPreferredDistance(double minimumDistance)

Specifies the preferred distance between each two segments.

This value also applies to the distance between a segment and the border of the containing channel.

The preferred distance should be at least 0.

In the case where the preferred distance is adjustable, the preferred distance might be reduced to the maximum possible distance closest to the given value. This happens if the channel is not large enough to fit in all segments with the desired preferred distance.

Default Value:

The default value is 10.0.

Parameters:

minimumDistance - the preferred distance between two segments

Throws:

java.lang.IllegalArgumentException - if the specified distance is negative

See Also:

setPreferredDistanceAdjustable(boolean)