y.layout.multipage
Class MultiPageLayouter

java.lang.Object
  y.layout.AbstractLayoutStage
      y.layout.multipage.MultiPageLayouter

All Implemented Interfaces:

Layouter, LayoutStage

public class MultiPageLayouter
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 MultiPageLayouter it doesn't support PartitionGrids. Furthermore, while the MultiPageLayouter is able to support groups (see setGroupMode(byte)), it doesn't support edges incident to group nodes.

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, MultiPageLayouter does not modify its input graph but returns its result as a MultiPageLayout. To be able to profit as much as possible from existing layout support, this layout algorithm implements the Layouter interface, although method doLayout does not specify a return value. Therefore, client code has to register a LayoutCallback 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 DataProviders for keys NODE_ID_DPKEY, EDGE_ID_DPKEY, NODE_LABEL_ID_DPKEY, and EDGE_LABEL_ID_DPKEY before calling doLayout(y.layout.LayoutGraph) or calcLayout(y.layout.LayoutGraph).

Field Summary

static byte	EDGE_BUNDLE_DISTINGUISH_DIRECTIONS Edge bundle mode constant that specifies that multi-edges (edges with same endpoints) should be distinguished if they have different directions.
static byte	EDGE_BUNDLE_DISTINGUISH_MULTIEDGES Edge bundle mode constant that specifies that all multi-edges (edges with same endpoints) should be distinguished.
static byte	EDGE_BUNDLE_DISTINGUISH_TYPES Edge bundle mode constant that specifies that multi-edges (edges with same endpoints) should be distinguished if they are of different (user specified) type, see EDGE_TYPE_DPKEY.
static java.lang.Object	EDGE_ID_DPKEY A DataProvider key for mapping each edge of the input graph to a unique ID.
static java.lang.Object	EDGE_LABEL_ID_DPKEY A DataProvider key for mapping each edge label of the input graph to a unique ID.
static java.lang.Object	EDGE_TYPE_DPKEY A DataProvider key for specifying the type of multi-edges.
static byte	GROUP_MODE_ALL_NODES Node grouping specifier used when special nodes like, e.g., connector and proxy nodes (see NodeInfo.TYPE_CONNECTOR and NodeInfo.TYPE_PROXY) should be assigned to group nodes, too.
static byte	GROUP_MODE_IGNORE Node grouping specifier used when group nodes should be ignored.
static byte	GROUP_MODE_ORIGINAL_NODES_ONLY Node grouping specifier used when only original nodes should be assigned to group nodes.
static java.lang.Object	NODE_CLUSTER_ID_DPKEY A DataProvider key for assigning a cluster ID to common (non-group) nodes.
static java.lang.Object	NODE_ID_DPKEY A DataProvider key for mapping each node of the input graph to a unique ID.
static java.lang.Object	NODE_LABEL_ID_DPKEY A DataProvider key for mapping each node label of the input graph to a unique ID.

Fields inherited from interface y.layout.Layouter

NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

MultiPageLayouter(Layouter core)
Creates a new MultiPageLayouter instance.

Method Summary

