com.yworks.yfiles.layout.tree

Class AspectRatioTreeLayout

java.lang.Object

com.yworks.yfiles.layout.MultiStageLayout

com.yworks.yfiles.layout.tree.AspectRatioTreeLayout

All Implemented Interfaces:

ILayoutAlgorithm

public class AspectRatioTreeLayout
extends MultiStageLayout

The AspectRatioTreeLayout 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 IDataProvider registered with SUBTREE_ASPECT_RATIO_DPKEY returns the aspect ratio for each local root node.

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

Field Summary

Fields

Modifier and Type	Field and Description
protected LayoutGraph	graph The input graph this algorithm is handling.
static NodeDpKey<Object>	ROOT_PLACEMENT_DPKEY 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 NodeDpKey<Boolean>	SELECTED_ROOT_DPKEY A DataProvider key for marking the node that will be used as root node of the tree.
static NodeDpKey<Double>	SUBTREE_ASPECT_RATIO_DPKEY A DataProvider key for specifying a target aspect ratio for each subtree The aspect ratio needs to be greater than 0.
static NodeDpKey<Object>	SUBTREE_ROUTING_POLICY_DPKEY A DataProvider key for specifying the routing direction for each subtree root The children in a subtree are arranged either horizontally or vertically.

Constructor Summary

Constructors

Constructor and Description
AspectRatioTreeLayout() Creates a new AspectRatioTreeLayout instance with default settings.

Method Summary

Modifier and Type	Method and Description
void	applyLayoutCore(LayoutGraph graph) Arranges the given graph considering the specified aspect ratio.
protected void	createBends(IEdgeLayout edgeLayout, Node localRoot, Node child, RootPlacement rootPlacement, SubtreeArrangement routingPolicy) Adds bends to the given IEdgeLayout.
double	getAspectRatio() Gets the default aspect ratio for this AspectRatioTreeLayout.
protected double	getAspectRatio(Node localRoot) Retrieves the aspect ratio for the subtree that is rooted at the given node.
double	getBendDistance() Gets the preferred distance between any two bends of an edge.
Comparator<Object>	getComparator() Gets the Comparator that will be used for sorting the outgoing edges of each local root in the tree before they are being arranged.
double	getHorizontalDistance() Gets the horizontal distance between adjacent nodes.
RootPlacement	getRootPlacement() Gets the desired placement of the tree's root node.
protected RootPlacement	getRootPlacement(Object localRoot) Retrieves the root placement for the subtree that is rooted at the given node.
SubtreeArrangement	getSubtreeArrangement() Gets how the children of a local root are arranged and how the edges between them are routed.
protected SubtreeArrangement	getSubtreeArrangement(Object localRoot) Retrieves the routing for the subtree that is rooted at the given node.
protected INodeCursor	getSuccessors(Node localRoot) Retrieves all children of the given local root.
double	getVerticalDistance() Gets the vertical distance between adjacent nodes.
void	setAspectRatio(double value) Sets the default aspect ratio for this AspectRatioTreeLayout.
void	setBendDistance(double value) Sets the preferred distance between any two bends of an edge.
void	setComparator(Comparator<Object> value) Sets the Comparator that will be used for sorting the outgoing edges of each local root in the tree before they are being arranged.
void	setComponentLayoutEnabled(boolean value) Sets whether or not the ILayoutStage used for arranging the components of the graph is activated.
void	setHideGroupsStageEnabled(boolean value) Sets whether or not the ILayoutStage used for hiding group nodes is activated.
void	setHorizontalDistance(double value) Sets the horizontal distance between adjacent nodes.
void	setParallelEdgeRouterEnabled(boolean value) Sets whether or not the ILayoutStage used for routing parallel edges is activated.
void	setRootPlacement(RootPlacement value) Sets the desired placement of the tree's root node.
void	setSelfLoopRouterEnabled(boolean value) Sets whether or not the ILayoutStage used for routing self-loops is activated.
void	setSubtreeArrangement(SubtreeArrangement value) Sets how the children of a local root are arranged and how the edges between them are routed.
void	setVerticalDistance(double value) Sets the vertical distance between adjacent nodes.

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

appendStage, applyLayout, checkNodeSize, disableAllStages, getComponentLayout, getHideGroupsStage, getLabeling, getLayoutOrientation, getOrientationLayout, getParallelEdgeRouter, getSelfLoopRouter, getSubgraphLayout, isComponentLayoutEnabled, isHideGroupsStageEnabled, isLabelingEnabled, isOrientationLayoutEnabled, isParallelEdgeRouterEnabled, isSelfLoopRouterEnabled, isSubgraphLayoutEnabled, prependStage, removeStage, setComponentLayout, setHideGroupsStage, setLabeling, setLabelingEnabled, setLayoutOrientation, setOrientationLayout, setOrientationLayoutEnabled, setParallelEdgeRouter, setSelfLoopRouter, setSubgraphLayout, setSubgraphLayoutEnabled

