com.yworks.yfiles.layout.tree

Class ClassicTreeLayout

java.lang.Object

com.yworks.yfiles.layout.MultiStageLayout

com.yworks.yfiles.layout.tree.ClassicTreeLayout

All Implemented Interfaces:

ILayoutAlgorithm

public class ClassicTreeLayout
extends MultiStageLayout

This layout algorithm arranges graphs with a tree structure.

Layout Style

ClassicTreeLayout is designed to arrange directed and undirected trees that have a unique root node. All children are placed below their parent in relation to the main layout direction. The edges of the graph are routed as straight-line segments or in an orthogonal bus-like fashion.

Tree layout algorithms are commonly used for visualizing relational data and for producing diagrams of high quality that are able to reveal possible hierarchic properties of the graph. More precisely, they find applications in dataflow analysis, software engineering, bioinformatics and business administration.

A Dendrogram A graph containing group nodes Left-to-right layout with global layering

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

Features

The layout algorithm supports custom sorting of sibling nodes by using a specific NodeOrderComparator. Each tree node may have an individual NodeOrderComparator that is stored in a IDataProvider registered with the graph with NodeOrderComparator.NODE_ORDER_COMPARABLE_DPKEY. If this NodeOrderComparator uses the initial coordinates of the nodes, it allows the incremental insertion of child nodes while keeping the relative locations of the other nodes.

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

ClassicTreeLayout can be configured to reserve space for node labels. It can also place edge labels along edges such that the labels won't overlap with other graph elements. Edge labels are placed according to the information stored in a PreferredPlacementDescriptor instance. However, the placement along the edge will only affect the order of multiple labels at the same edge. The algorithm will always place the labels close to the target node.

Grouping of nodes can also be handled by this layout algorithm. It is important that a group node contains a whole subtree. Otherwise, the group nodes may overlap with each other or with other nodes. Furthermore, the user may specify minimum size constraints for each group node using IDataProvider key GroupingKeys.MINIMUM_NODE_SIZE_DPKEY.

This layout algorithm can only handle graphs with a tree structure. To apply it to a general graph, a TreeReductionStage can be appended. This stage will temporarily remove some edges of the input graph until a tree is obtained. After the layout calculation, the stage will reinsert the edges that were removed and route them separately.

Field Summary

Fields

Modifier and Type	Field and Description
static NodeDpKey<Boolean>	SELECTED_ROOT_DPKEY A DataProvider key for marking the node that will be used as root node of the tree.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	applyLayoutCore(LayoutGraph graph) Arranges the given graph as a tree.
double	getBusAlignment() Gets the vertical bus alignment for orthogonally routed edge buses.
Comparator<Object>	getComparator() Gets the Comparator instance that is used for sorting the outgoing edges of each node of the tree.
EdgeRoutingStyle	getEdgeRoutingStyle() Gets the edge routing style used by this layout algorithm.
LeafPlacement	getLeafPlacement() Gets the layout policy for leaf nodes.
double	getMinimumLayerDistance() Gets the minimum distance between two adjacent layers.
double	getMinimumNodeDistance() Gets the minimum horizontal distance between adjacent nodes within the same layer.
AbstractRotatableNodePlacer.Matrix	getModificationMatrix() Gets the modification matrix used for rotating / mirroring the layout.
PortStyle	getPortStyle() Gets the port assignment policy that will be applied.
double	getVerticalAlignment() Gets the vertical alignment of the nodes within their corresponding layers.
boolean	isGlobalLayeringEnforced() Gets whether or not a global layering is enforced, that is, each node spans exactly one layer.
boolean	isGroupingSupported() Gets whether or not group nodes are handled by the layout algorithm.
boolean	isIntegratedEdgeLabelingEnabled() Gets whether or not the layout algorithm reserves space for edge labels and places them.
boolean	isNodeLabelConsiderationEnabled() Gets whether or not the layout algorithm reserves space for node labels.
void	setBusAlignment(double value) Sets the vertical bus alignment for orthogonally routed edge buses.
void	setComparator(Comparator<Object> value) Sets the Comparator instance that is used for sorting the outgoing edges of each node of the tree.
void	setComponentLayoutEnabled(boolean value) Sets whether or not the ILayoutStage used for arranging the components of the graph is activated.
void	setEdgeRoutingStyle(EdgeRoutingStyle value) Sets the edge routing style used by this layout algorithm.
void	setGlobalLayeringEnforced(boolean value) Sets whether or not a global layering is enforced, that is, each node spans exactly one layer.
void	setGroupingSupported(boolean value) Sets whether or not group nodes are handled by the layout algorithm.
void	setIntegratedEdgeLabelingEnabled(boolean value) Sets whether or not the layout algorithm reserves space for edge labels and places them.
void	setLeafPlacement(LeafPlacement value) Sets the layout policy for leaf nodes.
void	setMinimumLayerDistance(double value) Sets the minimum distance between two adjacent layers.
void	setMinimumNodeDistance(double value) Sets the minimum horizontal distance between adjacent nodes within the same layer.
void	setModificationMatrix(AbstractRotatableNodePlacer.Matrix value) Sets the modification matrix used for rotating / mirroring the layout.
void	setNodeLabelConsiderationEnabled(boolean value) Sets whether or not the layout algorithm reserves space for node labels.
void	setParallelEdgeRouterEnabled(boolean value) Sets whether or not the ILayoutStage used for routing parallel edges is activated.
void	setPortStyle(PortStyle value) Sets the port assignment policy that will be applied.
void	setSelfLoopRouterEnabled(boolean value) Sets whether or not the ILayoutStage used for routing self-loops is activated.
void	setVerticalAlignment(double value) Sets the vertical alignment of the nodes within their corresponding layers.

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, setHideGroupsStageEnabled, 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

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.

