com.yworks.yfiles.layout

Class ComponentLayout

java.lang.Object

com.yworks.yfiles.layout.AbstractLayoutStage

com.yworks.yfiles.layout.ComponentLayout

All Implemented Interfaces:

ILayoutAlgorithm, ILayoutStage

Direct Known Subclasses:

IsolatedGroupComponentLayout

public class ComponentLayout
extends AbstractLayoutStage

A ComponentLayout arranges the connected components of a graph.

Layout Style

The components can be arranged using different styles. All styles except ComponentArrangementStyles.NONE place the components without overlaps.

Layout with orthogonal components using ComponentArrangementStyles.MULTI_ROWS_COMPACT

Concept

ComponentLayout is a ILayoutStage that can wrap another layout algorithm. That way, it allows handling disconnected graphs for the wrapped core layout algorithm.

The following steps outline the concept of ComponentLayout:

1. Determine the connected components of the graph
2. Hide all graph components
3. Apply the following steps to each component separately
4. Unhide all graph components
5. Optionally arrange the components

Features

To arrange the subgraphs of the components, ComponentLayout uses the specified core layout algorithm. If there is no core layout algorithm specified, it will keep the locations in the subgraph and arrange the components as they are.

Hierarchically grouped graphs are handled in a special way. The contents of a group node will always belong to the same component as the group node itself. To change that behavior grouping can be disabled.

By default, the components consist of the connected nodes in a graph. To choose custom subgraphs to form components, register a IDataProvider with COMPONENT_ID_DPKEY and assign component IDs to the nodes.

See Also:

MultiStageLayout

Field Summary

Fields

Modifier and Type	Field and Description
static NodeDpKey<Boolean>	AFFECTED_COMPONENTS_DPKEY A DataProvider key for specifying which nodes should be arranged If no IDataProvider is registered with this key, all components will be laid out by the core layout algorithm.
static NodeDpKey<Comparable>	COMPONENT_ID_DPKEY A DataProvider key for specifying custom graph components

Constructor Summary

Constructors

Constructor and Description
ComponentLayout() Creates a new ComponentLayout instance with an optional core layout algorithm.
ComponentLayout(ILayoutAlgorithm coreLayouter) Creates a new ComponentLayout instance with an optional core layout algorithm.

Method Summary

Modifier and Type	Method and Description
void	applyLayout(LayoutGraph graph) Delegates the layout calculation for each component separately to the core layout algorithm and optionally arranges the components.
protected void	arrangeComponents(LayoutGraph graph, NodeList[] nodes, EdgeList[] edges, YRectangle[] bbox, Rectangle2D[] boxes) Produces a component graph layout.
protected void	arrangeFields(LayoutGraph graph, NodeList[] nodes, EdgeList[] edges, YRectangle[] bbox, Rectangle2D[] boxes, boolean circular, boolean fill, boolean fromSketch) Arranges the bounding boxes of the components.
protected Rectangle2D	calculateBounds(LayoutGraph graph) Calculates the bounding box of a graph component including NodeHalos.
protected int	findGraphComponents(LayoutGraph graph, INodeMap compNumber) Determines which nodes belong to the same graph component.
double	getComponentSpacing() Gets the distance between the bounding boxes of the components.
double	getGridSpacing() Gets the current grid spacing.
YDimension	getPreferredSize() Gets the preferred size of the layout.
ComponentArrangementStyles	getStyle() Gets how the components are arranged.
boolean	isComponentArrangementEnabled() Gets whether or not the separately arranged components of the input graph should be arranged relative to each other.
boolean	isGroupingConsiderationEnabled() Gets whether or not grouping information bound to the graph should be considered when determining the graph components.
boolean	isLabelConsiderationEnabled() Gets whether or not to take node and edge labels into account when calculating the bounding box of the graph components.
void	setComponentArrangementEnabled(boolean value) Sets whether or not the separately arranged components of the input graph should be arranged relative to each other.
void	setComponentSpacing(double value) Sets the distance between the bounding boxes of the components.
void	setGridSpacing(double value) Sets the current grid spacing.
void	setGroupingConsiderationEnabled(boolean value) Sets whether or not grouping information bound to the graph should be considered when determining the graph components.
void	setLabelConsiderationEnabled(boolean value) Sets whether or not to take node and edge labels into account when calculating the bounding box of the graph components.
protected void	setOrigin(LayoutGraph graph, NodeList nodes, EdgeList edges, YPoint origin, YRectangle rectangle) Moves the subgraph containing the given nodes and edges to the specified origin.
void	setPreferredSize(YDimension value) Sets the preferred size of the layout.
void	setStyle(ComponentArrangementStyles value) Sets how the components are arranged.

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

