com.yworks.yfiles.layout.multipage

Class MultiPageLayout

java.lang.Object

com.yworks.yfiles.layout.AbstractLayoutStage

com.yworks.yfiles.layout.multipage.MultiPageLayout

All Implemented Interfaces:

ILayoutAlgorithm, ILayoutStage

public class MultiPageLayout
extends AbstractLayoutStage

This layout algorithm subdivides the input graph into several LayoutGraphs (called page graphs) such that the layout (calculated by the specified core layout algorithm) of each graph fits the specified maximum page size.

The algorithm adds special nodes to guarantee that no information is lost when splitting edges that connect nodes placed on different pages (for more details take a look at the concept described below).

The input graph.

The input graph is subdivided into two pages with size 500x500. Circular nodes denote the so-called connectors that split edges to nodes placed on other pages. The label of a connector corresponds to that of the opposite node of the split edge.

Layout Style

This multi-page layout algorithm subdivides the input graph into several smaller ones and applies existing layout algorithms to each of them. Hence, its layout style heavily depends on the selected core layout algorithm used for each single page. Furthermore, the algorithm uses several refinement steps to produce more compact results.

Features

Similar to the layout style, the supported feature set mainly depends on the features supported by the specified core layout algorithm. Note that due to the underlying approach of the MultiPageLayout it doesn't support PartitionGrids.

Concept

To guarantee that no information is lost, this layout algorithm replaces edges between nodes on different pages by so-called connector nodes. Furthermore, it may replicate nodes (the clones are called proxy nodes) and insert special nodes to refer to such nodes (so-called proxy reference nodes).

Unlike other yFiles layout algorithms, MultiPageLayout does not modify its input graph but returns its result as a MultiPageLayoutResult. To be able to profit as much as possible from existing layout support, this layout algorithm implements the ILayoutAlgorithm interface, although method doLayout does not specify a return value. Therefore, client code has to register a ILayoutCallback that is invoked when the algorithm has calculated a new multi-page result.

This layout algorithm does not consider the initial drawing of the graph.

Client code must register IDataProviders for keys NODE_ID_DPKEY, EDGE_ID_DPKEY, NODE_LABEL_ID_DPKEY, and EDGE_LABEL_ID_DPKEY before calling applyLayout(LayoutGraph) or calculateLayout(LayoutGraph).

Field Summary

Fields

Modifier and Type	Field and Description
static EdgeDpKey<Object>	EDGE_ID_DPKEY A DataProvider key for mapping each edge of the input graph to a unique ID.
static IEdgeLabelLayoutDpKey<Object>	EDGE_LABEL_ID_DPKEY A DataProvider key for mapping each edge label of the input graph to a unique ID.
static EdgeDpKey<Object>	EDGE_TYPE_DPKEY A DataProvider key for specifying the type of multi-edges.
static NodeDpKey<Object>	NODE_CLUSTER_ID_DPKEY A DataProvider key for assigning a cluster ID to common (non-group) nodes.
static NodeDpKey<Object>	NODE_ID_DPKEY A DataProvider key for mapping each node of the input graph to a unique ID.
static INodeLabelLayoutDpKey<Object>	NODE_LABEL_ID_DPKEY A DataProvider key for mapping each node label of the input graph to a unique ID.

Constructor Summary

Constructors

Constructor and Description
MultiPageLayout(ILayoutAlgorithm core) Creates a new MultiPageLayout instance.

Method Summary

