This layout algorithm recursively traverses a hierarchically organized graph in a bottom-up fashion and applies a specified layout algorithm to the contents (direct children) of each group node.
Remarks
Layout Style
The way a graph is arranged depends on the layout algorithms which are applied to the different group nodes. RecursiveGroupLayout is able to produce different layout styles for the content of each group node.
This layout algorithm can be either applied if a layout algorithm cannot handle grouped graphs by itself or if the content of (some) group nodes should be arranged differently.
Concept
RecursiveGroupLayout uses a hierarchy tree representation of the grouped graph in which the content nodes are the children of their containing group node. That way, it can traverse the tree recursively while arranging only the direct children of each group node. The layout algorithm starts by arranging the leaves in the hierarchy tree, then works its way up to the root computing the layout for each group node in the tree.
A) Group Handling
All nodes other than the direct children are temporarily hidden. The layout algorithm performs two steps for each group node.- It arranges the direct children using either the core layout algorithm or a special layout algorithm retrieved from a IDataProvider registered with GROUP_NODE_LAYOUT_DP_KEY. The content of group nodes among the children is already arranged at this time and will be ignored. These group nodes are handled like normal nodes with a size that encloses the content.
The following two special cases should be considered. If
nullis specified as layout algorithm for a group, the recursion will be disabled and the group is handled non-recursively: the group itself and its content is arranged by the algorithm specified for the nearest ancestor which has a non-nullalgorithm mapped to it. Importantly, this must be distinguished from the second case where the layout of the group content should remain unchanged. This is achieved when the group is associated with NULL_LAYOUT as responsible layout algorithm (or any another algorithm that does not change the layout). - Then RecursiveGroupLayout computes the final size of the group node using an implementation of ILayoutGroupBoundsCalculator. Customized ILayoutGroupBoundsCalculators can be specified using groupBoundsCalculator. Aside from the resulting layout, this size is used in the following iteration.
B) Top-Level Hierarchy
After a layout is applied to all group nodes, the layout algorithm uses the core layout algorithm to arrange the top level hierarchy. Note that RecursiveGroupLayout can run without a core layout. In this case no layout is calculated for the top level hierarchy. Still, for group nodes with a non-null algorithm, the bounds are adjusted to fit their respective contents.
C) Inter-Edge Routing
Finally, routes for the edges whose source node is located at a different hierarchy level than its target node are computed. The edge routing algorithm for these so-called inter-edges can be customized.
Features
There are two alternatives for applying different layout styles to the contents of group nodes:
- Mapping each group node to a corresponding layout algorithm by registering a IDataProvider with key GROUP_NODE_LAYOUT_DP_KEY. The content of the hierarchy root is arranged with the core layout algorithm.
- Using LayoutMultiplexer as core layout algorithm.
Since RecursiveGroupLayout delegates the actual arrangement of the graph to other layout algorithms, it will support the same features as the currently used layout algorithm.
The improvement of the routing of inter-edges is based on the insertion of PortCandidates or the conversion of PortConstraints into PortCandidates. Hence, they only work well if the applied layout algorithm supports PortCandidates.
This algorithm also provides a From Sketch mode that should be activated if the applied layout algorithm runs in From Sketch mode, too. Otherwise, the initial coordinates may not be considered correctly.
It is also possible to apply individual layout styles to different sub-graphs using this algorithm without actually defining group nodes: Use TemporaryGroupNodeInsertionStage and specify RecursiveGroupLayout as its core layout algorithm. The stage allows to define sub-graphs which are internally enclosed by a temporary group node. To assign a specific ILayoutAlgorithm instance for a temporary group, specify the desired ILayoutAlgorithm in the TemporaryGroupDescriptor's property recursiveGroupLayoutAlgorithm. It is then not necessary to use key GROUP_NODE_LAYOUT_DP_KEY.
Default Values of Properties
| considerEmptyGroups | true | Empty group nodes are resized. |
| fromSketchMode | false | The initial coordinates of the nodes are not taken into account. |
| groupBoundsCalculator | MinimumSizeGroupBoundsCalculator | |
| interEdgeRouter | null | Edges are routed as straight lines from source to target. |
| interEdgesDpKey | AFFECTED_EDGES_DP_KEY |
Type Details
- yfiles module
- layout-core
- yfiles-umd modules
- All layout modules, view-layout-bridge
- Legacy UMD name
- yfiles.layout.RecursiveGroupLayout
See Also
Constructors
RecursiveGroupLayout
(coreLayout?: ILayoutAlgorithm, groupBoundsCalculator?: ILayoutGroupBoundsCalculator)Creates a new instance of RecursiveGroupLayout with default settings using the given layout algorithm and ILayoutGroupBoundsCalculator implementation.
Remarks
null, the MinimumSizeGroupBoundsCalculator will be used instead.Parameters
A map of options to pass to the method.
- coreLayout - ILayoutAlgorithm
- the layout algorithm that is applied in each step of the recursion
- groupBoundsCalculator - ILayoutGroupBoundsCalculator
- the ILayoutGroupBoundsCalculator for calculating group sizes
- fromSketchMode - boolean
Whether or not to consider the initial coordinates of the graph elements. This option sets the fromSketchMode property on the created object.
- autoAssignPortCandidates - boolean
Whether or not temporary PortCandidates are inserted to improve the routing of inter-edges. This option sets the autoAssignPortCandidates property on the created object.
- replacePortConstraints - boolean
Whether or not PortConstraints of inter-edges are temporarily replaced by PortCandidates. This option sets the replacePortConstraints property on the created object.
- considerEmptyGroups - boolean
Whether empty group nodes are handled like group nodes with content or like normal nodes. This option sets the considerEmptyGroups property on the created object.
- interEdgeRouter - ILayoutAlgorithm
The current edge routing algorithm for handling inter-edges. This option sets the interEdgeRouter property on the created object.
- interEdgesDpKey - Object
The key for marking the inter-edges to be routed. This option sets the interEdgesDpKey property on the created object.
Properties
Gets or sets whether or not temporary PortCandidates are inserted to improve the routing of inter-edges.
Remarks
If enabled, RecursiveGroupLayout will insert PortCandidates for all inter-edges that cross a group node border. Those PortCandidates are located at the relative position of the real source/target node. Inter-edges that connect to such PortCandidates will be routed when the layout of the containing group node is calculated and will not be rerouted later. This may produce more suitable edge routes but cannot prevent edges from crossing nodes.
Without temporary or user specified PortCandidates, inter-edges will always end at the border/center of the corresponding group node. Thus, they are rerouted afterwards using an edge routing algorithm.
Default Value
false.No temporary
See Also
Sample Graphs
Gets or sets whether empty group nodes are handled like group nodes with content or like normal nodes.
Remarks
Default Value
true.Empty group nodes are resized.
Sample Graphs
Gets or sets the core layout algorithm that is wrapped by this stage.
Gets or sets whether or not to consider the initial coordinates of the graph elements.
Remarks
Default Value
false.The initial coordinates of the nodes are not taken into account.
Gets or sets a ILayoutGroupBoundsCalculator which computes the sizes of all group nodes.
Remarks
Default Value
Gets or sets the current edge routing algorithm for handling inter-edges.
Remarks
During layout, edges that connect from outside a group node to the content inside (inter-edges) are temporarily connected to the group node itself. Hence, these edges have to be routed after restoring the original graph structure using this edge routing algorithm.
It is required that a suitable selection key is specified. The same selection key must be used for setting the sphere of action for the edge router.
Default Value
null.Edges are routed as straight lines from source to target.
See Also
Gets or sets the key for marking the inter-edges to be routed.
Remarks
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if the specified key is
null
See Also
Gets or sets whether or not PortConstraints of inter-edges are temporarily replaced by PortCandidates.
Remarks
If disabled, inter-edges will always end at the border/center of the corresponding group node, even if those edges have port constraints. Thus, they are rerouted later without considering the constraint. Enabling this settings may produce more suitable edge routes but cannot prevent edges from crossing nodes.
Port candidates are automatically redirected to their original location. Hence, enabling this option may produce more suitable edge routes if the layout algorithm applied to the content of a group node can handle port candidates.
Default Value
true.Existing
See Also
Methods
Invokes a recursive traversal through the grouping hierarchy of the given graph during which the specified layout algorithms are applied to the content of the groups.
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
Invokes the layout process of the core layout algorithm.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Defined in
Reroutes the given inter-edges using the current edge routing algorithm.
Remarks
This method is called after calculating the overall layout when the positions of all nodes and normal edges are fixed.
If no inter-edge router is specified, this method resets the path of all inter-edges that don't connect to the proper location within the group. This may happen for inter-edges without PortCandidates or if the applied layout algorithm doesn't support such constraints.
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
- interEdges - EdgeList
- the edges which traverse the boundary of a group node
See Also
Constants
A data provider key for arranging the content of each group node with an individual layout algorithm.
Remarks
The specified layout algorithm instance is applied to the content of the group node. To arrange the top level elements the core layout algorithm is used.
The core layout is also applied to group nodes if there is no IDataProvider registered. Importantly, this must be distinguished from the case that there is a provider but it returns null for a group. Then, RecursiveGroupLayout handles the corresponding group node non-recursively. The group node and its content is arranged using the layout algorithm instance specified for the nearest ancestor of the group node which is associated with an algorithm.
| Domain | YNode | the group nodes of the graph |
| Values | ILayoutAlgorithm | the layout algorithm to arrange the content of a group node |
See Also
A data provider key for specifying a local partition grid for each group node.
Remarks
Each recursively handled group node can get its own local PartitionGrid. The grid is then valid for the child nodes of the group and only visible for the layout algorithm that is responsible for the group's content. Thus, to properly consider the grid it is required that the responsible algorithm supports the partition grid structure.
The mapping of the nodes to the partition cells is still defined by a single IDataProvider registered with the graph with key PARTITION_CELL_ID_DP_KEY. When creating the cell id it is important to call the creation method on the correct partition grid instance.
In addition to the local partition grids it is also allowed to have a global grid which is defined as usual via key PARTITION_GRID_DP_KEY. This grid is handled by the core layout algorithm responsible for the top-level hierarchy.
| Domain | YNode | the group nodes of the graph |
| Values | PartitionGrid | the group's local partition grid |
A constant that represents a ILayoutAlgorithm implementation that does nothing.
Remarks
A data provider key for assigning source split ids to edges connecting to group nodes.
Remarks
| Domain | Edge | the edge to align |
| Values | Object | an id to mark the source of the edge |
See Also
Sample Graphs
A data provider key for assigning target split ids to edges connecting to group nodes.
Remarks
| Domain | Edge | the edge to align |
| Values | Object | an id to mark the target of the edge |