com.yworks.yfiles.layout.circular

Class CircularLayout

java.lang.Object

com.yworks.yfiles.layout.MultiStageLayout

com.yworks.yfiles.layout.circular.CircularLayout

All Implemented Interfaces:

ILayoutAlgorithm

public class CircularLayout
extends MultiStageLayout

This layout algorithm arranges graphs in a circular fashion.

Layout Style

The nodes are arranged in circles and stars which emphasize group and tree structures inside a graph. Circular layout algorithms find applications in many areas such as social networking, network management, WWW visualization, eCommerce, telecommunications. Circular layout with default settings Circular layout with LayoutStyle.SINGLE_CYCLE layout style

Concept

The layout algorithm performs three steps when calculating a circular arrangement for a graph:

1. It searches for partitions in the input graph depending on connectivity and on the given layout style. Considering each partition as a node, the resulting graph has a tree-like structure.
2. The partitions are laid out as circles using the selected partition style.
3. The algorithm delegates the layout calculation for the underlying tree (in which each node corresponds to a partition) to a specialized layout algorithm accessible by SingleCycleLayout or BalloonLayout. The partitions are moved to their final location.

Features

The layout algorithm places the nodes in circles that represent a partition. There are several ways to find partitions in the input graph. Which one is applied is defined using LayoutStyle.

The nodes in a partition can either lie on or in the interior of a circle. The placement of the nodes affects the compactness of the layout and can be specified using PartitionStyle.

Since edges are routed as straight lines, they may overlap with nodes or node labels. To resolve these overlaps, an edge routing algorithm (e.g. EdgeRouter or OrganicEdgeRouter) can be appended.

This layout algorithm supports edge bundling. In order to bundle the edges, the nodes of the graph are clustered in groups. Edge bundling is supported only if partition layout style is set to PartitionStyle.CYCLE and layout style is other than LayoutStyle.BCC_ISOLATED.

Field Summary

Fields

Modifier and Type	Field and Description
static NodeDpKey<Integer>	CIRCLE_ID_DPKEY A DataAcceptor key for publishing the final circle information For each node, the ID of the circle on which it was placed will be stored.
static NodeDpKey<Object>	CUSTOM_GROUPS_DPKEY A DataProvider key for defining custom node partitions The IDataProvider needs to provide a mapping from Nodes to unique Object IDs for each group of nodes.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	applyLayout(LayoutGraph graph) Calculates a circular layout for the given graph.
void	applyLayoutCore(LayoutGraph graph) Arranges the given graph in a circular fashion.
BalloonLayout	getBalloonLayout() Gets the BalloonLayout instance used for arranging multiple partitions.
EdgeBundling	getEdgeBundling() Gets the EdgeBundling instance that defines the settings of the edge bundling feature.
LayoutStyle	getLayoutStyle() Gets the global layout style for this layout algorithm.
int	getMaximumDeviationAngle() Gets the maximum deviation angle allowed for an edge.
PartitionStyle	getPartitionStyle() Gets the style for the arrangement of each partition.
SingleCycleLayout	getSingleCycleLayout() Gets the SingleCycleLayout instance used for laying out nodes on a single cycle.
boolean	isFromSketchModeEnabled() Gets whether or not to take the coordinates of the input diagram into account when arranging the nodes of the partitions and the partitions themselves.
boolean	isNodeLabelConsiderationEnabled() Gets whether or not the layout algorithm reserves space for node labels preventing possible overlaps.
boolean	isPlacingChildrenOnCommonRadiusEnabled() Gets whether or not, in the underlying tree, the children of a tree node are placed on a common radius.
void	setComponentLayoutEnabled(boolean value) Sets whether or not the ILayoutStage used for arranging the components of the graph is activated.
void	setFromSketchModeEnabled(boolean value) Sets whether or not to take the coordinates of the input diagram into account when arranging the nodes of the partitions and the partitions themselves.
void	setHideGroupsStageEnabled(boolean value) Sets whether or not the ILayoutStage used for hiding group nodes is activated.
void	setLayoutStyle(LayoutStyle value) Sets the global layout style for this layout algorithm.
void	setMaximumDeviationAngle(int value) Sets the maximum deviation angle allowed for an edge.
void	setNodeLabelConsiderationEnabled(boolean value) Sets whether or not the layout algorithm reserves space for node labels preventing possible overlaps.
void	setOrientationLayoutEnabled(boolean value) Sets whether or not the ILayoutStage that modifies the orientation of the layout is activated.
void	setPartitionStyle(PartitionStyle value) Sets the style for the arrangement of each partition.
void	setPlacingChildrenOnCommonRadiusEnabled(boolean value) Sets whether or not, in the underlying tree, the children of a tree node are placed on a common radius.
void	setSelfLoopRouterEnabled(boolean value) Sets whether or not the ILayoutStage used for routing self-loops is activated.

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

