y.layout.tree
Class ARTreeLayouter

java.lang.Object
  y.layout.CanonicMultiStageLayouter
      y.layout.tree.ARTreeLayouter

All Implemented Interfaces:

Layouter

public class ARTreeLayouter
extends CanonicMultiStageLayouter

The ARTreeLayouter arranges tree graphs in a compact fashion.

Layout Style

This layout algorithm tries to generate compact tree layouts with a certain preferred aspect ratio.

Example layout with an aspect ratio of 0.5

Concept

The layout algorithm starts from the root and recursively assigns coordinates to all tree nodes. In this manner, leaf nodes will be placed first, while each parent node is placed centered above its child nodes.

Features

The aspect ratio of each subtree can be specified individually. A DataProvider registered with RATIO returns the aspect ratio for each local root node.

A custom node can be defined as root of the tree using a DataProvider registered with the graph with key SELECTED_ROOT_DPKEY.

Field Summary

protected LayoutGraph	graph The input graph this algorithm is handling.
static java.lang.Object	PLACEMENT_CORNER A root placement specifier for placing the root in the upper left corner of the subtree bounds with respect to the actual layout orientation.
static java.lang.Object	PLACEMENT_CORNER_SIDE A root placement specifier for placing the root in the upper left corner of the subtree bounds with respect to the actual layout orientation.
static java.lang.Object	PLACEMENT_CORNER_TOP A root placement specifier for placing the root of a subtree in the upper left corner of the subtree bounds with respect to the actual layout orientation.
static java.lang.Object	PLACEMENT_TOP A root placement specifier for placing the root centered above its subtree, depending on the actual layout orientation.
static java.lang.Object	RATIO A DataProvider key for specifying a target aspect ratio for each subtree The aspect ratio needs to be greater than 0.
static java.lang.Object	ROOT_PLACEMENT A DataProvider key for specifying the placement of each subtree root If no root placement is specified for one of the subtree roots, the default root placement will be used.
static java.lang.Object	ROUTING_HORIZONTAL A direction specifier for placing the child nodes next to each other in direction of the actual layout orientation, with the edges connecting in the direction of flow.
static java.lang.Object	ROUTING_POLICY A DataProvider key for specifying the routing direction for each subtree root The children in a subtree are arranged either horizontally or vertically.
static java.lang.Object	ROUTING_VERTICAL A direction specifier for placing the child nodes above each other in direction of the actual layout orientation, with the edges connecting orthogonally to the direction of flow.
static java.lang.Object	SELECTED_ROOT_DPKEY A DataProvider key for marking the node that will be used as root node of the tree.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

ARTreeLayouter()
Creates a new ARTreeLayouter instance with default settings.

Method Summary

boolean	canLayoutCore(LayoutGraph graph) Accepts all graphs with a tree structure.
protected void	createBends(EdgeLayout edgeLayout, Node localRoot, Node child, java.lang.Object rootPlacement, java.lang.Object routingPolicy) Adds bends to the given EdgeLayout.
void	doLayoutCore(LayoutGraph graph) Arranges the given graph considering the specified aspect ratio.
double	getAspectRatio() Returns the default aspect ratio for this ARTreeLayouter.
protected double	getAspectRatio(Node localRoot) Retrieves the aspect ratio for the subtree that is rooted at the given node.
double	getBendDistance() Returns the preferred distance between any two bends of an edge.
java.util.Comparator	getComparator() Returns the Comparator that will be used for sorting the outgoing edges of each local root in the tree before they are being arranged.
double	getHorizontalSpace() Returns the horizontal distance between adjacent nodes.
java.lang.Object	getRootPlacement() Returns the desired placement of the tree's root node.
protected java.lang.Object	getRootPlacement(java.lang.Object localRoot) Retrieves the root placement for the subtree that is rooted at the given node.
java.lang.Object	getRoutingPolicy() Returns how the children of a local root are arranged and how the edges between them are routed.
protected java.lang.Object	getRoutingPolicy(java.lang.Object localRoot) Retrieves the routing for the subtree that is rooted at the given node.
protected NodeCursor	getSuccessors(Node localRoot) Retrieves all children of the given local root.
double	getVerticalSpace() Returns the vertical distance between adjacent nodes.
void	setAspectRatio(double aspectRatio) Specifies the default aspect ratio for this ARTreeLayouter.
void	setBendDistance(double bendDistance) Specifies the preferred distance between any two bends of an edge.
void	setComparator(java.util.Comparator comparator) Specifies the Comparator that will be used for sorting the outgoing edges of each local root in the tree before they are being arranged.
void	setComponentLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage used for arranging the components of the graph is activated.
void	setGroupNodeHidingEnabled(boolean groupNodeHidingEnabled) Specifies whether or not the LayoutStage used for hiding group nodes is activated.
void	setHorizontalSpace(double distance) Specifies the horizontal distance between adjacent nodes.
void	setParallelEdgeLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage used for routing parallel edges is activated.
void	setRootPlacement(java.lang.Object rootPlacement) Specifies the desired placement of the tree's root node.
void	setRoutingPolicy(java.lang.Object routingPolicy) Specifies how the children of a local root are arranged and how the edges between them are routed.
void	setSelfLoopLayouterEnabled(boolean enabled) Specifies whether or not the LayoutStage used for routing self-loops is activated.
void	setVerticalSpace(double distance) Specifies the vertical distance between adjacent nodes.

