com.yworks.yfiles.layout

Class RecursiveGroupLayout

java.lang.Object

com.yworks.yfiles.layout.AbstractLayoutStage

com.yworks.yfiles.layout.RecursiveGroupLayout

All Implemented Interfaces:

ILayoutAlgorithm, ILayoutStage

public class RecursiveGroupLayout
extends AbstractLayoutStage

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.

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.

All nodes other than the direct children are temporarily hidden. The layout algorithm performs two steps for each group node.

1. 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_DPKEY. 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.
2. Then RecursiveGroupLayout computes the final size of the group node using an implementation of IGroupBoundsCalculator. Customized IGroupBoundsCalculators can be specified using GroupBoundsCalculator. Aside from the resulting layout, this size is used in the following iteration.

After a layout is applied to all group nodes, the layout algorithm computes routes for the edges whose source node is located at a different hierarchy level than its target node. The edge routing algorithm for these so-called inter-edges can be customized.

Note that RecursiveGroupLayout can run without a core layout algorithm. In this case no layout is calculated, instead the group node bounds are merely adjusted to fit their respective contents.

Features

There are two alternatives for applying different layout styles to the contents of group nodes:

1. Mapping each group node to a corresponding layout algorithm by registering a IDataProvider with key GROUP_NODE_LAYOUT_DPKEY. The content of the hierarchy root is arranged with the core layout algorithm.
2. 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.

Field Summary

Fields

Modifier and Type	Field and Description
static NodeDpKey<ILayoutAlgorithm>	GROUP_NODE_LAYOUT_DPKEY A DataProvider key for arranging the content of each group node with an individual layout algorithm.
static ILayoutAlgorithm	NULL_LAYOUT A constant that represents a ILayoutAlgorithm implementation that does nothing.
static EdgeDpKey<Object>	SOURCE_SPLIT_ID_DPKEY A DataProvider key for assigning source split ids to edges connecting to group nodes.
static EdgeDpKey<Object>	TARGET_SPLIT_ID_DPKEY A DataProvider key for assigning target split ids to edges connecting to group nodes.

Constructor Summary

Constructors

Constructor and Description
RecursiveGroupLayout() Creates a new instance of RecursiveGroupLayout with an optional core layout algorithm.
RecursiveGroupLayout(ILayoutAlgorithm core) Creates a new instance of RecursiveGroupLayout with an optional core layout algorithm.
RecursiveGroupLayout(ILayoutAlgorithm core, IGroupBoundsCalculator gbc) Creates a new instance of RecursiveGroupLayout with default settings using the given layout algorithm and IGroupBoundsCalculator implementation.

Method Summary

Modifier and Type	Method and Description
void	applyLayout(LayoutGraph graph) 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.
IGroupBoundsCalculator	getGroupBoundsCalculator() Gets a IGroupBoundsCalculator which computes the sizes of all group nodes.
ILayoutAlgorithm	getInterEdgeRouter() Gets the current edge routing algorithm for handling inter-edges.
Object	getInterEdgesDpKey() Gets the key for marking the inter-edges to be routed.
boolean	isEmptyGroupsConsiderationEnabled() Gets whether empty group nodes are handled like group nodes with content or like normal nodes.
boolean	isFromSketchModeEnabled() Gets whether or not to consider the initial coordinates of the graph elements.
boolean	isPortCandidatesAutoAssignmentEnabled() Gets whether or not temporary PortCandidates are inserted to improve the routing of inter-edges.
boolean	isPortConstraintsReplacementEnabled() Gets whether or not PortConstraints of inter-edges are temporarily replaced by PortCandidates.
protected void	routeInterEdges(LayoutGraph graph, EdgeList interEdges) Reroutes the given inter-edges using the current edge routing algorithm.
void	setEmptyGroupsConsiderationEnabled(boolean value) Sets whether empty group nodes are handled like group nodes with content or like normal nodes.
void	setFromSketchModeEnabled(boolean value) Sets whether or not to consider the initial coordinates of the graph elements.
void	setGroupBoundsCalculator(IGroupBoundsCalculator value) Sets a IGroupBoundsCalculator which computes the sizes of all group nodes.
void	setInterEdgeRouter(ILayoutAlgorithm value) Sets the current edge routing algorithm for handling inter-edges.
void	setInterEdgesDpKey(Object value) Sets the key for marking the inter-edges to be routed.
void	setPortCandidatesAutoAssignmentEnabled(boolean value) Sets whether or not temporary PortCandidates are inserted to improve the routing of inter-edges.
void	setPortConstraintsReplacementEnabled(boolean value) Sets whether or not PortConstraints of inter-edges are temporarily replaced by PortCandidates.

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