MultiPageLayout	calcLayout(LayoutGraph graph) Calculates a new multi-page layout for the specified graph.
boolean	canLayout(LayoutGraph graph) First, this method checks if all ID DataProviders are registered (NODE_ID_DPKEY, EDGE_ID_DPKEY, NODE_LABEL_ID_DPKEY and EDGE_LABEL_ID_DPKEY).
protected ElementFactory	createElementFactory() This method creates the element factory for multi-page layouts.
protected void	doIncrementalLayout(LayoutGraph graph, DataProvider incrementalNodesDP, LayoutContext context) This method is called to further improve the layout results.
void	doLayout(LayoutGraph graph) Calculates a new multi-page layout for the specified graph.
int	getAdditionalParentCount() Returns the number of additional tree parent proxies that the algorithm tries to place on a page.
int	getEdgeBundleModeMask() Returns the bit mask for defining edge bundles.
ElementFactory	getElementFactory() Returns the element factory for creating special nodes and edges in a multi-page layout.
byte	getGroupMode() Returns how to handle special nodes (like connector and proxy nodes) with respect to groups.
LayoutStage	getLabelLayouter() Returns the LayoutStage that places the labels of the input graph.
LayoutCallback	getLayoutCallback() Returns the callback that is notified upon completion of multi-page layout calculation runs.
YDimension	getMaxPageSize() Returns the maximum size of a single page.
long	getPreferredMaximalDuration() Returns the preferred time limit (in milliseconds) for the layout algorithm.
boolean	isLabelLayouterEnabled() Returns whether or not the given labeling algorithm places the labels of the input graph.
boolean	isMultipleComponentsOnSinglePagePlacementEnabled() Returns whether or not different connected components may be placed on a single page.
boolean	isProxyReferenceNodeCreationEnabled() Returns whether or not the algorithm should create proxy reference nodes.
boolean	isStrictClusterSeparationEnabled() Returns 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, DataProvider selectedEdgesDP, YRectangle boundingRectangle) This method is called whenever some single edges have to be routed without changing the position of nodes (e.g., by removeConnectorPair(y.base.Node, y.base.Node, y.base.YList, LayoutContext) to route the restored edges).
void	setAdditionalParentCount(int additionalParentCount) Specifies the number of additional tree parent proxies that the algorithm tries to place on a page.
void	setEdgeBundleModeMask(int edgeBundleModeMask) Specifies the bit mask for defining edge bundles.
void	setElementFactory(ElementFactory factory) Specifies the element factory for creating special nodes and edges in a multi-page layout.
void	setGroupMode(byte groupMode) Specifies how to handle special nodes (like connector and proxy nodes) with respect to groups.
void	setLabelLayouter(LayoutStage labeler) Specifies the LayoutStage that places the labels of the input graph.
void	setLabelLayouterEnabled(boolean labelLayouterEnabled) Specifies whether or not the given labeling algorithm places the labels of the input graph.
void	setLayoutCallback(LayoutCallback callback) Specifies the callback that is notified upon completion of multi-page layout calculation runs.
void	setMaxPageSize(YDimension maxPageSize) Specifies the maximum size of a single page.
void	setMultipleComponentsOnSinglePagePlacementEnabled(boolean multipleComponentsOnSinglePagePlacementEnabled) Specifies whether or not different connected components may be placed on a single page.
void	setPreferredMaximalDuration(long preferredMaximalDuration) Sets the preferred time limit (in milliseconds) for the layout algorithm.
void	setProxyReferenceNodeCreationEnabled(boolean proxyReferenceNodeCreationEnabled) Specifies whether or not the algorithm should create proxy reference nodes.
void	setStrictClusterSeparationEnabled(boolean strictClusterSeparationEnabled) Specifies whether or not the algorithm should separate nodes with different cluster IDs.

Methods inherited from class y.layout.AbstractLayoutStage

canLayoutCore, doLayoutCore, getCoreLayouter, setCoreLayouter

Methods inherited from class java.lang.Object

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

Field Detail

NODE_CLUSTER_ID_DPKEY

public static final java.lang.Object NODE_CLUSTER_ID_DPKEY

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

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

See Also:

setStrictClusterSeparationEnabled(boolean)

NODE_ID_DPKEY

public static final java.lang.Object NODE_ID_DPKEY

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

This DataProvider has to be specified by the user!

EDGE_ID_DPKEY

public static final java.lang.Object EDGE_ID_DPKEY

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

This DataProvider has to be specified by the user!

EDGE_LABEL_ID_DPKEY

public static final java.lang.Object EDGE_LABEL_ID_DPKEY

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

This DataProvider has to be specified by the user!

NODE_LABEL_ID_DPKEY

public static final java.lang.Object NODE_LABEL_ID_DPKEY

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

This DataProvider has to be specified by the user!

EDGE_TYPE_DPKEY

public static final java.lang.Object EDGE_TYPE_DPKEY

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

If getEdgeBundleModeMask() & EDGE_BUNDLE_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 NodeInfo.TYPE_CONNECTOR).

See Also:

EDGE_BUNDLE_DISTINGUISH_TYPES, setEdgeBundleModeMask(int)

GROUP_MODE_IGNORE

public static final byte GROUP_MODE_IGNORE

Node grouping specifier used when group nodes should be ignored.

See Also:

setGroupMode(byte), Constant Field Values

GROUP_MODE_ORIGINAL_NODES_ONLY

public static final byte GROUP_MODE_ORIGINAL_NODES_ONLY

Node grouping specifier used when only original nodes should be assigned to group nodes. Hence, connector and proxy nodes (see NodeInfo.TYPE_CONNECTOR and NodeInfo.TYPE_PROXY) are never assigned to group nodes even though the associated node lies within a group.

A group node may be fragmented, i.e., its content may be placed on different pages.

See Also:

setGroupMode(byte), Constant Field Values

Sample Graph:

GROUP_MODE_ALL_NODES

public static final byte GROUP_MODE_ALL_NODES

Node grouping specifier used when special nodes like, e.g., connector and proxy nodes (see NodeInfo.TYPE_CONNECTOR and NodeInfo.TYPE_PROXY) should be assigned to group nodes, too.