Methods inherited from class java.lang.Object

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

Field Detail

graph

protected LayoutGraph graph

The input graph this algorithm is handling.

ROOT_PLACEMENT_DPKEY

public static final NodeDpKey<Object> ROOT_PLACEMENT_DPKEY

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.

SELECTED_ROOT_DPKEY

public static final NodeDpKey<Boolean> SELECTED_ROOT_DPKEY

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

SUBTREE_ASPECT_RATIO_DPKEY

public static final NodeDpKey<Double> SUBTREE_ASPECT_RATIO_DPKEY

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.

SUBTREE_ROUTING_POLICY_DPKEY

public static final NodeDpKey<Object> SUBTREE_ROUTING_POLICY_DPKEY

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.

Constructor Detail

AspectRatioTreeLayout

public AspectRatioTreeLayout()

Creates a new AspectRatioTreeLayout instance with default settings.

Method Detail

applyLayoutCore

public void applyLayoutCore(LayoutGraph graph)

Arranges the given graph considering the specified aspect ratio.

Specified by:

applyLayoutCore in class MultiStageLayout

Throws:

InvalidGraphStructureException - if the input graph is not a tree

Parameters:

graph - the input graph

createBends

protected void createBends(IEdgeLayout edgeLayout,
                           Node localRoot,
                           Node child,
                           RootPlacement rootPlacement,
                           SubtreeArrangement routingPolicy)

Adds bends to the given IEdgeLayout.