applyLayoutCore, getCoreLayout, setCoreLayout

Methods inherited from class java.lang.Object

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

Field Detail

GROUP_NODE_LAYOUT_DPKEY

public static final NodeDpKey<ILayoutAlgorithm> GROUP_NODE_LAYOUT_DPKEY

A DataProvider key for arranging the content of each group node with an individual layout algorithm.

The specified layouter instance is applied to the content of the group node. To arrange the top level elements the core layout algorithm is used.

To leave the content of a group node unchanged, the group node can be associated with a layout algorithm which does not change the layout of the graph like NULL_LAYOUT.

If the IDataProvider returns null, 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 a layout algorithm.

See Also:

NULL_LAYOUT

NULL_LAYOUT

public static final ILayoutAlgorithm NULL_LAYOUT

A constant that represents a ILayoutAlgorithm implementation that does nothing.

This implementation can be assigned to group nodes to keep their content unchanged. The layout algorithm will still calculate the sizes of the group nodes.

SOURCE_SPLIT_ID_DPKEY

public static final EdgeDpKey<Object> SOURCE_SPLIT_ID_DPKEY

A DataProvider key for assigning source split ids to edges connecting to group nodes.

The edges will be aligned with edges that connect to the same group node and have the same split id at their source (preferably) or target.

Marking edges with split ids will only provide good results if HierarchicLayout is used as core layout algorithm. Also, the edges need to be routed directly from the content of a group to the group itself.

In case a core layout algorithm is used that cannot handle groups, it will fail if it needs to layout a graph containing an edge with a split id.

See Also:

TARGET_SPLIT_ID_DPKEY, HierarchicLayout, EdgeLayoutDescriptor.setDirectGroupContentEdgeRoutingEnabled(boolean)

TARGET_SPLIT_ID_DPKEY

public static final EdgeDpKey<Object> TARGET_SPLIT_ID_DPKEY

A DataProvider key for assigning target split ids to edges connecting to group nodes.

The edges will be aligned with edges that connect to the same group node and have the same split id at their source or target (preferably).

Marking edges with split ids will only provide good results if HierarchicLayout is used as core layout algorithm. Also, the edges need to be routed directly from the content of a group to the group itself.

In case a core layout algorithm is used that cannot handle groups, it will fail if it needs to layout a graph containing an edge with a split id.

See Also:

SOURCE_SPLIT_ID_DPKEY, HierarchicLayout, EdgeLayoutDescriptor.setDirectGroupContentEdgeRoutingEnabled(boolean)

Constructor Detail

RecursiveGroupLayout

public RecursiveGroupLayout()

Creates a new instance of RecursiveGroupLayout with an optional core layout algorithm.

RecursiveGroupLayout

public RecursiveGroupLayout(ILayoutAlgorithm core)

Creates a new instance of RecursiveGroupLayout with an optional core layout algorithm.

Parameters:

core - The layout algorithm that is applied in each recursion step.

RecursiveGroupLayout

public RecursiveGroupLayout(ILayoutAlgorithm core,
                            IGroupBoundsCalculator gbc)

Creates a new instance of RecursiveGroupLayout with default settings using the given layout algorithm and IGroupBoundsCalculator implementation.

Parameters:

core - the layout algorithm that is applied in each step of the recursion

gbc - the IGroupBoundsCalculator for calculating group sizes

Method Detail

applyLayout

public void applyLayout(LayoutGraph graph)

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.

Specified by:

applyLayout in interface ILayoutAlgorithm

Specified by:

applyLayout in class AbstractLayoutStage

Parameters:

graph - the input graph

getGroupBoundsCalculator