AFFECTED_COMPONENTS_DPKEY

public static final NodeDpKey<Boolean> AFFECTED_COMPONENTS_DPKEY

A DataProvider key for specifying which nodes should be arranged

If no IDataProvider is registered with this key, all components will be laid out by the core layout algorithm.

Components will only be arranged if at least one of the nodes that make up the component is marked.

COMPONENT_ID_DPKEY

public static final NodeDpKey<Comparable> COMPONENT_ID_DPKEY

A DataProvider key for specifying custom graph components

Constructor Detail

ComponentLayout

public ComponentLayout()

Creates a new ComponentLayout instance with an optional core layout algorithm.

ComponentLayout

public ComponentLayout(ILayoutAlgorithm coreLayouter)

Creates a new ComponentLayout instance with an optional core layout algorithm.

Parameters:

coreLayouter - The core layout algortihm.

Method Detail

applyLayout

public void applyLayout(LayoutGraph graph)

Delegates the layout calculation for each component separately to the core layout algorithm and optionally arranges the components.

Specified by:

applyLayout in interface ILayoutAlgorithm

Specified by:

applyLayout in class AbstractLayoutStage

Parameters:

graph - the input graph

arrangeComponents

protected void arrangeComponents(LayoutGraph graph,
                                 NodeList[] nodes,
                                 EdgeList[] edges,
                                 YRectangle[] bbox,
                                 Rectangle2D[] boxes)

Produces a component graph layout.

This method is called by applyLayout(LayoutGraph) in case component arrangement is enabled. It moves the graph's components such that their bounding boxes do not overlap. Subclasses may want to override this method to introduce custom component arrangement styles.

Depending on the chosen arrangement strategy, this layout algorithm takes the ratio of the overall layout area into account. ComponentArrangementStyles.NONE, ComponentArrangementStyles.SINGLE_ROW and ComponentArrangementStyles.SINGLE_COLUMN are excluded.

Parameters:

graph - the input graph

nodes - the nodes of the components; the i-th list contains the nodes of the i-th component

edges - the edges of the components; the i-th list contains the edges of the i-th component

bbox - the bounds of the components; the i-th rectangle describes the bounding box of the i-th component

boxes - the extended bounds of the components; the i-th rectangle describes the bounding box of the i-th component extended by the spacing between components. The method arranges these boxes in such a way that they do not overlap. Then, the i-th graph component must be placed inside the i-th box

See Also:

arrangeFields(LayoutGraph, NodeList[], EdgeList[], YRectangle[], Rectangle2D[], boolean, boolean, boolean), LayoutGraphUtilities.arrangeRectangleRows(Rectangle2D[], Rectangle2D, double, RowAlignment), LayoutGraphUtilities.arrangeRectangleMultiRows(Rectangle2D[], Rectangle2D, double, double, boolean, MultiRowConstraint, RowAlignment)

arrangeFields

protected void arrangeFields(LayoutGraph graph,
                             NodeList[] nodes,
                             EdgeList[] edges,
                             YRectangle[] bbox,
                             Rectangle2D[] boxes,
                             boolean circular,
                             boolean fill,
                             boolean fromSketch)

Arranges the bounding boxes of the components.

This method is called by arrangeComponents(LayoutGraph, NodeList[], EdgeList[], YRectangle[], Rectangle2D[]) if the style is set to ComponentArrangementStyles.PACKED_RECTANGLE, ComponentArrangementStyles.PACKED_COMPACT_RECTANGLE, ComponentArrangementStyles.PACKED_CIRCLE or ComponentArrangementStyles.PACKED_COMPACT_CIRCLE. It may be overridden to adjust the component arrangement strategy of the mentioned styles.

Parameters:

graph - the input graph

nodes - the nodes of the components; the i-th list contains the nodes of the i-th component

edges - the edges of the components; the i-th list contains the edges of the i-th component

bbox - the bounds of the components; the i-th rectangle describes the bounding box of the i-th component

boxes - the extended bounds of the components; the i-th rectangle describes the bounding box of the i-th component

circular - true if the arrangement should be circular, false if it should be rectangular