Modifier and Type	Method and Description
protected void	applyIncrementalLayout(LayoutGraph graph, IDataProvider incrementalNodesDP, LayoutContext context) This method is called to further improve the layout results.
void	applyLayout(LayoutGraph graph) Calculates a new multi-page layout for the specified graph.
MultiPageLayoutResult	calculateLayout(LayoutGraph graph) Calculates a new multi-page layout for the specified graph.
protected IElementFactory	createElementFactory() This method creates the element factory for multi-page layouts.
EdgeBundleModes	getEdgeBundleModeMask() Gets the bit mask for defining edge bundles.
IElementFactory	getElementFactory() Gets the element factory for creating special nodes and edges in a multi-page layout.
GroupingMode	getGroupingMode() Gets how to handle special nodes (like connector and proxy nodes) with respect to groups.
ILayoutStage	getLabeling() Gets the ILayoutStage that places the labels of the input graph.
ILayoutCallback	getLayoutCallback() Gets the callback that is notified upon completion of multi-page layout calculation runs.
long	getMaximumDuration() Gets the preferred time limit (in milliseconds) for the layout algorithm.
YDimension	getMaximumPageSize() Gets the maximum size of a single page.
boolean	isLabelingEnabled() Gets whether or not the given labeling algorithm places the labels of the input graph.
boolean	isStrictClusterSeparationEnabled() Gets whether or not the algorithm should separate nodes with different cluster IDs.
protected boolean	removeConnectorPair(Node connector1, Node connector2, YList originalEdgeIds, LayoutContext context) This method is called during a postprocessing step that reduces the number of connectors.
protected void	routeRestoredEdges(LayoutGraph graph, IDataProvider selectedEdgesDP, YRectangle boundingRectangle) This method is called by removeConnectorPair(Node, Node, YList, LayoutContext) to route the restored edges.
void	setEdgeBundleModeMask(EdgeBundleModes value) Sets the bit mask for defining edge bundles.
void	setElementFactory(IElementFactory value) Sets the element factory for creating special nodes and edges in a multi-page layout.
void	setGroupingMode(GroupingMode value) Sets how to handle special nodes (like connector and proxy nodes) with respect to groups.
void	setLabeling(ILayoutStage value) Sets the ILayoutStage that places the labels of the input graph.
void	setLabelingEnabled(boolean value) Sets whether or not the given labeling algorithm places the labels of the input graph.
void	setLayoutCallback(ILayoutCallback value) Sets the callback that is notified upon completion of multi-page layout calculation runs.
void	setMaximumDuration(long value) Sets the preferred time limit (in milliseconds) for the layout algorithm.
void	setMaximumPageSize(YDimension value) Sets the maximum size of a single page.
void	setStrictClusterSeparationEnabled(boolean value) Sets whether or not the algorithm should separate nodes with different cluster IDs.

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

EDGE_ID_DPKEY

public static final EdgeDpKey<Object> EDGE_ID_DPKEY

A DataProvider key for mapping each edge of the input graph to a unique ID.

This IDataProvider has to be specified by the user!

EDGE_LABEL_ID_DPKEY

public static final IEdgeLabelLayoutDpKey<Object> EDGE_LABEL_ID_DPKEY

A DataProvider key for mapping each edge label of the input graph to a unique ID.

This IDataProvider has to be specified by the user!

EDGE_TYPE_DPKEY

public static final EdgeDpKey<Object> EDGE_TYPE_DPKEY

A DataProvider key for specifying the type of multi-edges.

If EdgeBundleModeMask & EdgeBundleModes.DISTINGUISH_TYPES == 1, multi-edges (edges with same endpoints) associated with different types (objects) are distinguished, i.e., they are split by different connector pairs (see NodeType.CONNECTOR).

See Also:

EdgeBundleModes.DISTINGUISH_TYPES, setEdgeBundleModeMask(EdgeBundleModes)

NODE_CLUSTER_ID_DPKEY

public static final NodeDpKey<Object> NODE_CLUSTER_ID_DPKEY

A DataProvider key for assigning a cluster ID to common (non-group) nodes.

If there is no IDataProvider associated with this key, the algorithm assumes that there are no such preferences.

See Also:

setStrictClusterSeparationEnabled(boolean)

NODE_ID_DPKEY

public static final NodeDpKey<Object> NODE_ID_DPKEY

A DataProvider key for mapping each node of the input graph to a unique ID.

This IDataProvider has to be specified by the user!

NODE_LABEL_ID_DPKEY

public static final INodeLabelLayoutDpKey<Object> NODE_LABEL_ID_DPKEY

A DataProvider key for mapping each node label of the input graph to a unique ID.

This IDataProvider has to be specified by the user!

Constructor Detail

MultiPageLayout

public MultiPageLayout(ILayoutAlgorithm core)

Creates a new MultiPageLayout instance.

Parameters:

core - the layout algorithm used for a single page

Method Detail

applyIncrementalLayout

protected void applyIncrementalLayout(LayoutGraph graph,
                                      IDataProvider incrementalNodesDP,
                                      LayoutContext context)

