Search this API

y.layout.tree
Class ARTreeLayouter

java.lang.Object
  extended by y.layout.CanonicMultiStageLayouter
      extended by 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, 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.

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

© Copyright 2000-2021,
yWorks GmbH.
All rights reserved.