This method is called by applyLayoutCore(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

getAspectRatio

public double getAspectRatio()

Gets the default aspect ratio for this AspectRatioTreeLayout.

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

The aspect ratio needs to have a positive value.

Throws:

IllegalArgumentException - if the specified aspect ratio is 0 or negative

Default Value:

The default value is 1.41.

Returns:

the aspect ratio

See Also:

setAspectRatio(double)

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 IDataProvider registered with key SUBTREE_ASPECT_RATIO_DPKEY, that ratio will be returned. Otherwise, the default aspect ratio will be returned.

This method is called by applyLayoutCore(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:

SUBTREE_ASPECT_RATIO_DPKEY, getAspectRatio()

getBendDistance

public double getBendDistance()

Gets 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.

Throws:

IllegalArgumentException - if the specified distance is negative

Default Value:

The default value is 20.

Returns:

the preferred bend distance

See Also:

setBendDistance(double)

getComparator

public Comparator<Object> getComparator()

Gets 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 (or better their whole subtrees) have equal sizes.

Default Value:

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

Returns:

a Comparator or null if the default order should be used

See Also:

setComparator(Comparator)

getHorizontalDistance

public double getHorizontalDistance()

Gets the horizontal distance between adjacent nodes.

The distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is negative

Default Value:

The default value is 10.

Returns:

the horizontal distance between nodes

See Also:

setHorizontalDistance(double)

getRootPlacement

public RootPlacement getRootPlacement()

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

Throws:

IllegalArgumentException - if an unknown placement specifiers is set

Default Value:

The default value is RootPlacement.CORNER

Returns:

one of RootPlacement.TOP, RootPlacement.CORNER, RootPlacement.CORNER_SIDE or RootPlacement.CORNER_TOP

See Also:

setRootPlacement(RootPlacement)

getRootPlacement

protected RootPlacement getRootPlacement(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 IDataProvider registered with ROOT_PLACEMENT_DPKEY), or if there is none, the default root placement is returned.

This method is called by applyLayoutCore(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_DPKEY, getRootPlacement()

getSubtreeArrangement

public SubtreeArrangement getSubtreeArrangement()

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

Throws:

IllegalArgumentException - if the specified routing policy is unknown

Default Value:

The default value is SubtreeArrangement.HORIZONTAL

Returns:

one of SubtreeArrangement.HORIZONTAL or SubtreeArrangement.VERTICAL

See Also:

setSubtreeArrangement(SubtreeArrangement)

getSubtreeArrangement

protected SubtreeArrangement getSubtreeArrangement(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 IDataProvider registered with SUBTREE_ROUTING_POLICY_DPKEY), or if there is none, the default routing is returned.

This method is called by applyLayoutCore(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:

SUBTREE_ROUTING_POLICY_DPKEY, getSubtreeArrangement()

getSuccessors

protected INodeCursor getSuccessors(Node localRoot)

Retrieves all children of the given local root.

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

Parameters:

localRoot - the root of a subtree

Returns:

all successors of the given node

getVerticalDistance

public double getVerticalDistance()

Gets the vertical distance between adjacent nodes.

The distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is negative

Default Value:

The default value is 10.

Returns:

the vertical distance between nodes

See Also:

setVerticalDistance(double)

setAspectRatio

public void setAspectRatio(double value)

Sets the default aspect ratio for this AspectRatioTreeLayout.

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

The aspect ratio needs to have a positive value.

Throws:

IllegalArgumentException - if the specified aspect ratio is 0 or negative

Default Value:

The default value is 1.41.

Parameters:

value - the aspect ratio

See Also:

getAspectRatio()

setBendDistance

public void setBendDistance(double value)

Sets 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.

Throws:

IllegalArgumentException - if the specified distance is negative

Default Value:

The default value is 20.

Parameters:

value - the preferred bend distance

See Also:

getBendDistance()

setComparator

public void setComparator(Comparator<Object> value)

Sets 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 (or better their whole subtrees) have equal sizes.

Default Value:

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

Parameters:

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

See Also:

getComparator()

setComponentLayoutEnabled

public void setComponentLayoutEnabled(boolean value)

Sets whether or not the ILayoutStage used for arranging the components of the graph is activated.

Overrides:

setComponentLayoutEnabled in class MultiStageLayout

AspectRatioTreeLayout can only handle single components. Disabling ComponentLayout will lead to errors during execution.

Default Value:

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

Parameters:

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

See Also:

MultiStageLayout.isComponentLayoutEnabled(), MultiStageLayout.setComponentLayout(ILayoutStage), ComponentLayout

setHideGroupsStageEnabled

public void setHideGroupsStageEnabled(boolean value)

Sets whether or not the ILayoutStage used for hiding group nodes is activated.

Overrides:

setHideGroupsStageEnabled in class MultiStageLayout

AspectRatioTreeLayout cannot handle group nodes. Disabling HideGroupsStage will lead to errors during execution.

Default Value:

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

Parameters:

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

See Also:

MultiStageLayout.isHideGroupsStageEnabled(), MultiStageLayout.setHideGroupsStage(ILayoutStage), HideGroupsStage

setHorizontalDistance

public void setHorizontalDistance(double value)

Sets the horizontal distance between adjacent nodes.

The distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is negative

Default Value:

The default value is 10.

Parameters:

value - the horizontal distance between nodes

See Also:

getHorizontalDistance()

setParallelEdgeRouterEnabled

public void setParallelEdgeRouterEnabled(boolean value)

Sets whether or not the ILayoutStage used for routing parallel edges is activated.

Overrides:

setParallelEdgeRouterEnabled in class MultiStageLayout

AspectRatioTreeLayout cannot handle parallel edges. Disabling ParallelEdgeRouter will lead to errors during execution.

Default Value:

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

Parameters:

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

See Also:

MultiStageLayout.isParallelEdgeRouterEnabled(), MultiStageLayout.setParallelEdgeRouter(ILayoutStage), ParallelEdgeRouter

setRootPlacement

public void setRootPlacement(RootPlacement value)

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

Throws:

IllegalArgumentException - if an unknown placement specifiers is set

Default Value:

The default value is RootPlacement.CORNER

Parameters:

value - one of RootPlacement.TOP, RootPlacement.CORNER, RootPlacement.CORNER_SIDE or RootPlacement.CORNER_TOP

See Also:

getRootPlacement()

setSelfLoopRouterEnabled

public void setSelfLoopRouterEnabled(boolean value)

Sets whether or not the ILayoutStage used for routing self-loops is activated.

Overrides:

setSelfLoopRouterEnabled in class MultiStageLayout

AspectRatioTreeLayout cannot handle self-loops. Disabling SelfLoopRouter will lead to errors during execution.

Default Value:

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

Parameters:

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

See Also:

MultiStageLayout.isSelfLoopRouterEnabled(), MultiStageLayout.setSelfLoopRouter(ILayoutStage), SelfLoopRouter

setSubtreeArrangement

public void setSubtreeArrangement(SubtreeArrangement value)

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

Throws:

IllegalArgumentException - if the specified routing policy is unknown

Default Value:

The default value is SubtreeArrangement.HORIZONTAL

Parameters:

value - one of SubtreeArrangement.HORIZONTAL or SubtreeArrangement.VERTICAL

See Also:

getSubtreeArrangement()

setVerticalDistance

public void setVerticalDistance(double value)

Sets the vertical distance between adjacent nodes.

The distance needs to be non-negative.

Throws:

IllegalArgumentException - if the specified distance is negative

Default Value:

The default value is 10.

Parameters:

value - the vertical distance between nodes

See Also:

getVerticalDistance()