Methods inherited from class y.layout.CanonicMultiStageLayouter

appendStage, calcLayout, calcLayout, canLayout, checkGroupNodeSize, checkNodeSize, doLayout, doLayout, enableOnlyCore, getComponentLayouter, getGroupNodeHider, getLabelLayouter, getLayoutOrientation, getOrientationLayouter, getParallelEdgeLayouter, getSelfLoopLayouter, getSubgraphLayouter, isComponentLayouterEnabled, isGroupNodeHidingEnabled, isLabelLayouterEnabled, isOrientationLayouterEnabled, isParallelEdgeLayouterEnabled, isSelfLoopLayouterEnabled, isSubgraphLayouterEnabled, prependStage, removeStage, setComponentLayouter, setGroupNodeHider, setLabelLayouter, setLabelLayouterEnabled, setLayoutOrientation, setOrientationLayouter, setOrientationLayouterEnabled, setParallelEdgeLayouter, setSelfLoopLayouter, setSubgraphLayouter, setSubgraphLayouterEnabled

Methods inherited from class java.lang.Object

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

Field Detail

RATIO

public static final java.lang.Object RATIO

A DataProvider key for specifying a target aspect ratio for each subtree The aspect ratio needs to be greater than 0.

• aspect ratio 1: width and height of the layout should be the same
• aspect ratio between 0 and 1: the height of the layout should be greater than its width
• aspect ratio greater than 1: the width of the layout should be greater than its height

If no specific ratio is defined for a subtree, the layout algorithm falls back to the default aspect ratio.

ROOT_PLACEMENT

public static final java.lang.Object ROOT_PLACEMENT

A DataProvider key for specifying the placement of each subtree root

If no root placement is specified for one of the subtree roots, the default root placement will be used.

PLACEMENT_TOP

public static final java.lang.Object PLACEMENT_TOP

A root placement specifier for placing the root centered above its subtree, depending on the actual layout orientation.

See Also:

ROOT_PLACEMENT

Sample Graph:

PLACEMENT_CORNER

public static final java.lang.Object PLACEMENT_CORNER

A root placement specifier for placing the root in the upper left corner of the subtree bounds with respect to the actual layout orientation.

Whether the root is placed entirely beside the subtree with no horizontal overlaps or entirely above the subtree without vertical overlaps will be determined by the layout of the subtree. The layout algorithm tries to minimize the bounds of the subtree.

See Also:

ROOT_PLACEMENT, PLACEMENT_CORNER_TOP, PLACEMENT_CORNER_SIDE

PLACEMENT_CORNER_SIDE

public static final java.lang.Object PLACEMENT_CORNER_SIDE

A root placement specifier for placing the root in the upper left corner of the subtree bounds with respect to the actual layout orientation.

The root is placed entirely beside the subtree with no horizontal overlaps. This might by important if the root's height is very large while its width is small.

See Also:

ROOT_PLACEMENT

Sample Graph:

PLACEMENT_CORNER_TOP

public static final java.lang.Object PLACEMENT_CORNER_TOP

