com.yworks.yfiles.layout

Class ParallelEdgeRouter

java.lang.Object

com.yworks.yfiles.layout.AbstractLayoutStage

com.yworks.yfiles.layout.ParallelEdgeRouter

All Implemented Interfaces:

ILayoutAlgorithm, ILayoutStage

public class ParallelEdgeRouter
extends AbstractLayoutStage

ParallelEdgeRouter is a ILayoutStage that routes parallel edges which connect the same pair of nodes in a graph.

Layout Style

The edge paths of parallel edges consist of parallel segments. At the end points, the edges can either still be parallel or joined in one point.

The master edge determining the routing is highlighted

Concept

ParallelEdgeRouter performs four basic steps:

1. Remove all parallel edges from the input graph, leaving one master edge in the graph
2. Invoke the core layout algorithm on the graph without parallel edges
3. Reinsert all previously removed edges
4. Route the parallel edges

Features

ParallelEdgeRouter can either be used as a ILayoutStage wrapping a layout algorithm which cannot handle parallel edges. Then it will hide the parallel edges from this core layout algorithm and take over the routing of them.
If no core layout algorithm is specified, ParallelEdgeRouter can work alone. It will route only the parallel edges and keep the remaining graph unchanged.

Parallel edges can either be all edges between the same two nodes, ignoring the direction, or edges are only considered parallel if they share the same source node and target node. Hence, they share the same direction.

To make sure that the ports of all parallel edges are on the end nodes, the first and last segments can be joined. However, these segments won't be parallel.

There are two ways to define the distance between two parallel edges. First, an absolute distance can be defined. Parallel segments will keep this distance. Second, the distance can be determined relative to the node bounds. Depending on the size of the nodes and the number of parallel edges between them, the distance between parallel edges is adjusted. This will keep the edges straight in most cases.

It is possible to select custom master edges. All edges that are parallel to the selected edges will be temporarily removed.

Field Summary

Fields

Modifier and Type	Field and Description
static EdgeDpKey<Boolean>	AFFECTED_EDGES_DPKEY A DataProvider key for marking edges that will be routed
protected EdgeList	hiddenEdges Holds the list of parallel edges that are hidden from the core layout algorithm.
static EdgeDpKey<Boolean>	LEADING_EDGE_DPKEY A DataProvider key for specifying the master edges Marked edges won't be removed for the core layout algorithm.
IEdgeMap	parallelEdges IEdgeMap that associates a hidden edge with the unique parallel edge not hidden from the core layout algorithm.

Constructor Summary

Constructors

Constructor and Description
ParallelEdgeRouter() Creates a new ParallelEdgeRouter instance with an optional core layout algorithm.
ParallelEdgeRouter(ILayoutAlgorithm coreLayouter) Creates a new ParallelEdgeRouter instance with an optional core layout algorithm.

Method Summary

Modifier and Type	Method and Description
void	applyLayout(LayoutGraph graph) Delegates the arrangement of nodes and edges to the core layout algorithm and routes the parallel edges.
protected void	findAndHideParallelEdges(Graph graph) Hides all parallel edges leaving a master edge in the graph.
double	getAbsJoinEndDistance() Gets the absolute distance from the end point of the joined lines to the first parallel segments.
double	getLineDistance() Gets the distance between two adjacent edge paths that run in parallel.
double	getRelJoinEndDistance() Gets the relative distance from the end point of the joined lines to the first parallel segments.
boolean	isAdaptiveLineDistancesEnabled() Gets whether or not the distances between parallel edges should be determined automatically according to the sizes of their source and target nodes.
boolean	isDirectedModeEnabled() Gets whether or not the direction of edges should be considered.
boolean	isJoiningEndsEnabled() Gets whether or not to join end points of parallel edges.
boolean	isLeadingEdgeAdjustmentEnabled() Gets whether or not to adjust the leading edge to obtain more symmetric results.
protected void	layoutParallelEdges(LayoutGraph graph, IEdgeMap parallelEdges) Assigns a layout to all parallel edges.
void	setAbsJoinEndDistance(double value) Sets the absolute distance from the end point of the joined lines to the first parallel segments.
void	setAdaptiveLineDistancesEnabled(boolean value) Sets whether or not the distances between parallel edges should be determined automatically according to the sizes of their source and target nodes.
void	setDirectedModeEnabled(boolean value) Sets whether or not the direction of edges should be considered.
void	setJoiningEndsEnabled(boolean value) Sets whether or not to join end points of parallel edges.
void	setLeadingEdgeAdjustmentEnabled(boolean value) Sets whether or not to adjust the leading edge to obtain more symmetric results.
void	setLineDistance(double value) Sets the distance between two adjacent edge paths that run in parallel.
void	setRelJoinEndDistance(double value) Sets the relative distance from the end point of the joined lines to the first parallel segments.

Methods inherited from class com.yworks.yfiles.layout.AbstractLayoutStage

applyLayoutCore, getCoreLayout, setCoreLayout

Methods inherited from class java.lang.Object

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

Field Detail

AFFECTED_EDGES_DPKEY