This method is called to further improve the layout results.

The marked nodes have to be placed without changing the coordinates of the fixed (non-marked) elements and without exceeding the specified maximum page size. Furthermore, the basic layout properties should be maintained.

Subclasses may implement a custom layout strategy for this step.

Parameters:

graph - the input graph

incrementalNodesDP - a IDataProvider that returns a boolean value indicating whether or not a node is marked; the positions of the non-marked nodes are not allowed to change

context - the current layout context

See Also:

LayoutContext

applyLayout

public void applyLayout(LayoutGraph graph)

Calculates a new multi-page layout for the specified graph.

This method calls calculateLayout(LayoutGraph) and notifies the registered layout callback of the calculated result.

Specified by:

applyLayout in interface ILayoutAlgorithm

Specified by:

applyLayout in class AbstractLayoutStage

Unlike other implementations of ILayoutAlgorithm.applyLayout(LayoutGraph) method, the result of the layout calculation will not be applied to the input graph.

Parameters:

graph - the input graph

calculateLayout

public MultiPageLayoutResult calculateLayout(LayoutGraph graph)

Calculates a new multi-page layout for the specified graph.

Unlike method applyLayout(LayoutGraph), this method ignores the registered layout callback and directly returns the calculated MultiPageLayoutResult.

Throws:

IllegalArgumentException - if for one of the keys NODE_ID_DPKEY, EDGE_ID_DPKEY, NODE_LABEL_ID_DPKEY and EDGE_LABEL_ID_DPKEY no IDataProvider is registered with the given graph

Unlike other implementations of the ILayoutAlgorithm.applyLayout(LayoutGraph) method, the result of the layout calculation will not be applied to the input graph.

Parameters:

graph - the input graph

Returns:

an instance of MultiPageLayoutResult that represents the result of the layout run

See Also:

MultiPageLayoutResult

createElementFactory

protected IElementFactory createElementFactory()

This method creates the element factory for multi-page layouts.

It is called once from ElementFactory if no factory has been explicitly set using ElementFactory. By default, this method returns an instance of DefaultElementFactory.

Subclasses may create a custom implementation of the element factory.

Returns:

the created element factory

See Also:

setElementFactory(IElementFactory), getElementFactory(), IElementFactory

getEdgeBundleModeMask

public EdgeBundleModes getEdgeBundleModeMask()

Gets the bit mask for defining edge bundles.

All multi-edges (edges with same endpoints) belonging to the same edge bundle are split by the same connector pair (see NodeType.CONNECTOR).

Default Value:

The default value is 0. All multi-edges belong to the same edge bundle.

Returns:

the bit mask for defining edge bundles

See Also:

NodeType.CONNECTOR, setEdgeBundleModeMask(EdgeBundleModes)

getElementFactory

public IElementFactory getElementFactory()

Gets the element factory for creating special nodes and edges in a multi-page layout.

If no element factory is set explicitly (see method ElementFactory), a new instance is created and set by method createElementFactory() during the first layout run.

Default Value:

The default value is DefaultElementFactory. If no element factory is set explicitly, the algorithm uses an instance of DefaultElementFactory.

Returns:

the element factory for creating special nodes and edges

See Also:

createElementFactory(), IElementFactory, setElementFactory(IElementFactory)

getGroupingMode

public GroupingMode getGroupingMode()

Gets how to handle special nodes (like connector and proxy nodes) with respect to groups.

Throws:

IllegalArgumentException - if the specified group mode is unknown

Default Value:

The default value is GroupingMode.ALL_NODES. Special nodes are also assigned to the associated groups.

Returns:

the current node grouping specifier

See Also:

NodeType.CONNECTOR, NodeType.PROXY, setGroupingMode(GroupingMode)

getLabeling

public ILayoutStage getLabeling()

Gets the ILayoutStage that places the labels of the input graph.

This ILayoutStage needs to be activated in order to take effect.

Default Value:

The default value is GenericLabeling. An instance of GenericLabeling with MaximumDuration set to 0.

Returns:

the ILayoutStage instance

See Also:

setLabelingEnabled(boolean), GenericLabeling, setLabeling(ILayoutStage)

getLayoutCallback

public ILayoutCallback getLayoutCallback()