appendStage, checkNodeSize, disableAllStages, getComponentLayout, getHideGroupsStage, getLabeling, getLayoutOrientation, getOrientationLayout, getParallelEdgeRouter, getSelfLoopRouter, getSubgraphLayout, isComponentLayoutEnabled, isHideGroupsStageEnabled, isLabelingEnabled, isOrientationLayoutEnabled, isParallelEdgeRouterEnabled, isSelfLoopRouterEnabled, isSubgraphLayoutEnabled, prependStage, removeStage, setComponentLayout, setHideGroupsStage, setLabeling, setLabelingEnabled, setLayoutOrientation, setOrientationLayout, setParallelEdgeRouter, setParallelEdgeRouterEnabled, setSelfLoopRouter, setSubgraphLayout, setSubgraphLayoutEnabled

Methods inherited from class java.lang.Object

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

Field Detail

CIRCLE_ID_DPKEY

public static final NodeDpKey<Integer> CIRCLE_ID_DPKEY

A DataAcceptor key for publishing the final circle information

For each node, the ID of the circle on which it was placed will be stored.

If no IDataProvider is registered with this key, the circle information will be dropped.

CUSTOM_GROUPS_DPKEY

public static final NodeDpKey<Object> CUSTOM_GROUPS_DPKEY

A DataProvider key for defining custom node partitions

The IDataProvider needs to provide a mapping from Nodes to unique Object IDs for each group of nodes. These groups will form the circles in the layout.

See Also:

LayoutStyle.CUSTOM_GROUPS

Constructor Detail

CircularLayout

public CircularLayout()

Creates a new CircularLayout instance with the default settings.

Method Detail

applyLayout

public void applyLayout(LayoutGraph graph)

Calculates a circular layout for the given graph.

The given graph will not be copied during the layout process and the layout will be immediately applied to the given graph.

This method is not side effect free in the sense that the order of edges or nodes in the input graph may change during the layout process.

Specified by:

applyLayout in interface ILayoutAlgorithm

Overrides:

applyLayout in class MultiStageLayout

Parameters:

graph - the input graph

See Also:

MultiStageLayout.appendStage(ILayoutStage), MultiStageLayout.prependStage(ILayoutStage), MultiStageLayout.applyLayoutCore(LayoutGraph)

applyLayoutCore

public void applyLayoutCore(LayoutGraph graph)

Arranges the given graph in a circular fashion.

Specified by:

applyLayoutCore in class MultiStageLayout

Parameters:

graph - the input graph

getBalloonLayout

public BalloonLayout getBalloonLayout()

Gets the BalloonLayout instance used for arranging multiple partitions.

Configuring this layout algorithm affects the arrangement of the partitions within the overall layout.

Returns:

the BalloonLayout instance that arranges the partitions

See Also:

setLayoutStyle(LayoutStyle)

getEdgeBundling

public EdgeBundling getEdgeBundling()

Gets the EdgeBundling instance that defines the settings of the edge bundling feature.

The specified EdgeBundling defines global bundling properties. Settings for individual edges can be defined by assigning an EdgeBundleDescriptor to an edge using a IDataProvider registered with key EdgeBundling.EDGE_BUNDLE_DESCRIPTOR_DPKEY.

To enable bundling for all edges, set a default bundle descriptor which has bundling enabled.

When using layout style LayoutStyle.CUSTOM_GROUPS, edge bundles between different groups might in some cases intersect with other groups.

Edge bundling is supported only if partition layout style is set to PartitionStyle.CYCLE and layout style is other than LayoutStyle.BCC_ISOLATED.