public static final EdgeDpKey<Boolean> AFFECTED_EDGES_DPKEY

A DataProvider key for marking edges that will be routed

If no IDataProvider is registered with the given key, all edges will be routed.

hiddenEdges

protected EdgeList hiddenEdges

Holds the list of parallel edges that are hidden from the core layout algorithm.

LEADING_EDGE_DPKEY

public static final EdgeDpKey<Boolean> LEADING_EDGE_DPKEY

A DataProvider key for specifying the master edges

Marked edges won't be removed for the core layout algorithm. All edges parallel to the master edges will get parallel paths.

If no leading edge is specified for a bundle of parallel edges, it will be determined automatically. If there is more than one leading edge, the first one is chosen.

parallelEdges

public IEdgeMap parallelEdges

IEdgeMap that associates a hidden edge with the unique parallel edge not hidden from the core layout algorithm.

Constructor Detail

ParallelEdgeRouter

public ParallelEdgeRouter()

Creates a new ParallelEdgeRouter instance with an optional core layout algorithm.

See Also:

AbstractLayoutStage.setCoreLayout(ILayoutAlgorithm)

ParallelEdgeRouter

public ParallelEdgeRouter(ILayoutAlgorithm coreLayouter)

Creates a new ParallelEdgeRouter instance with an optional core layout algorithm.

Parameters:

coreLayouter - The core layout algorithm.

See Also:

AbstractLayoutStage.setCoreLayout(ILayoutAlgorithm)

Method Detail

applyLayout

public void applyLayout(LayoutGraph graph)

Delegates the arrangement of nodes and edges to the core layout algorithm and routes the parallel edges.

Specified by:

applyLayout in interface ILayoutAlgorithm

Specified by:

applyLayout in class AbstractLayoutStage

Parameters:

graph - the input graph

findAndHideParallelEdges

protected void findAndHideParallelEdges(Graph graph)

Hides all parallel edges leaving a master edge in the graph.

ParallelEdgeRouter detects parallel edges of the given graph. From each set of parallel edges it hides all but one edge from the given graph.

This method is called before invoking the core layout algorithm. It may be overridden to change the selection of leading edges. Hidden edges should be stored in hiddenEdges to enable un-hiding later on.

Parameters:

graph - the input graph

See Also:

setDirectedModeEnabled(boolean), AFFECTED_EDGES_DPKEY

getAbsJoinEndDistance

public double getAbsJoinEndDistance()

Gets the absolute distance from the end point of the joined lines to the first parallel segments.

The absolute distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is negative

This distance is only considered if parallel edge paths are joined.

Default Value:

The default value is 20.

Returns:

the absolute distance from the end point to the first/last bend of parallel edges

See Also:

setJoiningEndsEnabled(boolean), setRelJoinEndDistance(double), setAbsJoinEndDistance(double)

getLineDistance

public double getLineDistance()

Gets the distance between two adjacent edge paths that run in parallel.

The distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is less than 0

If adaptive line distances are used, the resulting distance may be less than the specified distance.

Default Value:

The default value is 10.

Returns:

the distance between two parallel edges

See Also:

setAdaptiveLineDistancesEnabled(boolean), setLineDistance(double)

getRelJoinEndDistance

public double getRelJoinEndDistance()

Gets the relative distance from the end point of the joined lines to the first parallel segments.

The length is relative to the corresponding original segment's length. It needs to have a value in the interval [0,1].

Throws:

IllegalArgumentException - if the specified relative distance is less than 0 or greater than 1

This distance is only considered if parallel edge paths are joined.

Default Value:

The default value is 0.1.

Returns:

the relative distance from the end point to the first/last bend of parallel edges

See Also:

setJoiningEndsEnabled(boolean), setAbsJoinEndDistance(double), setRelJoinEndDistance(double)

isAdaptiveLineDistancesEnabled

public boolean isAdaptiveLineDistancesEnabled()

Gets whether or not the distances between parallel edges should be determined automatically according to the sizes of their source and target nodes.

If enabled, the distances between edges are chosen such that all parallel edges can be drawn as straight lines and still connect to the nodes' bounds.

Default Value:

The default value is true. The distances between parallel edges are adjusted to the nodes' bounds.

Returns:

true if the distances are determined according to the nodes' bounds, false otherwise

See Also:

setLineDistance(double), setAdaptiveLineDistancesEnabled(boolean)

isDirectedModeEnabled

public boolean isDirectedModeEnabled()

Gets whether or not the direction of edges should be considered.

In directed mode, only edges that share the same source and target node will be routed in parallel. Edges that connect to the same nodes but in different directions won't be considered parallel.

In undirected mode, all edges connecting the same pair of nodes will be routed in parallel.

Default Value:

The default value is false. All edges that connect the same pair of nodes are considered parallel, ignoring their directions.

Returns:

true if the direction of parallel edges must be the same, false otherwise

See Also:

setDirectedModeEnabled(boolean)

isJoiningEndsEnabled

public boolean isJoiningEndsEnabled()

Gets whether or not to join end points of parallel edges.

