This layout algorithm arranges graphs with a tree structure.
Remarks
Layout Style
TreeLayout provides multiple different arrangements of trees and subtrees. It is easy to customize the order of edges, the port assignment and the arrangement of the nodes for each subtree.
Tree layout algorithms are commonly applied to visualize relational data and produce 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.
Concept
The layout algorithm starts from the leaves and continues with their parents, then with the parents of the parents and so on. When a node is processed, the algorithm will use the corresponding ITreeLayoutNodePlacer instance to move its children (along with their subtrees) to a suitable position and to route the outgoing edges of this node. Then, the next local root node will be processed.
To avoid moving all nodes several times and to know the area that the subtrees occupy, the layout algorithm uses SubtreeShapes. These SubtreeShapes are moved and merged during layout calculation.
Features
Each subtree can have a different style of node placement. ITreeLayoutNodePlacers are responsible for arranging subtrees and their common root node. They can be specified separately for each local root with a IDataProvider registered with the graph using key NODE_PLACER_DP_KEY.
A custom node can be defined as root of the tree using a IDataProvider registered with the graph with key SELECTED_ROOT_DP_KEY.
The layout algorithm can be configured to reserve space for node labels and place the 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 MINIMUM_NODE_SIZE_DP_KEY.
TreeLayout supports custom sorting of the outgoing edges of a node. For example, a ITreeLayoutNodePlacer instance that implements IFromSketchNodePlacer provides a comparator that keeps the current order of siblings, allowing to extend the graph incrementally.
Node types are considered such that the type of the nodes is used as a criterion for sorting the child nodes of a local root node, with the effect that nodes of the same type are placed consecutively, if possible. The primary ordering criterion is still specified by the defaultOutEdgeComparer.
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.
Default Values of Properties
| componentLayoutEnabled | true | The stage that arranges connected graph components is activated. |
| considerNodeLabels | false | Node labels are not considered. |
| defaultNodePlacer | DefaultNodePlacer | |
| defaultOutEdgeComparer | null | No sorting is executed. |
| defaultPortAssignment | DefaultTreeLayoutPortAssignment | |
| groupingSupported | true | Grouping is enabled. |
| hideGroupsStageEnabled | false | The stage responsible for hiding group nodes is activated. |
| integratedEdgeLabeling | false | Edge labels are ignored. |
| multiParentAllowed | false | Multi-parent structures are not allowed. |
| parallelEdgeRouterEnabled | true | The stage that routes parallel edges is activated. |
| selfLoopRouterEnabled | true | The stage that routes self-loops is activated. |
Type Details
- yfiles module
- layout-tree
- yfiles-umd modules
- layout-orthogonal-compact, layout-orthogonal, layout-tree, layout
- Legacy UMD name
- yfiles.tree.TreeLayout
See Also
Constructors
Creates a new TreeLayout instance with default settings.
Parameters
A map of options to pass to the method.
- groupingSupported - boolean
Whether or not group nodes are handled by the layout algorithm. This option sets the groupingSupported property on the created object.
- componentLayoutEnabled - boolean
Whether or not the ILayoutStage used for arranging the components of the graph is activated. This option sets the componentLayoutEnabled property on the created object.
- parallelEdgeRouterEnabled - boolean
Whether or not the ILayoutStage used for routing parallel edges is activated. This option sets the parallelEdgeRouterEnabled property on the created object.
- selfLoopRouterEnabled - boolean
Whether or not the ILayoutStage used for routing self-loops is activated. This option sets the selfLoopRouterEnabled property on the created object.
- defaultNodePlacer - ITreeLayoutNodePlacer
The default ITreeLayoutNodePlacer instance that arranges all subtrees that do not have a specific ITreeLayoutNodePlacer assigned using a IDataProvider. This option sets the defaultNodePlacer property on the created object.
- defaultLeafPlacer - ITreeLayoutNodePlacer
The default ITreeLayoutNodePlacer instance that places the leaf nodes of the tree. This option sets the defaultLeafPlacer property on the created object.
- defaultPortAssignment - ITreeLayoutPortAssignment
The default ITreeLayoutPortAssignment instance for all subtrees that do not have a specific ITreeLayoutPortAssignment assigned using a IDataProvider. This option sets the defaultPortAssignment property on the created object.
- defaultOutEdgeComparer - IComparer<Object>
The default IComparer<T> instance that sorts the outgoing edges in all subtrees that do not have a specific IComparer<T> assigned using a IDataProvider. This option sets the defaultOutEdgeComparer property on the created object.
- considerNodeLabels - boolean
Whether or not the layout algorithm reserves space for node labels. This option sets the considerNodeLabels property on the created object.
- integratedEdgeLabeling - boolean
Whether or not edge labels are placed by the layout algorithm. This option sets the integratedEdgeLabeling property on the created object.
- multiParentAllowed - boolean
Whether or not multi-parent structures are allowed for this tree layout. This option sets the multiParentAllowed property on the created object.
- labeling - ILayoutStage
The ILayoutStage that places the labels of the input graph. This option sets the labeling property on the created object.
- selfLoopRouter - ILayoutStage
The ILayoutStage that routes self-loops. This option sets the selfLoopRouter property on the created object.
- parallelEdgeRouter - ILayoutStage
The ILayoutStage that routes parallel edges. This option sets the parallelEdgeRouter property on the created object.
- componentLayout - ILayoutStage
The ILayoutStage that arranges the connected components of an input graph. This option sets the componentLayout property on the created object.
- subgraphLayout - ILayoutStage
The ILayoutStage that constrains the layout process to a subgraph of the input graph. This option sets the subgraphLayout property on the created object.
- hideGroupsStage - ILayoutStage
The ILayoutStage that hides the group nodes of the input graph. This option sets the hideGroupsStage property on the created object.
- orientationLayout - ILayoutStage
The ILayoutStage that modifies the orientation of a computed layout. This option sets the orientationLayout property on the created object.
- orientationLayoutEnabled - boolean
Whether or not the ILayoutStage that modifies the orientation of the layout is activated. This option sets the orientationLayoutEnabled property on the created object.
- layoutOrientation - LayoutOrientation
The main orientation of the layout. This option sets the layoutOrientation property on the created object.
- labelingEnabled - boolean
Whether or not the ILayoutStage used for placing the labels of the input graph is activated. This option sets the labelingEnabled property on the created object.
- hideGroupsStageEnabled - boolean
Whether or not the ILayoutStage used for hiding group nodes is activated. This option sets the hideGroupsStageEnabled property on the created object.
- subgraphLayoutEnabled - boolean
Whether or not the ILayoutStage used for constraining the layout process to a subgraph of the input graph is activated. This option sets the subgraphLayoutEnabled property on the created object.
Properties
Gets or sets the ILayoutStage that arranges the connected components of an input graph.
Default Value
See Also
Defined in
Sets whether or not the ILayoutStage used for arranging the components of the graph is activated.
Default Value
true.The stage that arranges connected graph components is activated.
See Also
Overrides
Gets or sets whether or not the layout algorithm reserves space for node labels.
Remarks
Default Value
false.Node labels are not considered.
See Also
Sample Graphs
Gets or sets the default ITreeLayoutNodePlacer instance that places the leaf nodes of the tree.
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if the default
is set to null
See Also
Gets or sets the default ITreeLayoutNodePlacer instance that arranges all subtrees that do not have a specific ITreeLayoutNodePlacer assigned using a IDataProvider.
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if the default
is set to null
See Also
Gets or sets the default IComparer<T> instance that sorts the outgoing edges in all subtrees that do not have a specific IComparer<T> assigned using a IDataProvider.
Default Value
null.No sorting is executed.
See Also
null, the order of the edges will be maintained.Gets or sets the default ITreeLayoutPortAssignment instance for all subtrees that do not have a specific ITreeLayoutPortAssignment assigned using a IDataProvider.
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if the default
is set to null
See Also
Gets or sets whether or not group nodes are handled by the layout algorithm.
Default Value
true.Grouping is enabled.
See Also
Sample Graphs
Gets or sets the ILayoutStage that hides the group nodes of the input graph.
Default Value
See Also
Defined in
Gets or sets whether or not the ILayoutStage used for hiding group nodes is activated.
Remarks
Default Value(Overrides the default value defined in MultiStageLayout)
false.The stage responsible for hiding group nodes is activated.
See Also
Defined in
Gets or sets whether or not edge labels are placed by the layout algorithm.
Remarks
If this is enabled, the SubtreeShapes of the subtrees are extended by the edge labels.
The layout algorithm uses the information of PreferredPlacementDescriptor for an edge label to determine the corresponding placement. However, edge labels are always placed at the target side of the edge. The placement along the edge only affects the order of the edge labels at the same edge.
Default Value
false.Edge labels are ignored.
See Also
Sample Graphs
Gets or sets the ILayoutStage that places the labels of the input graph.
Default Value
See Also
Defined in
Gets or sets whether or not the ILayoutStage used for placing the labels of the input graph is activated.
Remarks
Default Value
false.The stage responsible for label placement is deactivated.
See Also
Defined in
Gets or sets the main orientation of the layout.
Remarks
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if the specified orientation does not match a default layout orientation
See Also
Defined in
Gets or sets whether or not multi-parent structures are allowed for this tree layout.
Remarks
Default Value
false.Multi-parent structures are not allowed.
See Also
Sample Graphs
- DefaultNodePlacer delivers the best results for multi-parent structures. However, routing style FORK_AT_ROOT as well as root alignments LEADING_ON_BUS and TRAILING_ON_BUS are not supported.
- DendrogramNodePlacer supports multi-parent structures.
- BusNodePlacer supports multi-parent structures.
- LeftRightNodePlacer supports multi-parent structures.
Gets or sets the ILayoutStage that modifies the orientation of a computed layout.
Default Value
See Also
Defined in
Gets or sets whether or not the ILayoutStage that modifies the orientation of the layout is activated.
Remarks
Default Value
true.The orientation
See Also
Defined in
Gets or sets the ILayoutStage that routes parallel edges.
Default Value
See Also
Defined in
Sets whether or not the ILayoutStage used for routing parallel edges is activated.
Default Value
true.The stage that routes parallel edges is activated.
See Also
Overrides
Gets or sets the ILayoutStage that routes self-loops.
Default Value
See Also
Defined in
Sets whether or not the ILayoutStage used for routing self-loops is activated.
Default Value
true.The stage that routes self-loops is activated.
See Also
Overrides
Gets a IDataAcceptor that can be used for temporarily overwriting the source group information used during the layout.
Remarks
See Also
Gets a IDataAcceptor that can overwrite the source port contraint temporarily used during the layout.
Remarks
See Also
Gets or sets the ILayoutStage that constrains the layout process to a subgraph of the input graph.
Default Value
See Also
Defined in
Gets or sets whether or not the ILayoutStage used for constraining the layout process to a subgraph of the input graph is activated.
Remarks
Default Value
false.The stage that constrains the input graph to a subgraph is deactivated.
See Also
Defined in
Gets a IDataAcceptor that can be used for temporarily overwriting the target group information used during the layout.
Remarks
See Also
Gets a IDataAcceptor that can overwrite the target port contraint temporarily used during the layout.
Remarks
See Also
Methods
Appends the given ILayoutStage to the layout pipeline.
Remarks
Parameters
A map of options to pass to the method.
- stage - ILayoutStage
- the ILayoutStage instance to be added
See Also
Defined in
Calculates a layout for the given graph and applies it directly to the graph.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
Arranges the given graph as a tree.
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Implements
Checks the sizes of the nodes to be non-zero.
Parameters
A map of options to pass to the method.
- g - LayoutGraph
- The graph to check.
Defined in
Creates a SubtreeShape for the given node that consists only of the bounds of this particular node.
Remarks
It may also include node labels or NodeHalos.
This method may be overridden to return a custom SubtreeShape for the given node.
Parameters
A map of options to pass to the method.
- node - YNode
- the given node
Returns
- ↪SubtreeShape
- a SubtreeShape instance
Returns a list of edges that need to be reversed in order to obtain a valid rooted and directed tree from the input graph.
Remarks
The root node of the tree is either a node marked by a IDataProvider registered with the graph with key SELECTED_ROOT_DP_KEY or is defined according to getRoot.
This method is called initially to calculate a rooted tree from the input graph. It may be overridden to apply a custom algorithm that determines which edges need to be reversed.
Returns
- ↪EdgeList
- a list of edges that need to be reversed
See Also
Deactivates all predefined ILayoutStages so that upon applyLayout only the layout algorithm will be executed.
See Also
Defined in
Returns the ITreeLayoutNodePlacer instance that is used for the placement of the local root node and the SubtreeShapes.
Remarks
The method may be overridden to return custom ITreeLayoutNodePlacer instances. It is possible to return a shared instance for multiple different nodes because the instances are not used after subsequent calls to this method.
The current implementation returns the ITreeLayoutNodePlacer defined by the IDataProvider registered with key NODE_PLACER_DP_KEY. It falls back to the default ITreeLayoutNodePlacer if there is no specific ITreeLayoutNodePlacer for the given node.
Parameters
A map of options to pass to the method.
- localRoot - YNode
- the root of the local subtree
Returns
- ↪ITreeLayoutNodePlacer
- the ITreeLayoutNodePlacer instance that places the subtree below the given local root node
See Also
Returns the IComparer<T> instance that will sort the outgoing edges connecting to the given node.
Remarks
The IComparer<T> can be null in case the initial edge order shall be used.
The method may be overridden to return custom IComparer<T> instances. It is possible to return a shared instance for multiple different nodes because the instances are not used after subsequent calls to this method.
The current implementation returns the IComparer<T> defined in the IDataProvider registered with key OUT_EDGE_COMPARER_DP_KEY. It falls back to the default IComparer<T> if there is no specific IComparer<T> for the given node.
Parameters
A map of options to pass to the method.
- localRoot - YNode
- the root of the local subtree
Returns
- ↪IComparer<any>
- the IComparer<T> or
nullthat sorts the outgoing edges of the given node
See Also
Returns the ITreeLayoutPortAssignment instance that places the ports of the connecting edges of the given node.
Remarks
The method may be overridden to return customized ITreeLayoutPortAssignment instances. It is possible to return a shared instance for multiple different nodes because the instances are not used after subsequent calls to this method.
The current implementation returns the ITreeLayoutPortAssignment defined by the IDataProvider registered with key OUT_EDGE_COMPARER_DP_KEY. It falls back to the default ITreeLayoutPortAssignment if there is no specific ITreeLayoutPortAssignment for the given node.
Parameters
A map of options to pass to the method.
- localRoot - YNode
- the root of the local subtree
Returns
- ↪ITreeLayoutPortAssignment
- the ITreeLayoutPortAssignment instance that assigns the ports of the edges at the given node
See Also
Returns an array of the nodes that will be laid out.
Remarks
The given node will be considered as the root of the tree. The order of the elements ensures that no parent is processed before one of its successors.
This method may be overridden to change the order in which the nodes (and their subtrees) are handled. However, it is important to keep the parents after the successors. Only siblings can change places.
Parameters
A map of options to pass to the method.
- root - YNode
- the node to be considered as root of the tree
Returns
- ↪YNode[]
- an array of nodes that will be laid out
Provides access to the SubtreeShape for the given node.
Remarks
The SubtreeShape contains information about the current extent and location of the subtree rooted at the node. It should only be modified during the layout of the parent node. Also, it won't be initialized before the layout of the corresponding subtree is calculated.
This method updates the SubtreeShape in layoutRoot.
Parameters
A map of options to pass to the method.
- localRoot - YNode
- the root of the subtree
Returns
- ↪SubtreeShape
- the SubtreeShape instance if it has already been calculated,
nullotherwise
Calculates the layout for the given root node and its subtrees.
Remarks
This method is invoked for each node in the tree exactly once. Thus, children are always handled before their parents. In this manner, the subtrees already have a layout and can be arranged with their parent.
To retrieve the shapes of the subtrees of all children of the local root, this method uses getSubtreeShape.
The method may be overridden to add configuration code.
Parameters
A map of options to pass to the method.
- localRoot - YNode
- the root of the subtree that whose layout is calculated
Returns
- ↪SubtreeShape
- the combined SubtreeShape of the local root node and all of its children and connecting edges
Prepends the given ILayoutStage to the layout pipeline.
Remarks
Parameters
A map of options to pass to the method.
- stage - ILayoutStage
- the ILayoutStage instance to be added
See Also
Defined in
Removes the given ILayoutStage from the layout pipeline.
Remarks
Parameters
A map of options to pass to the method.
- stage - ILayoutStage
- a ILayoutStage to be removed from the layout pipeline
See Also
Defined in
Reverses the direction of given edges.
Remarks
Parameters
A map of options to pass to the method.
- reversedEdges - EdgeList
- the edges that will be reversed
Fields
The input graph for which a layout is calculated.
Constants
A data provider key for defining the priority of critical edges.
Remarks
The layout algorithm tries to align each node pair that is connected by a critical edge (integer value > 0). This feature can, for example, be used for highlighting different edge paths that are important for a user. Conflicts between different critical edges are always resolved in favor of the higher priority.
This feature is only supported by the following ITreeLayoutNodePlacers:
| Domain | Edge | |
| Values | number | the positive priority for "critical" edges or 0 for "non-critical" edges |
See Also
Sample Graphs
A data provider key for retrieving descriptors for nodes in multi-parent structures.
Remarks
| Domain | YNode | the nodes that are part of a multi-parent structure |
| Values | MultiParentDescriptor | the descriptor for the multi-parent structure |
See Also
A data provider key for specifying a child node placer for each node.
| Domain | YNode | |
| Values | ITreeLayoutNodePlacer | the placement for the children of the node or null if the default node placer should be used |
See Also
A data provider key for specifying the comparator for the outgoing edges.
| Domain | YNode | |
| Values | IComparer<T> | the comparator to sort the outgoing edges of the node or null if the default comparator should be used |
See Also
A data provider key for assigning ports to nodes.
| Domain | YNode | |
| Values | ITreeLayoutPortAssignment | the assignment for all connecting ports at the node or null if the default assignment should be used |
See Also
A data provider key for marking the node that will be used as root node of the tree.
| Domain | YNode | |
| Values | boolean | true if the node should be considered as the root node of the tree, false otherwise |