Constructor Detail

ClassicTreeLayout

public ClassicTreeLayout()

Creates a new ClassicTreeLayout instance with default settings.

Method Detail

applyLayoutCore

public void applyLayoutCore(LayoutGraph graph)

Arranges the given graph as a tree.

Specified by:

applyLayoutCore in class MultiStageLayout

Parameters:

graph - the input graph

getBusAlignment

public double getBusAlignment()

Gets the vertical bus alignment for orthogonally routed edge buses.

The bus alignment determines the relative position of an edge bus between two subsequent layers. The value of this property must lie within the interval [0,1] where:

• A value of 0 places the bus at the top, directly below the parent node.
• A value of 0.5 places the bus in the middle between parent and child nodes.
• A value of 1 places the bus at the bottom, directly above the child nodes.

Throws:

IllegalArgumentException - if busAlignment is not in [0,1]

Bus alignment is taken into account only for:

• EdgeRoutingStyle.ORTHOGONAL layout style with global layering enforced.
• EdgeRoutingStyle.ORTHOGONAL layout style with child placement policy LeafPlacement.ALL_LEAVES_ON_SAME_LAYER.

Default Value:

The default value is 0.3. The bus is placed closer to the parent node than to the child nodes.

Returns:

a value from the interval [0,1]

See Also:

setEdgeRoutingStyle(EdgeRoutingStyle), setGlobalLayeringEnforced(boolean), setLeafPlacement(LeafPlacement), setBusAlignment(double)

getComparator

public Comparator<Object> getComparator()

Gets the Comparator instance that is used for sorting the outgoing edges of each node of the tree.

This comparator defines the relative order of the child nodes in the layout.

Default Value:

The default value is Comparator. An implementation that compares the x-coordinates of the nodes.

Returns:

a Comparator instance

See Also:

setComparator(Comparator)

getEdgeRoutingStyle

public EdgeRoutingStyle getEdgeRoutingStyle()

Gets the edge routing style used by this layout algorithm.

If EdgeRoutingStyle.PLAIN is set, the edges will be routed as straight-line segments. If EdgeRoutingStyle.ORTHOGONAL is set, all edges will be routed orthogonally in a bus-like fashion.

Throws:

IllegalArgumentException - if an invalid layout style is provided

Default Value:

The default value is EdgeRoutingStyle.PLAIN. Edges are routed as straight-line segments.

Returns:

one of EdgeRoutingStyle.PLAIN or EdgeRoutingStyle.ORTHOGONAL

See Also:

setEdgeRoutingStyle(EdgeRoutingStyle)

getLeafPlacement

public LeafPlacement getLeafPlacement()

Gets the layout policy for leaf nodes.

Throws:

IllegalArgumentException - if the specified policy is unknown

Default Value:

The default value is LeafPlacement.SIBLINGS_ON_SAME_LAYER. Sibling nodes are placed on the same layer.

Returns:

one of the predefined layout policies for leaf nodes