fill - true if it is allowed to place components in empty spaces inside other components, false otherwise

fromSketch - true if the initial coordinates should be considered, false otherwise

calculateBounds

protected Rectangle2D calculateBounds(LayoutGraph graph)

Calculates the bounding box of a graph component including NodeHalos.

This method will be invoked for each component of the graph. Depending on the state of property LabelConsiderationEnabled, the returned bounding box will also include node and edge labels. It may be overridden to extend the bounds to reserve space for other elements.

Parameters:

graph - the subgraph containing the nodes and edges of a component

Returns:

the bounding box of the component

See Also:

setLabelConsiderationEnabled(boolean)

findGraphComponents

protected int findGraphComponents(LayoutGraph graph,
                                  INodeMap compNumber)

Determines which nodes belong to the same graph component.

This implementation uses the graph connectivity to sort the nodes into different components. Nodes that are not connected by a path will be in separate components.

This method is called by applyLayout(LayoutGraph). It may be overridden to choose another approach to find components that will be passed to the core layout algorithm. However, most of the layout algorithms cannot handle disconnected graphs. Also, edges between custom components will be ignored.

Additionally to normal connectedness, a group node and all of its children will belong to the same component.

Parameters:

graph - the input graph

compNumber - a map that will be filled with the zero-based index of the component to which the node belongs

Returns:

the number of connected components of this graph

See Also:

GraphConnectivity.connectedComponents(com.yworks.yfiles.algorithms.Graph)

getComponentSpacing

public double getComponentSpacing()

Gets the distance between the bounding boxes of the components.

The spacing needs to be non-negative.

Throws:

IllegalArgumentException - if the spacing is negative

Default Value:

The default value is 45.

Returns:

the component spacing

See Also:

setComponentSpacing(double)

getGridSpacing

public double getGridSpacing()

Gets the current grid spacing.

Components will be moved by multiples of this value, thus keeping their offset to the grid. That way, components or parts of them that were placed on a grid before, will stay on their original grid. The grid spacing also influences the distance between the components.

The spacing needs to be a non-negative value. If the grid spacing is set to 0, the grid won't be considered at all.

Throws:

IllegalArgumentException - if the given spacing is negative

This option keeps existing grid locations intact and won't correct the location of a component with respect to the grid specified here.

Default Value:

The default value is 0. No grid is considered.

Returns:

the grid spacing

See Also:

setGridSpacing(double)

getPreferredSize

public YDimension getPreferredSize()

Gets the preferred size of the layout.

The layout size also defines the desired aspect ratio (width/height).

The width and height need to be greater than zero.

Throws:

IllegalArgumentException - if the specified width or height is negative or zero.

ComponentArrangementStyles.NONE, ComponentArrangementStyles.SINGLE_ROW and ComponentArrangementStyles.SINGLE_COLUMN do not consider the preferred layout size.

Default Value:

The default value is YDimension. Both preferred width and height are 400.

Returns:

the preferred size of the calculated graph layout

See Also:

setPreferredSize(YDimension)

getStyle

public ComponentArrangementStyles getStyle()

Gets how the components are arranged.

Throws:

IllegalArgumentException - if the specified style is unknown

The style will have no effect if component arrangement is disabled.

Default Value:

The default value is ComponentArrangementStyles.ROWS

Returns:

one of the valid style specifiers

See Also:

setStyle(ComponentArrangementStyles)

isComponentArrangementEnabled

public boolean isComponentArrangementEnabled()

Gets whether or not the separately arranged components of the input graph should be arranged relative to each other.

If enabled, the components are arranged using a specific style without producing overlaps between components (except for ComponentArrangementStyles.NONE). Otherwise, the layout algorithm will keep the components at their location. Then, the components may overlap.

Default Value:

The default value is true. The components are arranged relative to each other.

Returns:

true if the components of the graph are arranged, false otherwise

See Also:

setComponentArrangementEnabled(boolean)

isGroupingConsiderationEnabled

public boolean isGroupingConsiderationEnabled()

Gets whether or not grouping information bound to the graph should be considered when determining the graph components.

Default Value:

The default value is true. Grouping information is considered for determining the components.

Returns:

true if the nesting structure of the graph is considered when determining the components, false otherwise

See Also:

setGroupingConsiderationEnabled(boolean)

isLabelConsiderationEnabled

public boolean isLabelConsiderationEnabled()