public IGroupBoundsCalculator getGroupBoundsCalculator()

Gets a IGroupBoundsCalculator which computes the sizes of all group nodes.

This IGroupBoundsCalculator is used each time after calculating the layout for a content graph.

Default Value:

The default value is MinimumSizeGroupBoundsCalculator

Returns:

the current IGroupBoundsCalculator instance

See Also:

setGroupBoundsCalculator(IGroupBoundsCalculator)

getInterEdgeRouter

public ILayoutAlgorithm getInterEdgeRouter()

Gets the current edge routing algorithm for handling inter-edges.

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:

The default value is null. Edges are routed as straight lines from source to target.

Returns:

the edge routing algorithm for inter-edges

See Also:

setInterEdgesDpKey(Object), setInterEdgeRouter(ILayoutAlgorithm)

getInterEdgesDpKey

public Object getInterEdgesDpKey()

Gets the key for marking the inter-edges to be routed.

The key should be used by the specified inter-edge routing algorithm to obtain the edges to be routed. This layouter automatically marks these edges and registers the IDataProvider using the specified key.

Throws:

IllegalArgumentException - if the specified key is null

Default Value:

The default value is LayoutKeys.AFFECTED_EDGES_DPKEY

Returns:

the inter edge selection key

See Also:

getInterEdgeRouter(), setInterEdgesDpKey(Object)

isEmptyGroupsConsiderationEnabled

public boolean isEmptyGroupsConsiderationEnabled()

Gets whether empty group nodes are handled like group nodes with content or like normal nodes.

If they are handled like other group nodes, RecursiveGroupLayout will resize them according to their (non-existing) content. This results in small empty group nodes. Handled like normal nodes, empty group nodes will keep their initial size.

Default Value:

The default value is true. Empty group nodes are resized.

Returns:

true if empty groups are treated like group nodes, false if they are treated like normal nodes

See Also:

setEmptyGroupsConsiderationEnabled(boolean)

isFromSketchModeEnabled

public boolean isFromSketchModeEnabled()

Gets whether or not to consider the initial coordinates of the graph elements.

When using the initial coordinates, RecursiveGroupLayout sets the coordinates of the nodes to their initial position before the corresponding layout algorithm is called.

This option should be enabled if RecursiveGroupLayout uses a layout algorithm that runs in From Sketch mode.

Default Value:

The default value is false. The initial coordinates of the nodes are not taken into account.

Returns:

true if the initial coordinates of the graph elements are considered, false otherwise

See Also:

setFromSketchModeEnabled(boolean)

isPortCandidatesAutoAssignmentEnabled

public boolean isPortCandidatesAutoAssignmentEnabled()

Gets whether or not temporary PortCandidates are inserted to improve the routing of inter-edges.

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.

Predefined PortCandidates are always satisfied depending on the used layout algorithm, even if this option is disabled.

Adding temporary PortCandidates will only have an effect if the layout algorithm supports them.

Default Value:

The default value is false. No temporary PortCandidates are added.

Returns:

true if temporary port candidates are inserted

See Also:

routeInterEdges(LayoutGraph, EdgeList), setInterEdgeRouter(ILayoutAlgorithm), PortCandidate, setPortCandidatesAutoAssignmentEnabled(boolean)

isPortConstraintsReplacementEnabled

public boolean isPortConstraintsReplacementEnabled()

Gets whether or not PortConstraints of inter-edges are temporarily replaced by PortCandidates.

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.

Predefined PortCandidates are always satisfied depending on the used layout algorithm, even if this option is disabled.

Temporarily replacing the PortConstraints will only have an effect if the layout algorithm supports PortCandidates.

Default Value:

The default value is true. Existing PortConstraints are temporarily replaced with corresponding PortCandidates.

Returns:

whether or not port constraints are replaced

See Also:

routeInterEdges(LayoutGraph, EdgeList), PortCandidate, setPortConstraintsReplacementEnabled(boolean)

routeInterEdges

protected void routeInterEdges(LayoutGraph graph,
                               EdgeList interEdges)

Reroutes the given inter-edges using the current edge routing algorithm.

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:

graph - the input graph

interEdges - the edges which traverse the boundary of a group node