Returns:

the EdgeBundling instance defining the edge bundling setup

getLayoutStyle

public LayoutStyle getLayoutStyle()

Gets the global layout style for this layout algorithm.

Throws:

IllegalArgumentException - if an unknown layout style is set

Default Value:

The default value is LayoutStyle.BCC_COMPACT

Returns:

one of the predefined layout styles

See Also:

setLayoutStyle(LayoutStyle)

getMaximumDeviationAngle

public int getMaximumDeviationAngle()

Gets the maximum deviation angle allowed for an edge.

The deviation angle for an edge is the difference between its optimal angle away from the parent cycle and its actual angle.

Using a small maximum deviation angle may significantly increase the length of the edges. The same holds if a small preferred child wedge is set on the used balloon layout algorithm.

Default Value:

The default value is 90.

Returns:

the maximum deviation angle given in degrees

See Also:

setMaximumDeviationAngle(int)

getPartitionStyle

public PartitionStyle getPartitionStyle()

Gets the style for the arrangement of each partition.

Throws:

IllegalArgumentException - if an unknown style is given

Default Value:

The default value is PartitionStyle.CYCLE

Returns:

one of the predefined partition styles

See Also:

setPartitionStyle(PartitionStyle)

getSingleCycleLayout

public SingleCycleLayout getSingleCycleLayout()

Gets the SingleCycleLayout instance used for laying out nodes on a single cycle.

Configuring this layout algorithm only affects layouts with only one partition.

Returns:

the SingleCycleLayout instance that handles layouts with only one partition

See Also:

setLayoutStyle(LayoutStyle)

isFromSketchModeEnabled

public boolean isFromSketchModeEnabled()

Gets whether or not to take the coordinates of the input diagram into account when arranging the nodes of the partitions and the partitions themselves.

If enabled:

• For complex partitions (those consisting of more than one node), the layout algorithm tries to keep peripheral nodes and maintain their circular order around the center of the disk/circle. Other partitions that connect to this node are moved accordingly, if possible.
• For multiple partitions that connect to the same node, the layout algorithm tries to keep their circular order around this node. This only works as expected for LayoutStyle.BCC_COMPACT as layout style, since otherwise the underlying tree structure is not well defined.

Switching between different layout styles or partition styles can lead to unexpected results.

Default Value:

The default value is false. The layout algorithm does not consider the initial coordinates of the nodes.

Returns:

true if the initial coordinates of the nodes are used, false otherwise

See Also:

setFromSketchModeEnabled(boolean)

isNodeLabelConsiderationEnabled

public boolean isNodeLabelConsiderationEnabled()

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

Nodes get temporarily enlarged such that they contain their labels.

This might result in layouts that need much space.

This option only works correctly if the layout orientation is set to LayoutOrientation.TOP_TO_BOTTOM (which is the default). Changing the layout orientation for an undirected layout algorithm like the CircularLayout doesn't make sense.

Default Value:

The default value is false. Node labels are not taken into account.

Returns:

true if labels are considered, false otherwise.

See Also:

setNodeLabelConsiderationEnabled(boolean)

isPlacingChildrenOnCommonRadiusEnabled

public boolean isPlacingChildrenOnCommonRadiusEnabled()

Gets whether or not, in the underlying tree, the children of a tree node are placed on a common radius.

Disabling this feature may produce more compact layout results.

Default Value:

The default value is true. Children are placed on a common radius.

Returns:

true if a common radius is used, false otherwise

See Also:

setPlacingChildrenOnCommonRadiusEnabled(boolean)

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

CircularLayout 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

setFromSketchModeEnabled

public void setFromSketchModeEnabled(boolean value)

Sets whether or not to take the coordinates of the input diagram into account when arranging the nodes of the partitions and the partitions themselves.

If enabled:

• For complex partitions (those consisting of more than one node), the layout algorithm tries to keep peripheral nodes and maintain their circular order around the center of the disk/circle. Other partitions that connect to this node are moved accordingly, if possible.
• For multiple partitions that connect to the same node, the layout algorithm tries to keep their circular order around this node. This only works as expected for LayoutStyle.BCC_COMPACT as layout style, since otherwise the underlying tree structure is not well defined.