A root placement specifier for placing the root of a subtree in the upper left corner of the subtree bounds with respect to the actual layout orientation.

The root is placed entirely above the subtree with no vertical overlaps. This might by important if the root's width is very large while its height is small.

See Also:

ROOT_PLACEMENT

Sample Graph:

ROUTING_POLICY

public static final java.lang.Object ROUTING_POLICY

A DataProvider key for specifying the routing direction for each subtree root The children in a subtree are arranged either horizontally or vertically. The edges are routed to the top of the child nodes or at the side, respectively. Directions depend on the layout orientation and refer to LayoutOrientation.TOP_TO_BOTTOM for this description.

If no specific routing policy is specified for a subtree root, the layout algorithm uses the default routing direction.

ROUTING_HORIZONTAL

public static final java.lang.Object ROUTING_HORIZONTAL

A direction specifier for placing the child nodes next to each other in direction of the actual layout orientation, with the edges connecting in the direction of flow.

See Also:

ROUTING_POLICY

Sample Graph:

ROUTING_VERTICAL

public static final java.lang.Object ROUTING_VERTICAL

A direction specifier for placing the child nodes above each other in direction of the actual layout orientation, with the edges connecting orthogonally to the direction of flow.

See Also:

ROUTING_POLICY

Sample Graph:

SELECTED_ROOT_DPKEY

public static final java.lang.Object SELECTED_ROOT_DPKEY

A DataProvider key for marking the node that will be used as root node of the tree.

graph

protected LayoutGraph graph

The input graph this algorithm is handling.

Constructor Detail

ARTreeLayouter

public ARTreeLayouter()

Creates a new ARTreeLayouter instance with default settings.

Method Detail

setHorizontalSpace

public void setHorizontalSpace(double distance)

Specifies the horizontal distance between adjacent nodes.

The distance needs to be non-negative.

Default Value:

The default value is 10.

Parameters:

distance - the horizontal distance between nodes

Throws:

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

Sample Graphs:

10

50

getHorizontalSpace

public double getHorizontalSpace()

Returns the horizontal distance between adjacent nodes.

The distance needs to be non-negative.

Returns:

the horizontal distance between nodes

See Also:

setHorizontalSpace(double)

setVerticalSpace

public void setVerticalSpace(double distance)

Specifies the vertical distance between adjacent nodes.

The distance needs to be non-negative.

Default Value:

The default value is 10.

Parameters:

distance - the vertical distance between nodes

Throws:

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

Sample Graphs:

10

50

getVerticalSpace

public double getVerticalSpace()

Returns the vertical distance between adjacent nodes.

The distance needs to be non-negative.

Returns:

the vertical distance between nodes

See Also:

setVerticalSpace(double)

setComponentLayouterEnabled

public void setComponentLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage used for arranging the components of the graph is activated.

Overrides:

setComponentLayouterEnabled in class CanonicMultiStageLayouter

ARTreeLayouter can only handle single components. Disabling ComponentLayouter will lead to errors during execution.

Default Value:

The default value is true. The stage that arranges connected graph components is activated.

Parameters:

enabled - true if the stage that arranges the graph components is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isComponentLayouterEnabled(), CanonicMultiStageLayouter.setComponentLayouter(LayoutStage), ComponentLayouter

setGroupNodeHidingEnabled

public void setGroupNodeHidingEnabled(boolean groupNodeHidingEnabled)

Specifies whether or not the LayoutStage used for hiding group nodes is activated.

Overrides:

setGroupNodeHidingEnabled in class CanonicMultiStageLayouter

ARTreeLayouter cannot handle group nodes. Disabling GroupNodeHider will lead to errors during execution.

Default Value:

The default value is true. The stage responsible for hiding group nodes is activated.

Parameters:

groupNodeHidingEnabled - true if the stage used for hiding group nodes is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isGroupNodeHidingEnabled(), CanonicMultiStageLayouter.setGroupNodeHider(LayoutStage), GroupNodeHider

setParallelEdgeLayouterEnabled

public void setParallelEdgeLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage used for routing parallel edges is activated.

Overrides:

setParallelEdgeLayouterEnabled in class CanonicMultiStageLayouter