If enabled, all edges end with non-parallel segments that connect at the same point to the node. Otherwise, all segments of the edges are parallel. In this case, some edges may not connect to the nodes' bounds.

Default Value:

The default value is false. Parallel edges have only parallel segments.

Returns:

true if edges are joined at the ends, false otherwise

See Also:

setAbsJoinEndDistance(double), setRelJoinEndDistance(double), setJoiningEndsEnabled(boolean)

isLeadingEdgeAdjustmentEnabled

public boolean isLeadingEdgeAdjustmentEnabled()

Gets whether or not to adjust the leading edge to obtain more symmetric results.

Default Value:

The default value is true. The leading edge is adjusted for more symmetric results.

Returns:

true if the leading edge is adjusted, false otherwise

See Also:

setLeadingEdgeAdjustmentEnabled(boolean)

layoutParallelEdges

protected void layoutParallelEdges(LayoutGraph graph,
                                   IEdgeMap parallelEdges)

Assigns a layout to all parallel edges.

The layout for each parallel edge follows the layout of the master edge which was not removed from the core layout algorithm.

This method is called when the core layout algorithm is finished. It may be overridden to introduce a custom routing for parallel edges.

Parameters:

graph - the graph after the core layout

parallelEdges - the map that provides all parallel edges for each master edge

See Also:

setJoiningEndsEnabled(boolean), setAdaptiveLineDistancesEnabled(boolean), setLeadingEdgeAdjustmentEnabled(boolean)

setAbsJoinEndDistance

public void setAbsJoinEndDistance(double value)

Sets the absolute distance from the end point of the joined lines to the first parallel segments.

The absolute distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is negative

This distance is only considered if parallel edge paths are joined.

Default Value:

The default value is 20.

Parameters:

value - the absolute distance from the end point to the first/last bend of parallel edges

See Also:

setJoiningEndsEnabled(boolean), setRelJoinEndDistance(double), getAbsJoinEndDistance()

setAdaptiveLineDistancesEnabled

public void setAdaptiveLineDistancesEnabled(boolean value)

Sets whether or not the distances between parallel edges should be determined automatically according to the sizes of their source and target nodes.

If enabled, the distances between edges are chosen such that all parallel edges can be drawn as straight lines and still connect to the nodes' bounds.

Default Value:

The default value is true. The distances between parallel edges are adjusted to the nodes' bounds.

Parameters:

value - true if the distances are determined according to the nodes' bounds, false otherwise

See Also:

setLineDistance(double), isAdaptiveLineDistancesEnabled()

setDirectedModeEnabled

public void setDirectedModeEnabled(boolean value)

Sets whether or not the direction of edges should be considered.

In directed mode, only edges that share the same source and target node will be routed in parallel. Edges that connect to the same nodes but in different directions won't be considered parallel.

In undirected mode, all edges connecting the same pair of nodes will be routed in parallel.

Default Value:

The default value is false. All edges that connect the same pair of nodes are considered parallel, ignoring their directions.

Parameters:

value - true if the direction of parallel edges must be the same, false otherwise

See Also:

isDirectedModeEnabled()

setJoiningEndsEnabled

public void setJoiningEndsEnabled(boolean value)

Sets whether or not to join end points of parallel edges.

If enabled, all edges end with non-parallel segments that connect at the same point to the node. Otherwise, all segments of the edges are parallel. In this case, some edges may not connect to the nodes' bounds.

Default Value:

The default value is false. Parallel edges have only parallel segments.

Parameters:

value - true if edges are joined at the ends, false otherwise

See Also:

setAbsJoinEndDistance(double), setRelJoinEndDistance(double), isJoiningEndsEnabled()

setLeadingEdgeAdjustmentEnabled

public void setLeadingEdgeAdjustmentEnabled(boolean value)

Sets whether or not to adjust the leading edge to obtain more symmetric results.

Default Value:

The default value is true. The leading edge is adjusted for more symmetric results.

Parameters:

value - true if the leading edge is adjusted, false otherwise

See Also:

isLeadingEdgeAdjustmentEnabled()

setLineDistance

public void setLineDistance(double value)

Sets the distance between two adjacent edge paths that run in parallel.

The distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is less than 0

If adaptive line distances are used, the resulting distance may be less than the specified distance.

Default Value:

The default value is 10.

Parameters:

value - the distance between two parallel edges

See Also:

setAdaptiveLineDistancesEnabled(boolean), getLineDistance()

setRelJoinEndDistance

public void setRelJoinEndDistance(double value)

Sets the relative distance from the end point of the joined lines to the first parallel segments.

The length is relative to the corresponding original segment's length. It needs to have a value in the interval [0,1].

Throws:

IllegalArgumentException - if the specified relative distance is less than 0 or greater than 1

This distance is only considered if parallel edge paths are joined.

Default Value:

The default value is 0.1.

Parameters:

value - the relative distance from the end point to the first/last bend of parallel edges

See Also:

setJoiningEndsEnabled(boolean), setAbsJoinEndDistance(double), getRelJoinEndDistance()