A group node may be fragmented, i.e., its content may be placed on different pages.

See Also:

setGroupMode(byte), Constant Field Values

Sample Graph:

EDGE_BUNDLE_DISTINGUISH_MULTIEDGES

public static final byte EDGE_BUNDLE_DISTINGUISH_MULTIEDGES

Edge bundle mode constant that specifies that all multi-edges (edges with same endpoints) should be distinguished. Hence, if such edges connect two nodes on different pages, a separate connector pair (see NodeInfo.TYPE_CONNECTOR) is used for each of them.

See Also:

setEdgeBundleModeMask(int), Constant Field Values

Sample Graph:

Circular nodes denote the connectors. The label of a connector corresponds to that of the opposite node of the split edge.

EDGE_BUNDLE_DISTINGUISH_DIRECTIONS

public static final byte EDGE_BUNDLE_DISTINGUISH_DIRECTIONS

Edge bundle mode constant that specifies that multi-edges (edges with same endpoints) should be distinguished if they have different directions. Hence, two edges with the same endpoints may share a connector pair (see NodeInfo.TYPE_CONNECTOR) if they point in the same direction (i.e., both have the same source and target node).

See Also:

setEdgeBundleModeMask(int), Constant Field Values

Sample Graph:

Circular nodes denote the connectors. The label of a connector corresponds to that of the opposite node of the split edge.

EDGE_BUNDLE_DISTINGUISH_TYPES

public static final byte EDGE_BUNDLE_DISTINGUISH_TYPES

Edge bundle mode constant that specifies that multi-edges (edges with same endpoints) should be distinguished if they are of different (user specified) type, see EDGE_TYPE_DPKEY. Hence, two edges with the same endpoints and same type may share a connector pair (see NodeInfo.TYPE_CONNECTOR).

See Also:

setEdgeBundleModeMask(int), EDGE_TYPE_DPKEY, Constant Field Values

Constructor Detail

MultiPageLayouter

public MultiPageLayouter(Layouter core)

Creates a new MultiPageLayouter instance.

Parameters:

core - the layout algorithm used for a single page

Method Detail

isProxyReferenceNodeCreationEnabled

public boolean isProxyReferenceNodeCreationEnabled()

Returns whether or not the algorithm should create proxy reference nodes.

If this option is disabled, the algorithm doesn't create proxy reference nodes in which case the referencing node of a proxy node corresponds to its represented node.

Returns:

true if the algorithm creates proxy reference nodes, false otherwise

See Also:

setProxyReferenceNodeCreationEnabled(boolean), NodeInfo.TYPE_PROXY_REFERENCE, NodeInfo.TYPE_PROXY, NodeInfo.getReferencingNode(), NodeInfo.getRepresentedNode()

setProxyReferenceNodeCreationEnabled

public void setProxyReferenceNodeCreationEnabled(boolean proxyReferenceNodeCreationEnabled)

Specifies whether or not the algorithm should create proxy reference nodes.

If this option is disabled, the algorithm doesn't create proxy reference nodes in which case the referencing node of a proxy node corresponds to its represented node.

Default Value:

The default value is true. The algorithm creates proxy reference nodes.

Parameters:

proxyReferenceNodeCreationEnabled - true if the algorithm should create proxy reference nodes, false otherwise

See Also:

NodeInfo.TYPE_PROXY_REFERENCE, NodeInfo.TYPE_PROXY, NodeInfo.getReferencingNode(), NodeInfo.getRepresentedNode()

isStrictClusterSeparationEnabled

public boolean isStrictClusterSeparationEnabled()

Returns 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.

Returns:

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

See Also:

NODE_CLUSTER_ID_DPKEY, setStrictClusterSeparationEnabled(boolean)

setStrictClusterSeparationEnabled

public void setStrictClusterSeparationEnabled(boolean strictClusterSeparationEnabled)

Specifies 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:

strictClusterSeparationEnabled - true if the algorithm should separate nodes with different cluster IDs, false otherwise

See Also:

NODE_CLUSTER_ID_DPKEY

isLabelLayouterEnabled

public boolean isLabelLayouterEnabled()

Returns 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.

Returns:

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

See Also:

setLabelLayouter(y.layout.LayoutStage), setLabelLayouterEnabled(boolean)

setLabelLayouterEnabled

public void setLabelLayouterEnabled(boolean labelLayouterEnabled)

Specifies 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:

labelLayouterEnabled - true if the given labeling algorithm should place the labels, false otherwise

See Also:

setLabelLayouter(LayoutStage)

createElementFactory

protected ElementFactory createElementFactory()