ARTreeLayouter cannot handle parallel edges. Disabling ParallelEdgeLayouter will lead to errors during execution.

Default Value:

The default value is true. The stage that routes parallel edges is activated.

Parameters:

enabled - true if the stage responsible for routing parallel edges is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isParallelEdgeLayouterEnabled(), CanonicMultiStageLayouter.setParallelEdgeLayouter(LayoutStage), ParallelEdgeLayouter

setSelfLoopLayouterEnabled

public void setSelfLoopLayouterEnabled(boolean enabled)

Specifies whether or not the LayoutStage used for routing self-loops is activated.

Overrides:

setSelfLoopLayouterEnabled in class CanonicMultiStageLayouter

ARTreeLayouter cannot handle self-loops. Disabling SelfLoopLayouter will lead to errors during execution.

Default Value:

The default value is true. The stage that routes self-loops is activated.

Parameters:

enabled - true if the stage responsible for routing self-loops is activated, false otherwise

See Also:

CanonicMultiStageLayouter.isSelfLoopLayouterEnabled(), CanonicMultiStageLayouter.setSelfLoopLayouter(LayoutStage), SelfLoopLayouter

doLayoutCore

public void doLayoutCore(LayoutGraph graph)

Arranges the given graph considering the specified aspect ratio.

Specified by:

doLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the input graph

Throws:

WrongGraphStructure - if the input graph is not a tree

canLayoutCore

public boolean canLayoutCore(LayoutGraph graph)

Accepts all graphs with a tree structure.

Specified by:

canLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the input graph

Returns:

true if the given graph is a tree, false otherwise

See Also:

Trees.isTree(y.base.Graph)

getAspectRatio

protected double getAspectRatio(Node localRoot)

Retrieves the aspect ratio for the subtree that is rooted at the given node.

If there is an individual aspect ratio for the subtree provided by a DataProvider registered with key RATIO, that ratio will be returned. Otherwise, the default aspect ratio will be returned.

This method is called by doLayoutCore(LayoutGraph) before a subtree is arranged. It may be overridden to use another approach to define the aspect ratio for subtrees.

Parameters:

localRoot - the root node of the subtree

Returns:

the aspect ratio of the subtree rooted at the local root node

See Also:

RATIO, getAspectRatio()

getSuccessors

protected NodeCursor getSuccessors(Node localRoot)

Retrieves all children of the given local root.

This method is called by doLayoutCore(LayoutGraph) to arrange the subtrees below the local root.

Parameters:

localRoot - the root of a subtree

Returns:

all successors of the given node

getComparator

public java.util.Comparator getComparator()

Returns the Comparator that will be used for sorting the outgoing edges of each local root in the tree before they are being arranged.

The algorithm will only use the order induced by the Comparator, if the nodes (more precisely, their whole subtrees) have equal sizes. The reason is that the algorithm tries to find a good arrangement which optimizes the target aspect ratio. If the node ordering is already specified, this optimization would be impossible.

Returns:

a Comparator or null if the default order should be used

See Also:

setComparator(Comparator)

setComparator

public void setComparator(java.util.Comparator comparator)

Specifies the Comparator that will be used for sorting the outgoing edges of each local root in the tree before they are being arranged.

The algorithm will only use the order induced by the Comparator, if the nodes (more precisely, their whole subtrees) have equal sizes. The reason is that the algorithm tries to find a good arrangement which optimizes the target aspect ratio. If the node ordering is already specified, this optimization would be impossible.

Default Value:

The default value is null. Only the built-in logic of the layout algorithm is used.

Parameters:

comparator - a Comparator or null if the default order should be used

createBends

protected void createBends(EdgeLayout edgeLayout,
                           Node localRoot,
                           Node child,
                           java.lang.Object rootPlacement,
                           java.lang.Object routingPolicy)

Adds bends to the given EdgeLayout.

This method is called by doLayoutCore(LayoutGraph) for each edge, after the nodes are placed, to route the path of the edges. It may be overridden to apply a custom routing style.

Parameters:

edgeLayout - the layout of the edge that is routed

localRoot - the local root of the subtree

child - the child connected to the local root with the given edge

rootPlacement - the placement specifier of the local root

routingPolicy - the direction specifier for the routing

getRoutingPolicy