See Also:

setLeafPlacement(LeafPlacement)

getMinimumLayerDistance

public double getMinimumLayerDistance()

Gets the minimum distance between two adjacent layers.

Throws:

IllegalArgumentException - if the given distance is negative

Default Value:

The default value is 40.

Returns:

the non-negative minimum distance

See Also:

setMinimumLayerDistance(double)

getMinimumNodeDistance

public double getMinimumNodeDistance()

Gets the minimum horizontal distance between adjacent nodes within the same layer.

Throws:

IllegalArgumentException - if the given distance is negative

Default Value:

The default value is 20.

Returns:

the non-negative minimum distance

See Also:

setMinimumNodeDistance(double)

getModificationMatrix

public AbstractRotatableNodePlacer.Matrix getModificationMatrix()

Gets the modification matrix used for rotating / mirroring the layout.

Default Value:

The default value is AbstractRotatableNodePlacer.Matrix.DEFAULT

Returns:

the current modification matrix

See Also:

setModificationMatrix(AbstractRotatableNodePlacer.Matrix)

getPortStyle

public PortStyle getPortStyle()

Gets the port assignment policy that will be applied.

Default Value:

The default value is PortStyle.NODE_CENTER. Ports are placed at the center of the nodes.

Returns:

one of the predefined port assignment policies

See Also:

setPortStyle(PortStyle)

getVerticalAlignment

public double getVerticalAlignment()

Gets the vertical alignment of the nodes within their corresponding layers.

The value for the vertical alignment is considered as relative to the height of the corresponding layer, which is determined by the maximum height of the nodes that belong to the particular layer.

The value of this property must lie within the interval [0,1], where:

• A value of 0 corresponds to top-alignment.
• A value of 0.5 corresponds to center-alignment.
• A value of 1 corresponds to bottom-alignment.

Throws:

IllegalArgumentException - if vertical alignment value does not lie within [0,1]

If global layering is not enforced, the value of this property is usually ignored.

Default Value:

The default value is 0.5. Nodes of the same layer are center-aligned.

Returns:

a value from the interval [0,1]

See Also:

setGlobalLayeringEnforced(boolean), setVerticalAlignment(double)

isGlobalLayeringEnforced

public boolean isGlobalLayeringEnforced()

Gets whether or not a global layering is enforced, that is, each node spans exactly one layer.

If it is enabled, the algorithm ensures that nodes never span more than one layer. Otherwise, nodes with larger size might span two or more layers such that a more compact layout is produced.

This setting can be advantageous, if the hierarchical structure of the tree should be emphasized.

Disabling this feature to generate more compact layouts may force the algorithm to ignore the specified relative vertical alignment for nodes.

Default Value:

The default value is false. Global layering is disabled.

Returns:

true if global layering is enforced, false otherwise

See Also:

getVerticalAlignment(), setVerticalAlignment(double), setGlobalLayeringEnforced(boolean)

isGroupingSupported

public boolean isGroupingSupported()

Gets whether or not group nodes are handled by the layout algorithm.

If this option is disabled, group nodes will be temporarily hidden and reinserted to enclose their content. This may lead to node overlaps.

Grouping only works correctly, if each group contains a complete subtree. This means that for each group there is a node such that the group contains exactly this node and all its descendants.

Default Value:

The default value is true. Grouping is enabled.

Returns:

true if grouping is supported, false otherwise

See Also:

MultiStageLayout.setHideGroupsStageEnabled(boolean), setGroupingSupported(boolean)

isIntegratedEdgeLabelingEnabled

public boolean isIntegratedEdgeLabelingEnabled()

Gets whether or not the layout algorithm reserves space for edge labels and places them.

To define the desired placement for each label add a PreferredPlacementDescriptor on IEdgeLabelLayout.

This method is a convenience method that assures that the label layouter is of type LabelLayoutTranslator and EdgeLabelTranslationEnabled is set to true.

Optimal label placement with integrated labeling can be achieved using FreeEdgeLabelLayoutModel as the label model for the edges.

When enabling this property, any previously specified labeling algorithm will be overwritten and when disabling it, any currently specified labeling algorithm will be disabled via property LabelingEnabled. Therefore, it is recommended to only use this convenience property instead of manually changing the mentioned other properties.

Default Value:

The default value is false. Integrated edge labeling is disabled.

Returns:

true if integrated edge labeling is enabled, false otherwise

See Also:

setIntegratedEdgeLabelingEnabled(boolean)

isNodeLabelConsiderationEnabled

public boolean isNodeLabelConsiderationEnabled()

Gets whether or not the layout algorithm reserves space for node labels.

When enabling this property, any previously specified labeling algorithm will be overwritten and when disabling it, any currently specified labeling algorithm will be disabled via property LabelingEnabled. Therefore, it is recommended to only use this convenience property instead of manually changing the mentioned other properties.

Default Value:

The default value is false. Node labels are not considered.

Returns:

true if node labels are considered, false otherwise

See Also:

setNodeLabelConsiderationEnabled(boolean)

setBusAlignment

public void setBusAlignment(double value)

Sets the vertical bus alignment for orthogonally routed edge buses.

The bus alignment determines the relative position of an edge bus between two subsequent layers. The value of this property must lie within the interval [0,1] where:

• A value of 0 places the bus at the top, directly below the parent node.
• A value of 0.5 places the bus in the middle between parent and child nodes.
• A value of 1 places the bus at the bottom, directly above the child nodes.

Throws:

IllegalArgumentException - if busAlignment is not in [0,1]

Bus alignment is taken into account only for:

• EdgeRoutingStyle.ORTHOGONAL layout style with global layering enforced.
• EdgeRoutingStyle.ORTHOGONAL layout style with child placement policy LeafPlacement.ALL_LEAVES_ON_SAME_LAYER.

Default Value:

The default value is 0.3. The bus is placed closer to the parent node than to the child nodes.

Parameters:

value - a value from the interval [0,1]

See Also:

setEdgeRoutingStyle(EdgeRoutingStyle), setGlobalLayeringEnforced(boolean), setLeafPlacement(LeafPlacement), getBusAlignment()

setComparator

public void setComparator(Comparator<Object> value)

Sets the Comparator instance that is used for sorting the outgoing edges of each node of the tree.

This comparator defines the relative order of the child nodes in the layout.

Default Value:

The default value is Comparator. An implementation that compares the x-coordinates of the nodes.

Parameters:

value - a Comparator instance

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

ClassicTreeLayout 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

setEdgeRoutingStyle

public void setEdgeRoutingStyle(EdgeRoutingStyle value)

Sets the edge routing style used by this layout algorithm.

If EdgeRoutingStyle.PLAIN is set, the edges will be routed as straight-line segments. If EdgeRoutingStyle.ORTHOGONAL is set, all edges will be routed orthogonally in a bus-like fashion.

Throws:

IllegalArgumentException - if an invalid layout style is provided

Default Value:

The default value is EdgeRoutingStyle.PLAIN. Edges are routed as straight-line segments.

Parameters:

value - one of EdgeRoutingStyle.PLAIN or EdgeRoutingStyle.ORTHOGONAL

See Also:

getEdgeRoutingStyle()

setGlobalLayeringEnforced

public void setGlobalLayeringEnforced(boolean value)

Sets whether or not a global layering is enforced, that is, each node spans exactly one layer.

If it is enabled, the algorithm ensures that nodes never span more than one layer. Otherwise, nodes with larger size might span two or more layers such that a more compact layout is produced.

This setting can be advantageous, if the hierarchical structure of the tree should be emphasized.

Disabling this feature to generate more compact layouts may force the algorithm to ignore the specified relative vertical alignment for nodes.

Default Value:

The default value is false. Global layering is disabled.

Parameters:

value - true if global layering is enforced, false otherwise

See Also:

getVerticalAlignment(), setVerticalAlignment(double), isGlobalLayeringEnforced()

setGroupingSupported

public void setGroupingSupported(boolean value)

Sets whether or not group nodes are handled by the layout algorithm.

If this option is disabled, group nodes will be temporarily hidden and reinserted to enclose their content. This may lead to node overlaps.

Grouping only works correctly, if each group contains a complete subtree. This means that for each group there is a node such that the group contains exactly this node and all its descendants.

Default Value:

The default value is true. Grouping is enabled.

Parameters:

value - true if grouping is supported, false otherwise

See Also:

MultiStageLayout.setHideGroupsStageEnabled(boolean), isGroupingSupported()

setIntegratedEdgeLabelingEnabled

public void setIntegratedEdgeLabelingEnabled(boolean value)

Sets whether or not the layout algorithm reserves space for edge labels and places them.