Gets the callback that is notified upon completion of multi-page layout calculation runs.

Default Value:

The default value is null. No layout callback is set.

Returns:

the ILayoutCallback instance that is notified

See Also:

ILayoutCallback, setLayoutCallback(ILayoutCallback)

getMaximumDuration

public long getMaximumDuration()

Gets the preferred time limit (in milliseconds) for the layout algorithm.

The specified value has to be non-negative.

Throws:

IllegalArgumentException - if the preferred time limit is negative

Restricting the maximum duration may result in a worse layout quality. Furthermore, the actual runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.

Default Value:

The default value is Long.MAX_VALUE. The layout algorithm runs unrestricted.

Returns:

the preferred time limit

See Also:

setMaximumDuration(long)

getMaximumPageSize

public YDimension getMaximumPageSize()

Gets the maximum size of a single page.

The layout algorithm subdivides the input graph such that each part is placed on a different page that fits the specified maximum size.

Both the specified width and height have to be positive.

Throws:

IllegalArgumentException - if the specified width or height is not positive

A large page size may increase runtime significantly. To limit the runtime use method MaximumDuration.

Default Value:

The default value is 1000x1000. The width and height of the page are set to 1000.

Returns:

the maximum size for a single page

See Also:

setMaximumDuration(long), setMaximumPageSize(YDimension)

isLabelingEnabled

public boolean isLabelingEnabled()

Gets whether or not the given labeling algorithm places the labels of the input graph.

If this option is disabled, the labels are either ignored or placed by the integrated labeling approach of the core layout algorithm.

Default Value:

The default value is false. The given labeling algorithm does not place labels.

Returns:

true if the given label layouter places the labels, false otherwise

See Also:

setLabeling(ILayoutStage), setLabelingEnabled(boolean)

isStrictClusterSeparationEnabled

public boolean isStrictClusterSeparationEnabled()

Gets whether or not the algorithm should separate nodes with different cluster IDs.

More precisely, if this option is enabled, the algorithm doesn't place nodes with different cluster IDs onto the same page. Otherwise, such a placement is possible.

A node without cluster ID may be placed on any page, i.e., even though this option is enabled, a page may contain a node with and one without a cluster ID.

Default Value:

The default value is false. Nodes with different cluster IDs may be placed on the same page.

Returns:

true if the algorithm separates nodes with different cluster IDs, false otherwise

See Also:

NODE_CLUSTER_ID_DPKEY, setStrictClusterSeparationEnabled(boolean)

removeConnectorPair

protected boolean removeConnectorPair(Node connector1,
                                      Node connector2,
                                      YList originalEdgeIds,
                                      LayoutContext context)

This method is called during a postprocessing step that reduces the number of connectors.

A pair of connectors can be removed if both connector nodes are placed on the same page. The method removes both connector nodes and restores the original edges by calling routeRestoredEdges(LayoutGraph, IDataProvider, YRectangle).

Subclasses may implement a custom remove/restore strategy.

If this method returns false the graph was not changed, i.e., the connector pair still exists.

Parameters:

connector1 - the first connector of the connector pair

connector2 - the second connector of the connector pair

originalEdgeIds - the IDs of the original edges that have to be restored

context - the current layout context

Returns:

true if the removal of the connector pair was successful, false otherwise

See Also:

routeRestoredEdges(LayoutGraph, IDataProvider, YRectangle)

routeRestoredEdges

protected void routeRestoredEdges(LayoutGraph graph,
                                  IDataProvider selectedEdgesDP,
                                  YRectangle boundingRectangle)

This method is called by removeConnectorPair(Node, Node, YList, LayoutContext) to route the restored edges.

It has to guarantee that the routes are fully contained within the given bounding rectangle.

Subclasses may implement a custom routing strategy for the restored edges.

Parameters:

graph - the relevant graph

selectedEdgesDP - a IDataProvider that returns a boolean value indicating whether or not an edge should be rerouted

boundingRectangle - the edge routes should be fully contained within this rectangle

See Also:

removeConnectorPair(Node, Node, YList, LayoutContext)

setEdgeBundleModeMask

public void setEdgeBundleModeMask(EdgeBundleModes value)

Sets the bit mask for defining edge bundles.