Switching between different layout styles or partition styles can lead to unexpected results.

Default Value:

The default value is false. The layout algorithm does not consider the initial coordinates of the nodes.

Parameters:

value - true if the initial coordinates of the nodes are used, false otherwise

See Also:

isFromSketchModeEnabled()

setHideGroupsStageEnabled

public void setHideGroupsStageEnabled(boolean value)

Sets whether or not the ILayoutStage used for hiding group nodes is activated.

Overrides:

setHideGroupsStageEnabled in class MultiStageLayout

CircularLayout cannot handle group nodes. Disabling HideGroupsStage will lead to errors during execution.

Default Value:

The default value is true. The stage responsible for hiding group nodes is activated.

Parameters:

value - true if the stage used for hiding group nodes is activated, false otherwise

See Also:

MultiStageLayout.isHideGroupsStageEnabled(), MultiStageLayout.setHideGroupsStage(ILayoutStage), HideGroupsStage

setLayoutStyle

public void setLayoutStyle(LayoutStyle value)

Sets the global layout style for this layout algorithm.

Throws:

IllegalArgumentException - if an unknown layout style is set

Default Value:

The default value is LayoutStyle.BCC_COMPACT

Parameters:

value - one of the predefined layout styles

See Also:

getLayoutStyle()

setMaximumDeviationAngle

public void setMaximumDeviationAngle(int value)

Sets the maximum deviation angle allowed for an edge.

The deviation angle for an edge is the difference between its optimal angle away from the parent cycle and its actual angle.

Using a small maximum deviation angle may significantly increase the length of the edges. The same holds if a small preferred child wedge is set on the used balloon layout algorithm.

Default Value:

The default value is 90.

Parameters:

value - the maximum deviation angle given in degrees

See Also:

getMaximumDeviationAngle()

setNodeLabelConsiderationEnabled

public void setNodeLabelConsiderationEnabled(boolean value)

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

Nodes get temporarily enlarged such that they contain their labels.

This might result in layouts that need much space.

This option only works correctly if the layout orientation is set to LayoutOrientation.TOP_TO_BOTTOM (which is the default). Changing the layout orientation for an undirected layout algorithm like the CircularLayout doesn't make sense.

Default Value:

The default value is false. Node labels are not taken into account.

Parameters:

value - true if labels are considered, false otherwise.

See Also:

isNodeLabelConsiderationEnabled()

setOrientationLayoutEnabled

public void setOrientationLayoutEnabled(boolean value)

Sets whether or not the ILayoutStage that modifies the orientation of the layout is activated.

Overrides:

setOrientationLayoutEnabled in class MultiStageLayout

If the current layout orientation is LayoutOrientation.TOP_TO_BOTTOM, the orientation of the layout will not be modified.

Based on the undirected layout style, disabling OrientationLayout has no significant effect.

Default Value:

The default value is true. The orientation ILayoutStage is activated.

Parameters:

value - true if the stage that modifies the orientation is activated, false otherwise

See Also:

MultiStageLayout.isOrientationLayoutEnabled(), MultiStageLayout.setOrientationLayout(ILayoutStage), MultiStageLayout.setLayoutOrientation(com.yworks.yfiles.layout.LayoutOrientation), OrientationLayout

setPartitionStyle

public void setPartitionStyle(PartitionStyle value)

Sets the style for the arrangement of each partition.

Throws:

IllegalArgumentException - if an unknown style is given

Default Value:

The default value is PartitionStyle.CYCLE

Parameters:

value - one of the predefined partition styles

See Also:

getPartitionStyle()

setPlacingChildrenOnCommonRadiusEnabled

public void setPlacingChildrenOnCommonRadiusEnabled(boolean value)

Sets whether or not, in the underlying tree, the children of a tree node are placed on a common radius.

Disabling this feature may produce more compact layout results.

Default Value:

The default value is true. Children are placed on a common radius.

Parameters:

value - true if a common radius is used, false otherwise

See Also:

isPlacingChildrenOnCommonRadiusEnabled()

setSelfLoopRouterEnabled

public void setSelfLoopRouterEnabled(boolean value)

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

Overrides:

setSelfLoopRouterEnabled in class MultiStageLayout

CircularLayout 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