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 an ILayoutAlgorithm 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 coreLayout or a special layout algorithm defined using the layout data property groupNodeLayouts. 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 FIX_CONTENT_LAYOUT as responsible layout algorithm (or any other 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 coreLayout 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
To apply different layout styles to the contents of group nodes, it is required to map each group node to a corresponding ILayoutAlgorithm via groupNodeLayouts. The content of the hierarchy root is arranged with the coreLayout.
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 EdgePortCandidates. Hence, they only work well if the applied layout algorithm supports EdgePortCandidates.
This algorithm also provides a fromSketchMode 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 TemporaryGroupInsertionStage 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 groupNodeLayouts.
Default Values of Properties
| considerEmptyGroups | false | Empty group nodes are not resized. |
| fromSketchMode | false | The initial coordinates of the nodes are not taken into account. |
| groupBoundsCalculator | GroupBoundsCalculator | |
| interEdgeRouter | null | Edges are routed as straight lines from source to target. |
Type Details
- yFiles module
- algorithms
Constructors
RecursiveGroupLayout
(coreLayout?: ILayoutAlgorithm, groupBoundsCalculator?: ILayoutGroupBoundsCalculator)Creates a new instance of RecursiveGroupLayout.
Parameters
A map of options to pass to the method.
- coreLayout - ILayoutAlgorithm
- The layout algorithm that is applied in each step of the recursion. The default value is
null. - groupBoundsCalculator - ILayoutGroupBoundsCalculator
- An optional ILayoutGroupBoundsCalculator for calculating group sizes. The default value is GroupBoundsCalculator.
- 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 LayoutPortCandidates are inserted to improve the routing of inter-edges. This option sets the autoAssignPortCandidates 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.
- enabled - boolean
Properties
Gets or sets whether or not temporary LayoutPortCandidates are inserted to improve the routing of inter-edges.
Remarks
If enabled, RecursiveGroupLayout will insert LayoutPortCandidates for all inter-edges that cross a group node border. Those LayoutPortCandidates are located at the relative position of the real source/target node. Inter-edges that connect to such LayoutPortCandidates 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 LayoutPortCandidates, 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
Property Value
true if temporary port candidates are insertedSee Also
Sample Graphs
Gets or sets whether empty group nodes are handled like group nodes with content or like normal nodes.
Remarks
Default Value
false.Empty group nodes are not resized.
Property Value
true if empty groups are treated like group nodes, false if they are treated like normal nodesSample Graphs
Gets or sets the core ILayoutAlgorithm that is wrapped by this stage.
Gets or sets a value that determines whether this stage should do anything but execute the coreLayout.
Remarks
By default, when constructed, stages should be enabled. Users may disable a stage's functionality by setting this property to false.
Stages that can guarantee that the graph will not change can choose to not even execute the coreLayout when disabled.
Implements
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.
Property Value
true if the initial coordinates of the graph elements are considered, false otherwiseGets or sets a ILayoutGroupBoundsCalculator which computes the sizes of all group nodes.
Remarks
Default Value
Property Value
Gets or sets the current edge routing algorithm for handling inter-edges.
Remarks
Default Value
null.Edges are routed as straight lines from source to target.
Property Value
Methods
Implementation of the ILayoutAlgorithm interface and main entry point for the layout calculation.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- The graph to apply the layout to.
Implements
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
Implements
createLayoutData
(graph: LayoutGraph) : RecursiveGroupLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the RecursiveGroupLayout.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the graph that determines the generic type arguments of the created layout data
Returns
- ↪RecursiveGroupLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>
- an instance of layout data that can be used to perform item-specific configurations for the given RecursiveGroupLayout.
Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the RecursiveGroupLayout.
Remarks
Parameters
A map of options to pass to the method.
- graph - IGraph
- the graph that determines the generic type arguments of the created layout data
Returns
- ↪RecursiveGroupLayoutData<INode,IEdge,ILabel,ILabel>
- an instance of layout data that can be used to perform item-specific configurations for the given RecursiveGroupLayout.
LayoutExecutor type is available at runtime.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 LayoutPortCandidates 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 - IEnumerable<LayoutEdge>
- the edges which traverse the boundary of a group node
See Also
Constants
A constant that represents a ILayoutAlgorithm implementation that does nothing.
Remarks
See Also
A constant that represents a ILayoutAlgorithm implementation that does nothing.
Remarks
See Also
A data key for arranging the content of each group node with an individual layout algorithm.
Remarks
The specified ILayoutAlgorithm instance is applied to the content of the group node. To arrange the top level elements the coreLayout is used.
The core layout is also applied to group nodes if there is no IMapper<K,V> 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 ILayoutAlgorithm instance specified for the nearest ancestor of the group node which is associated with an algorithm.
See Also
A constant that represents a ILayoutAlgorithm implementation that delegates to the coreLayout.
Remarks
This implementation can be assigned to group nodes to specify that they should not be handled recursively. In this case, the marked group node handled by this stage's coreLayout as is. The core layout must therefore be able to handle group nodes.
This constant is functionally equivalent to marking a group node with the value null or not marking it at all. It can be used to explicitly specify that the default behaviour is intended.
See Also
A data key for assigning source split ids to edges connecting to group nodes.
Remarks
See Also
Sample Graphs
A data key for assigning target split ids to edges connecting to group nodes.