See Also:

setPortCandidatesAutoAssignmentEnabled(boolean), setPortConstraintsReplacementEnabled(boolean), setInterEdgeRouter(ILayoutAlgorithm)

setEmptyGroupsConsiderationEnabled

public void setEmptyGroupsConsiderationEnabled(boolean value)

Sets whether empty group nodes are handled like group nodes with content or like normal nodes.

If they are handled like other group nodes, RecursiveGroupLayout will resize them according to their (non-existing) content. This results in small empty group nodes. Handled like normal nodes, empty group nodes will keep their initial size.

Default Value:

The default value is true. Empty group nodes are resized.

Parameters:

value - true if empty groups are treated like group nodes, false if they are treated like normal nodes

See Also:

isEmptyGroupsConsiderationEnabled()

setFromSketchModeEnabled

public void setFromSketchModeEnabled(boolean value)

Sets whether or not to consider the initial coordinates of the graph elements.

When using the initial coordinates, RecursiveGroupLayout sets the coordinates of the nodes to their initial position before the corresponding layout algorithm is called.

This option should be enabled if RecursiveGroupLayout uses a layout algorithm that runs in From Sketch mode.

Default Value:

The default value is false. The initial coordinates of the nodes are not taken into account.

Parameters:

value - true if the initial coordinates of the graph elements are considered, false otherwise

See Also:

isFromSketchModeEnabled()

setGroupBoundsCalculator

public void setGroupBoundsCalculator(IGroupBoundsCalculator value)

Sets a IGroupBoundsCalculator which computes the sizes of all group nodes.

This IGroupBoundsCalculator is used each time after calculating the layout for a content graph.

Default Value:

The default value is MinimumSizeGroupBoundsCalculator

Parameters:

value - the current IGroupBoundsCalculator instance

See Also:

getGroupBoundsCalculator()

setInterEdgeRouter

public void setInterEdgeRouter(ILayoutAlgorithm value)

Sets the current edge routing algorithm for handling inter-edges.

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:

The default value is null. Edges are routed as straight lines from source to target.

Parameters:

value - the edge routing algorithm for inter-edges

See Also:

setInterEdgesDpKey(Object), getInterEdgeRouter()

setInterEdgesDpKey

public void setInterEdgesDpKey(Object value)

Sets the key for marking the inter-edges to be routed.

The key should be used by the specified inter-edge routing algorithm to obtain the edges to be routed. This layouter automatically marks these edges and registers the IDataProvider using the specified key.

Throws:

IllegalArgumentException - if the specified key is null

Default Value:

The default value is LayoutKeys.AFFECTED_EDGES_DPKEY

Parameters:

value - the inter edge selection key

See Also:

getInterEdgeRouter(), getInterEdgesDpKey()

setPortCandidatesAutoAssignmentEnabled

public void setPortCandidatesAutoAssignmentEnabled(boolean value)

Sets whether or not temporary PortCandidates are inserted to improve the routing of inter-edges.

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.

Predefined PortCandidates are always satisfied depending on the used layout algorithm, even if this option is disabled.

Adding temporary PortCandidates will only have an effect if the layout algorithm supports them.

Default Value:

The default value is false. No temporary PortCandidates are added.

Parameters:

value - true if temporary port candidates are inserted

See Also:

routeInterEdges(LayoutGraph, EdgeList), setInterEdgeRouter(ILayoutAlgorithm), PortCandidate, isPortCandidatesAutoAssignmentEnabled()

setPortConstraintsReplacementEnabled

public void setPortConstraintsReplacementEnabled(boolean value)

Sets whether or not PortConstraints of inter-edges are temporarily replaced by PortCandidates.

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.

Predefined PortCandidates are always satisfied depending on the used layout algorithm, even if this option is disabled.

Temporarily replacing the PortConstraints will only have an effect if the layout algorithm supports PortCandidates.

Default Value:

The default value is true. Existing PortConstraints are temporarily replaced with corresponding PortCandidates.

Parameters:

value - whether or not port constraints are replaced

See Also:

routeInterEdges(LayoutGraph, EdgeList), PortCandidate, isPortConstraintsReplacementEnabled()