All multi-edges (edges with same endpoints) belonging to the same edge bundle are split by the same connector pair (see NodeType.CONNECTOR).

Default Value:

The default value is 0. All multi-edges belong to the same edge bundle.

Parameters:

value - the bit mask for defining edge bundles

See Also:

NodeType.CONNECTOR, getEdgeBundleModeMask()

setElementFactory

public void setElementFactory(IElementFactory value)

Sets the element factory for creating special nodes and edges in a multi-page layout.

If no element factory is set explicitly (see method ElementFactory), a new instance is created and set by method createElementFactory() during the first layout run.

Default Value:

The default value is DefaultElementFactory. If no element factory is set explicitly, the algorithm uses an instance of DefaultElementFactory.

Parameters:

value - the element factory for creating special nodes and edges

See Also:

createElementFactory(), IElementFactory, getElementFactory()

setGroupingMode

public void setGroupingMode(GroupingMode value)

Sets how to handle special nodes (like connector and proxy nodes) with respect to groups.

Throws:

IllegalArgumentException - if the specified group mode is unknown

Default Value:

The default value is GroupingMode.ALL_NODES. Special nodes are also assigned to the associated groups.

Parameters:

value - the current node grouping specifier

See Also:

NodeType.CONNECTOR, NodeType.PROXY, getGroupingMode()

setLabeling

public void setLabeling(ILayoutStage value)

Sets the ILayoutStage that places the labels of the input graph.

This ILayoutStage needs to be activated in order to take effect.

Default Value:

The default value is GenericLabeling. An instance of GenericLabeling with MaximumDuration set to 0.

Parameters:

value - the ILayoutStage instance

See Also:

setLabelingEnabled(boolean), GenericLabeling, getLabeling()

setLabelingEnabled

public void setLabelingEnabled(boolean value)

Sets whether or not the given labeling algorithm places the labels of the input graph.

If this option is disabled, the labels are either ignored or placed by the integrated labeling approach of the core layout algorithm.

Default Value:

The default value is false. The given labeling algorithm does not place labels.

Parameters:

value - true if the given label layouter places the labels, false otherwise

See Also:

setLabeling(ILayoutStage), isLabelingEnabled()

setLayoutCallback

public void setLayoutCallback(ILayoutCallback value)

Sets the callback that is notified upon completion of multi-page layout calculation runs.

Default Value:

The default value is null. No layout callback is set.

Parameters:

value - the ILayoutCallback instance that is notified

See Also:

ILayoutCallback, getLayoutCallback()

setMaximumDuration

public void setMaximumDuration(long value)

Sets the preferred time limit (in milliseconds) for the layout algorithm.

The specified value has to be non-negative.

Throws:

IllegalArgumentException - if the preferred time limit is negative

Restricting the maximum duration may result in a worse layout quality. Furthermore, the actual runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.

Default Value:

The default value is Long.MAX_VALUE. The layout algorithm runs unrestricted.

Parameters:

value - the preferred time limit

See Also:

getMaximumDuration()

setMaximumPageSize

public void setMaximumPageSize(YDimension value)

Sets the maximum size of a single page.

The layout algorithm subdivides the input graph such that each part is placed on a different page that fits the specified maximum size.

Both the specified width and height have to be positive.

Throws:

IllegalArgumentException - if the specified width or height is not positive

A large page size may increase runtime significantly. To limit the runtime use method MaximumDuration.

Default Value:

The default value is 1000x1000. The width and height of the page are set to 1000.

Parameters:

value - the maximum size for a single page

See Also:

setMaximumDuration(long), getMaximumPageSize()

setStrictClusterSeparationEnabled

public void setStrictClusterSeparationEnabled(boolean value)

Sets whether or not the algorithm should separate nodes with different cluster IDs.

More precisely, if this option is enabled, the algorithm doesn't place nodes with different cluster IDs onto the same page. Otherwise, such a placement is possible.

A node without cluster ID may be placed on any page, i.e., even though this option is enabled, a page may contain a node with and one without a cluster ID.

Default Value:

The default value is false. Nodes with different cluster IDs may be placed on the same page.

Parameters:

value - true if the algorithm separates nodes with different cluster IDs, false otherwise

See Also:

NODE_CLUSTER_ID_DPKEY, isStrictClusterSeparationEnabled()