To define the desired placement for each label add a PreferredPlacementDescriptor on IEdgeLabelLayout.

This method is a convenience method that assures that the label layouter is of type LabelLayoutTranslator and EdgeLabelTranslationEnabled is set to true.

Optimal label placement with integrated labeling can be achieved using FreeEdgeLabelLayoutModel as the label model for the edges.

When enabling this property, any previously specified labeling algorithm will be overwritten and when disabling it, any currently specified labeling algorithm will be disabled via property LabelingEnabled. Therefore, it is recommended to only use this convenience property instead of manually changing the mentioned other properties.

Default Value:

The default value is false. Integrated edge labeling is disabled.

Parameters:

value - true if integrated edge labeling is enabled, false otherwise

See Also:

isIntegratedEdgeLabelingEnabled()

setLeafPlacement

public void setLeafPlacement(LeafPlacement value)

Sets the layout policy for leaf nodes.

Throws:

IllegalArgumentException - if the specified policy is unknown

Default Value:

The default value is LeafPlacement.SIBLINGS_ON_SAME_LAYER. Sibling nodes are placed on the same layer.

Parameters:

value - one of the predefined layout policies for leaf nodes

See Also:

getLeafPlacement()

setMinimumLayerDistance

public void setMinimumLayerDistance(double value)

Sets the minimum distance between two adjacent layers.

Throws:

IllegalArgumentException - if the given distance is negative

Default Value:

The default value is 40.

Parameters:

value - the non-negative minimum distance

See Also:

getMinimumLayerDistance()

setMinimumNodeDistance

public void setMinimumNodeDistance(double value)

Sets the minimum horizontal distance between adjacent nodes within the same layer.

Throws:

IllegalArgumentException - if the given distance is negative

Default Value:

The default value is 20.

Parameters:

value - the non-negative minimum distance

See Also:

getMinimumNodeDistance()

setModificationMatrix

public void setModificationMatrix(AbstractRotatableNodePlacer.Matrix value)

Sets the modification matrix used for rotating / mirroring the layout.

Default Value:

The default value is AbstractRotatableNodePlacer.Matrix.DEFAULT

Parameters:

value - the current modification matrix

See Also:

getModificationMatrix()

setNodeLabelConsiderationEnabled

public void setNodeLabelConsiderationEnabled(boolean value)

Sets whether or not the layout algorithm reserves space for node labels.

When enabling this property, any previously specified labeling algorithm will be overwritten and when disabling it, any currently specified labeling algorithm will be disabled via property LabelingEnabled. Therefore, it is recommended to only use this convenience property instead of manually changing the mentioned other properties.

Default Value:

The default value is false. Node labels are not considered.

Parameters:

value - true if node labels are considered, false otherwise

See Also:

isNodeLabelConsiderationEnabled()

setParallelEdgeRouterEnabled

public void setParallelEdgeRouterEnabled(boolean value)

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

Overrides:

setParallelEdgeRouterEnabled in class MultiStageLayout

ClassicTreeLayout 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

setPortStyle

public void setPortStyle(PortStyle value)

Sets the port assignment policy that will be applied.

Default Value:

The default value is PortStyle.NODE_CENTER. Ports are placed at the center of the nodes.

Parameters:

value - one of the predefined port assignment policies

See Also:

getPortStyle()

setSelfLoopRouterEnabled

public void setSelfLoopRouterEnabled(boolean value)

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

Overrides:

setSelfLoopRouterEnabled in class MultiStageLayout

ClassicTreeLayout 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

setVerticalAlignment

public void setVerticalAlignment(double value)

Sets the vertical alignment of the nodes within their corresponding layers.

The value for the vertical alignment is considered as relative to the height of the corresponding layer, which is determined by the maximum height of the nodes that belong to the particular layer.

The value of this property must lie within the interval [0,1], where:

• A value of 0 corresponds to top-alignment.
• A value of 0.5 corresponds to center-alignment.
• A value of 1 corresponds to bottom-alignment.

Throws:

IllegalArgumentException - if vertical alignment value does not lie within [0,1]

If global layering is not enforced, the value of this property is usually ignored.

Default Value:

The default value is 0.5. Nodes of the same layer are center-aligned.

Parameters:

value - a value from the interval [0,1]

See Also:

setGlobalLayeringEnforced(boolean), getVerticalAlignment()