This method creates the element factory for multi-page layouts. It is called once from getElementFactory() if no factory has been explicitly set using setElementFactory(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(ElementFactory), getElementFactory(), ElementFactory

getElementFactory

public ElementFactory getElementFactory()

Returns the element factory for creating special nodes and edges in a multi-page layout. If no element factory is set explicitly (see method setElementFactory(ElementFactory)), a new instance is created and set by method createElementFactory() during the first layout run.

Returns:

the element factory for creating special nodes and edges

See Also:

setElementFactory(ElementFactory), createElementFactory(), ElementFactory

setElementFactory

public void setElementFactory(ElementFactory factory)

Specifies the element factory for creating special nodes and edges in a multi-page layout. If no element factory is set explicitly (see method setElementFactory(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:

factory - the element factory for creating special nodes and edges

See Also:

createElementFactory(), ElementFactory

getLayoutCallback

public LayoutCallback getLayoutCallback()

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

Returns:

the LayoutCallback instance that is notified

See Also:

setLayoutCallback(LayoutCallback)

setLayoutCallback

public void setLayoutCallback(LayoutCallback callback)

Specifies 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:

callback - the LayoutCallback instance that is notified

See Also:

LayoutCallback

setAdditionalParentCount

public void setAdditionalParentCount(int additionalParentCount)

Specifies the number of additional tree parent proxies that the algorithm tries to place on a page.

If the input graph is a tree and the core layout algorithm is an instance of GenericTreeLayouter or TreeLayouter, the algorithm may place additional parent proxies of the subtree on a page. The number of these additional parent proxies is limited by this value. Note that these additional nodes are proxies and, thus, copies of already existing nodes. The reason why it may be appropriate to add additional proxies is, that you can better identify additional parents of the tree structure. Furthermore, if the additional count is larger than 0, the algorithm doesn't insert any connector nodes but uses proxy nodes instead.

This option is only considered if the input graph is a tree and the core layout algorithm is an instance of GenericTreeLayouter or TreeLayouter.

Default Value:

The default value is 0. No additional parent proxies are placed on a page.

Parameters:

additionalParentCount - the (non-negative) maximum number of additional tree parent proxies

Throws:

java.lang.IllegalArgumentException - if the given additional parent count is negative

getAdditionalParentCount

public int getAdditionalParentCount()

Returns the number of additional tree parent proxies that the algorithm tries to place on a page.

If the input graph is a tree and the core layout algorithm is an instance of GenericTreeLayouter or TreeLayouter, the algorithm may place additional parent proxies of the subtree on a page. The number of these additional parent proxies is limited by this value. Note that these additional nodes are proxies and, thus, copies of already existing nodes. The reason why it may be appropriate to add additional proxies is, that you can better identify additional parents of the tree structure. Furthermore, if the additional count is larger than 0, the algorithm doesn't insert any connector nodes but uses proxy nodes instead.

This option is only considered if the input graph is a tree and the core layout algorithm is an instance of GenericTreeLayouter or TreeLayouter.

Returns:

the (non-negative) maximum number of additional tree parent proxies

See Also:

setAdditionalParentCount(int)

getEdgeBundleModeMask

public int getEdgeBundleModeMask()

Returns 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 NodeInfo.TYPE_CONNECTOR).

Returns:

the bit mask for defining edge bundles

See Also:

setEdgeBundleModeMask(int), NodeInfo.TYPE_CONNECTOR

setEdgeBundleModeMask

public void setEdgeBundleModeMask(int edgeBundleModeMask)

Specifies 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 NodeInfo.TYPE_CONNECTOR).

Default Value:

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

Parameters:

edgeBundleModeMask - the bit mask for defining edge bundles

See Also:

NodeInfo.TYPE_CONNECTOR

getGroupMode

public byte getGroupMode()

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

While the MultiPageLayouter is able to handle groups (see setGroupMode(byte)), it doesn't support edges incident to group nodes.

Returns:

the current node grouping specifier

See Also:

setGroupMode(byte), NodeInfo.TYPE_CONNECTOR, NodeInfo.TYPE_PROXY

setGroupMode

public void setGroupMode(byte groupMode)

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

While the MultiPageLayouter is able to handle groups (see setGroupMode(byte)), it doesn't support edges incident to group nodes.

Default Value:

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

Parameters:

groupMode - the node grouping specifier

Throws:

java.lang.IllegalArgumentException - if the specified group mode is unknown

See Also:

NodeInfo.TYPE_CONNECTOR, NodeInfo.TYPE_PROXY

getPreferredMaximalDuration

public long getPreferredMaximalDuration()

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

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.

Returns:

the preferred time limit

See Also:

setPreferredMaximalDuration(long)

setPreferredMaximalDuration

public void setPreferredMaximalDuration(long preferredMaximalDuration)

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

The specified value has to be non-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:

preferredMaximalDuration - the preferred time limit

Throws:

java.lang.IllegalArgumentException - if the preferred time limit is negative

getLabelLayouter

public LayoutStage getLabelLayouter()

Returns the LayoutStage that places the labels of the input graph.

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

Returns:

the LayoutStage instance

See Also:

setLabelLayouter(LayoutStage), setLabelLayouterEnabled(boolean), SALabeling, GreedyMISLabeling

setLabelLayouter

public void setLabelLayouter(LayoutStage labeler)

Specifies the LayoutStage that places the labels of the input graph.

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

Default Value:

The default value is SALabeling. An instance of SALabeling with SALabeling.setMaximalDuration(long) set to 0.

Parameters:

labeler - the LayoutStage instance

See Also:

setLabelLayouterEnabled(boolean), SALabeling, GreedyMISLabeling

isMultipleComponentsOnSinglePagePlacementEnabled

public boolean isMultipleComponentsOnSinglePagePlacementEnabled()

Returns whether or not different connected components may be placed on a single page.

Returns:

true if different connected components may be placed on a single page, false otherwise

See Also:

setMultipleComponentsOnSinglePagePlacementEnabled(boolean)

setMultipleComponentsOnSinglePagePlacementEnabled

public void setMultipleComponentsOnSinglePagePlacementEnabled(boolean multipleComponentsOnSinglePagePlacementEnabled)

Specifies whether or not different connected components may be placed on a single page.

Default Value:

The default value is true. Different components may be placed on a single page.

Parameters:

multipleComponentsOnSinglePagePlacementEnabled - true if different connected components may be placed on a single page, false otherwise

doLayout

public void doLayout(LayoutGraph graph)

Calculates a new multi-page layout for the specified graph. This method calls calcLayout(y.layout.LayoutGraph) and notifies the registered layout callback of the calculated result.

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

Parameters:

graph - the input graph

See Also:

Layouter.canLayout(LayoutGraph)

calcLayout

public MultiPageLayout calcLayout(LayoutGraph graph)

Calculates a new multi-page layout for the specified graph. Unlike method doLayout(y.layout.LayoutGraph), this method ignores the registered layout callback and directly returns the calculated MultiPageLayout.

Unlike other implementations of the Layouter.doLayout(y.layout.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 MultiPageLayout that represents the result of the layout run

Throws:

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

See Also:

MultiPageLayout

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(y.layout.LayoutGraph, y.base.DataProvider, y.geom.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(y.layout.LayoutGraph, y.base.DataProvider, y.geom.YRectangle)

canLayout

public boolean canLayout(LayoutGraph graph)

First, this method checks if all ID DataProviders are registered (NODE_ID_DPKEY, EDGE_ID_DPKEY, NODE_LABEL_ID_DPKEY and EDGE_LABEL_ID_DPKEY). If not, this method returns false. Otherwise, it delegates this call to the Layouter.canLayout(y.layout.LayoutGraph) method of the specified core layouter.

Parameters:

graph - the input graph

Returns:

true if the partial layout algorithm can be applied to the specified graph, false otherwise

See Also:

Layouter.doLayout(LayoutGraph)

getMaxPageSize

public YDimension getMaxPageSize()

Returns 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.

A large page size may increase runtime significantly. To limit the runtime use method setPreferredMaximalDuration(long).

Returns:

the maximum size for a single page

See Also:

setMaxPageSize(YDimension), setPreferredMaximalDuration(long)

setMaxPageSize

public void setMaxPageSize(YDimension maxPageSize)

Specifies 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.

A large page size may increase runtime significantly. To limit the runtime use method setPreferredMaximalDuration(long).

Default Value:

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

Parameters:

maxPageSize - the maximum size for a single page

Throws:

java.lang.IllegalArgumentException - if the specified width or height is not positive

See Also:

setPreferredMaximalDuration(long)

Sample Graphs:

Size 250x250 The whole graph fits onto a single page.

Size 150x250 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.

Size 200x200 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.

doIncrementalLayout

protected void doIncrementalLayout(LayoutGraph graph,
                                   DataProvider 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 DataProvider 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

routeRestoredEdges

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

This method is called whenever some single edges have to be routed without changing the position of nodes (e.g., by removeConnectorPair(y.base.Node, y.base.Node, y.base.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 DataProvider 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(y.base.Node, y.base.Node, y.base.YList, LayoutContext)