protected java.lang.Object getRoutingPolicy(java.lang.Object localRoot)

Retrieves the routing for the subtree that is rooted at the given node.

Either an individual routing for the subtree (defined via a DataProvider registered with ROUTING_POLICY), or if there is none, the default routing is returned.

This method is called by doLayoutCore(LayoutGraph) to determine the direction of the subtrees. It may be overridden to use another approach to define the routing for a subtree.

Parameters:

localRoot - the root of the subtree

Returns:

the routing policy for the subtree

See Also:

ROUTING_POLICY, getRoutingPolicy()

getRootPlacement

protected java.lang.Object getRootPlacement(java.lang.Object localRoot)

Retrieves the root placement for the subtree that is rooted at the given node.

Either an individual root placement for the subtree (defined via a DataProvider registered with ROOT_PLACEMENT), or if there is none, the default root placement is returned.

This method is called by doLayoutCore(LayoutGraph) after a subtree is arranged to align the local root node. It may be overridden to use another approach to define the root placement for a subtree.

Parameters:

localRoot - the root of the subtree

Returns:

the root placement of the subtree

See Also:

ROOT_PLACEMENT, getRootPlacement()

getAspectRatio

public double getAspectRatio()

Returns the default aspect ratio for this ARTreeLayouter.

This aspect ratio is used for all subtrees for which there is no specific aspect ratio defined in a DataProvider registered with RATIO.

The aspect ratio needs to have a positive value.

Returns:

the aspect ratio

See Also:

setAspectRatio(double)

setAspectRatio

public void setAspectRatio(double aspectRatio)

Specifies the default aspect ratio for this ARTreeLayouter.

This aspect ratio is used for all subtrees for which there is no specific aspect ratio defined in a DataProvider registered with RATIO.

The aspect ratio needs to have a positive value.

Default Value:

The default value is 1.41.

Parameters:

aspectRatio - the aspect ratio

Throws:

java.lang.IllegalArgumentException - if the specified aspect ratio is 0 or negative

Sample Graphs:

0.5

1

6

getRootPlacement

public java.lang.Object getRootPlacement()

Returns the desired placement of the tree's root node.

Returns:

one of PLACEMENT_TOP, PLACEMENT_CORNER, PLACEMENT_CORNER_SIDE or PLACEMENT_CORNER_TOP

See Also:

setRootPlacement(Object)

setRootPlacement

public void setRootPlacement(java.lang.Object rootPlacement)

Specifies the desired placement of the tree's root node.

Default Value:

The default value is PLACEMENT_CORNER

Parameters:

rootPlacement - one of PLACEMENT_TOP, PLACEMENT_CORNER, PLACEMENT_CORNER_SIDE or PLACEMENT_CORNER_TOP

Throws:

java.lang.IllegalArgumentException - if an unknown placement specifiers is set

getRoutingPolicy

public java.lang.Object getRoutingPolicy()

Returns how the children of a local root are arranged and how the edges between them are routed.

Default Value:

The default value is ROUTING_HORIZONTAL

Returns:

one of ROUTING_HORIZONTAL or ROUTING_VERTICAL

See Also:

setRoutingPolicy(Object)

setRoutingPolicy

public void setRoutingPolicy(java.lang.Object routingPolicy)

Specifies how the children of a local root are arranged and how the edges between them are routed.

Default Value:

The default value is ROUTING_HORIZONTAL

Parameters:

routingPolicy - one of ROUTING_HORIZONTAL and ROUTING_VERTICAL

Throws:

java.lang.IllegalArgumentException - if the specified routing policy is unknown

getBendDistance

public double getBendDistance()

Returns the preferred distance between any two bends of an edge. Additionally, the preferred bend distance governs the distance between the first and last edges and the corresponding ports.

The distance needs to be non-negative.

Returns:

the preferred bend distance

See Also:

setBendDistance(double)

setBendDistance

public void setBendDistance(double bendDistance)

Specifies the preferred distance between any two bends of an edge. Additionally, the preferred bend distance governs the distance between the first and last edges and the corresponding ports.

The distance needs to be non-negative.

Default Value:

The default value is 20.

Parameters:

bendDistance - the preferred bend distance

Throws:

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

Sample Graphs:

20

50