Gets whether or not to take node and edge labels into account when calculating the bounding box of the graph components.

Default Value:

The default value is true. Node and edge labels are included in the bounds of the components.

Returns:

true if node and edge labels are taken into account when calculating the bounding box of the graph components, false otherwise

See Also:

calculateBounds(LayoutGraph), setLabelConsiderationEnabled(boolean)

setComponentArrangementEnabled

public void setComponentArrangementEnabled(boolean value)

Sets whether or not the separately arranged components of the input graph should be arranged relative to each other.

If enabled, the components are arranged using a specific style without producing overlaps between components (except for ComponentArrangementStyles.NONE). Otherwise, the layout algorithm will keep the components at their location. Then, the components may overlap.

Default Value:

The default value is true. The components are arranged relative to each other.

Parameters:

value - true if the components of the graph are arranged, false otherwise

See Also:

isComponentArrangementEnabled()

setComponentSpacing

public void setComponentSpacing(double value)

Sets the distance between the bounding boxes of the components.

The spacing needs to be non-negative.

Throws:

IllegalArgumentException - if the spacing is negative

Default Value:

The default value is 45.

Parameters:

value - the component spacing

See Also:

getComponentSpacing()

setGridSpacing

public void setGridSpacing(double value)

Sets the current grid spacing.

Components will be moved by multiples of this value, thus keeping their offset to the grid. That way, components or parts of them that were placed on a grid before, will stay on their original grid. The grid spacing also influences the distance between the components.

The spacing needs to be a non-negative value. If the grid spacing is set to 0, the grid won't be considered at all.

Throws:

IllegalArgumentException - if the given spacing is negative

This option keeps existing grid locations intact and won't correct the location of a component with respect to the grid specified here.

Default Value:

The default value is 0. No grid is considered.

Parameters:

value - the grid spacing

See Also:

getGridSpacing()

setGroupingConsiderationEnabled

public void setGroupingConsiderationEnabled(boolean value)

Sets whether or not grouping information bound to the graph should be considered when determining the graph components.

Default Value:

The default value is true. Grouping information is considered for determining the components.

Parameters:

value - true if the nesting structure of the graph is considered when determining the components, false otherwise

See Also:

isGroupingConsiderationEnabled()

setLabelConsiderationEnabled

public void setLabelConsiderationEnabled(boolean value)

Sets whether or not to take node and edge labels into account when calculating the bounding box of the graph components.

Default Value:

The default value is true. Node and edge labels are included in the bounds of the components.

Parameters:

value - true if node and edge labels are taken into account when calculating the bounding box of the graph components, false otherwise

See Also:

calculateBounds(LayoutGraph), isLabelConsiderationEnabled()

setOrigin

protected void setOrigin(LayoutGraph graph,
                         NodeList nodes,
                         EdgeList edges,
                         YPoint origin,
                         YRectangle rectangle)

Moves the subgraph containing the given nodes and edges to the specified origin.

This method is called by arrangeComponents(LayoutGraph, NodeList[], EdgeList[], YRectangle[], Rectangle2D[]) and arrangeFields(LayoutGraph, NodeList[], EdgeList[], YRectangle[], Rectangle2D[], boolean, boolean, boolean) to move the components to overlap-free positions.

Parameters:

graph - the input graph

nodes - the nodes in the moving subgraph

edges - the edges in the moving subgraph

origin - the new origin of the graph

rectangle - the current bounds of the subgraph

setPreferredSize

public void setPreferredSize(YDimension value)

Sets the preferred size of the layout.

The layout size also defines the desired aspect ratio (width/height).

The width and height need to be greater than zero.

Throws:

IllegalArgumentException - if the specified width or height is negative or zero.

ComponentArrangementStyles.NONE, ComponentArrangementStyles.SINGLE_ROW and ComponentArrangementStyles.SINGLE_COLUMN do not consider the preferred layout size.

Default Value:

The default value is YDimension. Both preferred width and height are 400.

Parameters:

value - the preferred size of the calculated graph layout

See Also:

getPreferredSize()

setStyle

public void setStyle(ComponentArrangementStyles value)

Sets how the components are arranged.

Throws:

IllegalArgumentException - if the specified style is unknown

The style will have no effect if component arrangement is disabled.

Default Value:

The default value is ComponentArrangementStyles.ROWS

Parameters:

value - one of the valid style specifiers

See Also:

getStyle()