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

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

To guarantee that no information is lost, the layout algorithm replaces edges between nodes on different pages by so-called connector nodes (see NodeInfo.TYPE_CONNECTOR). Furthermore, it may replicate (proxy) nodes and insert elements called proxy reference nodes to refers to such proxies (see NodeInfo.TYPE_PROXY and NodeInfo.TYPE_PROXY_REFERENCE).

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, MultiPageLayouter implements the Layouter interface although method doLayout does not specify a return value. Therefore client code has to register a LayoutCallback that is notified of MultiPageLayouter results.

Note: Client code must register data providers 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 specifier.
static byte	EDGE_BUNDLE_DISTINGUISH_MULTIEDGES Edge bundle mode specifier.
static byte	EDGE_BUNDLE_DISTINGUISH_TYPES Edge bundle mode specifier.
static Object	EDGE_ID_DPKEY Used to map each edge of the input graph to a unique id.
static Object	EDGE_LABEL_ID_DPKEY Used to map each edge label of the input graph to a unique id.
static Object	EDGE_TYPE_DPKEY Allows to specify the edge kind (an object).
static byte	GROUP_MODE_ALL_NODES Node grouping specifier.
static byte	GROUP_MODE_IGNORE Node grouping specifier.
static byte	GROUP_MODE_ORIGINAL_NODES_ONLY Node grouping specifier.
static Object	NODE_CLUSTER_ID_DPKEY Allows to specify a cluster id (an object) for each node.
static Object	NODE_ID_DPKEY Used to map each node of the input graph to a unique id.
static Object	NODE_LABEL_ID_DPKEY Used to map each node label of the input graph to a unique id.

Fields inherited from interface y.layout.Layouter

SELECTED_EDGES, SELECTED_NODES

Constructor Summary

MultiPageLayouter(Layouter core)
Creates an instance of this layouter.

Method Summary

MultiPageLayout	calcLayout(LayoutGraph graph) Calculates a new multi-page layout for the specified graph.
boolean	canLayout(LayoutGraph graph) Returns true iff the given graph can be laid out by this algorithm.
protected ElementFactory	createElementFactory() Creates an element factory for multi-page layouts.
protected void	doIncrementalLayout(LayoutGraph graph, DataProvider incrementalNodesDP, LayoutContext context) Called to improve layout results.
void	doLayout(LayoutGraph graph) Calculates a new multi-page layout for the specified graph.
int	getEdgeBundleModeMask() Returns the bit mask that is used to define edge bundles.
ElementFactory	getElementFactory() Returns the element factory that is used to create special nodes and edges in a multi-page layout.
byte	getGroupMode() Returns how to handle node grouping.
LayoutStage	getLabelLayouter() Returns the algorithm that is used for placing labels.
LayoutCallback	getLayoutCallback() Returns the callback that is notified upon completion of multi-page layout calculation runs.
YDimension	getMaxPageSize() Returns the maximum size allowed for a single page.
long	getPreferredMaximalDuration() Returns the preferred time limit (in milliseconds) set for the layout algorithm.
boolean	isLabelLayouterEnabled() Returns whether or not the specified labeling stage is enabled.
protected boolean	removeConnectorPair(Node connector1, Node connector2, YList originalEdgeIds, LayoutContext context) Called during a postprocessing step that reduces the number of connectors.
protected void	routeRestoredEdges(LayoutGraph graph, DataProvider selectedEdgesDP, YRectangle boundingRectangle) Called by method removeConnectorPair(y.base.Node, y.base.Node, y.base.YList, LayoutContext) to route the restored edges.
void	setEdgeBundleModeMask(int edgeBundleModeMask) Specifies a bit mask that is used to define edge bundles.
void	setElementFactory(ElementFactory factory) Specifies the element factory that is used to create special nodes and edges in a multi-page layout.
void	setGroupMode(byte groupMode) Specifies how to handle node grouping.
void	setLabelLayouter(LayoutStage labeler) Sets the algorithm that is used for placing labels.
void	setLabelLayouterEnabled(boolean labelLayouterEnabled) Specifies whether or not to enable the labeling stage.
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 allowed for a single page.
void	setPreferredMaximalDuration(long preferredMaximalDuration) Sets a preferred time limit (in milliseconds) for the layout algorithm.

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 Object NODE_CLUSTER_ID_DPKEY

Allows to specify a cluster id (an object) for each node. Nodes with the same cluster id should preferably be placed on the same page.

NODE_ID_DPKEY

public static final Object NODE_ID_DPKEY

Used to map each node of the input graph to a unique id. Note: this DataProvider has to be specified by the user!

EDGE_ID_DPKEY

public static final Object EDGE_ID_DPKEY

Used to map each edge of the input graph to a unique id. Note: this DataProvider has to be specified by the user!

EDGE_LABEL_ID_DPKEY

public static final Object EDGE_LABEL_ID_DPKEY

Used to map each edge label of the input graph to a unique id. Note: this DataProvider has to be specified by the user!

NODE_LABEL_ID_DPKEY

public static final Object NODE_LABEL_ID_DPKEY

Used to map each node label of the input graph to a unique id. Note: this DataProvider has to be specified by the user!

EDGE_TYPE_DPKEY

public static final Object EDGE_TYPE_DPKEY

Allows to specify the edge kind (an object). Multi-edges (edges with same endpoints) of different kind are distinguished if getEdgeBundleModeMask() & EDGE_BUNDLE_DISTINGUISH_TYPES == 1.

See Also:

EDGE_BUNDLE_DISTINGUISH_TYPES, setEdgeBundleModeMask(int)

GROUP_MODE_IGNORE

public static final byte GROUP_MODE_IGNORE

Node grouping specifier. This value specifies that group nodes are completely ignored.

See Also:

setGroupMode(byte), getGroupMode(), Constant Field Values

GROUP_MODE_ORIGINAL_NODES_ONLY

public static final byte GROUP_MODE_ORIGINAL_NODES_ONLY

Node grouping specifier. This value specifies that only original nodes are assigned in group nodes.

See Also:

setGroupMode(byte), getGroupMode(), Constant Field Values

GROUP_MODE_ALL_NODES

public static final byte GROUP_MODE_ALL_NODES

Node grouping specifier. This value specifies that special nodes like, e.g., connector and proxy nodes are assigned to group nodes, too.

See Also:

setGroupMode(byte), getGroupMode(), Constant Field Values

EDGE_BUNDLE_DISTINGUISH_MULTIEDGES

public static final byte EDGE_BUNDLE_DISTINGUISH_MULTIEDGES

Edge bundle mode specifier. Used to define 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). This value specifies that all multi-edges should be distinguished, i.e., a separate connector pair is used for each multi-edge.

See Also:

setEdgeBundleModeMask(int), getEdgeBundleModeMask(), Constant Field Values

EDGE_BUNDLE_DISTINGUISH_DIRECTIONS

public static final byte EDGE_BUNDLE_DISTINGUISH_DIRECTIONS

Edge bundle mode specifier. Used to define 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). This value specifies that multi-edges should be distinguished if the have different directions.

See Also:

setEdgeBundleModeMask(int), getEdgeBundleModeMask(), Constant Field Values

EDGE_BUNDLE_DISTINGUISH_TYPES

public static final byte EDGE_BUNDLE_DISTINGUISH_TYPES

Edge bundle mode specifier. Used to define 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). This value specifies that multi-edges should be distinguished if they are of different (user specified) type, see EDGE_TYPE_DPKEY.

See Also:

setEdgeBundleModeMask(int), getEdgeBundleModeMask(), Constant Field Values

Constructor Detail

MultiPageLayouter

public MultiPageLayouter(Layouter core)

Creates an instance of this layouter.

Parameters:

core - the layouter used to layout a page.

Method Detail

isLabelLayouterEnabled

public boolean isLabelLayouterEnabled()

Returns whether or not the specified labeling stage is enabled.

See Also:

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

setLabelLayouterEnabled

public void setLabelLayouterEnabled(boolean labelLayouterEnabled)

Specifies whether or not to enable the labeling stage. By default it is disabled.

See Also:

setLabelLayouter(y.layout.LayoutStage)

createElementFactory

protected ElementFactory createElementFactory()

Creates an element factory for multi-page layouts. Called from getElementFactory() if no factory has been explicitly set using setElementFactory(ElementFactory).

Returns:

a DefaultElementFactory instance.

getElementFactory

public ElementFactory getElementFactory()

Returns the element factory that is used to create special nodes and edges in a multi-page layout.

Returns:

the element factory.

See Also:

setElementFactory(ElementFactory), createElementFactory(), ElementFactory

setElementFactory

public void setElementFactory(ElementFactory factory)

Specifies the element factory that is used to create special nodes and edges in a multi-page layout.

Parameters:

factory - the factory instance to use.

See Also:

getElementFactory(), createElementFactory(), ElementFactory

getLayoutCallback

public LayoutCallback getLayoutCallback()

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

Returns:

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

setLayoutCallback

public void setLayoutCallback(LayoutCallback callback)

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

Parameters:

callback - the LayoutCallback instance that is notified. May be null.

getEdgeBundleModeMask

public int getEdgeBundleModeMask()

Returns the bit mask that is used to define edge bundles.

Returns:

the bit mask that is used to define edge bundles.

See Also:

setEdgeBundleModeMask(int)

setEdgeBundleModeMask

public void setEdgeBundleModeMask(int edgeBundleModeMask)

Specifies a bit mask that is used to define 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). Possible values are EDGE_BUNDLE_DISTINGUISH_TYPES, EDGE_BUNDLE_DISTINGUISH_DIRECTIONS and EDGE_BUNDLE_DISTINGUISH_MULTIEDGES.

Parameters:

edgeBundleModeMask - the bit mask that defines edge bundles.

See Also:

getEdgeBundleModeMask()

getGroupMode

public byte getGroupMode()

Returns how to handle node grouping.

Returns:

how to handle node grouping.

See Also:

setGroupMode(byte)

setGroupMode

public void setGroupMode(byte groupMode)

Specifies how to handle node grouping. Possible values are GROUP_MODE_IGNORE, GROUP_MODE_ALL_NODES and GROUP_MODE_ORIGINAL_NODES_ONLY.

Parameters:

groupMode - the node grouping specifier.

See Also:

getGroupMode()

getPreferredMaximalDuration

public long getPreferredMaximalDuration()

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

Returns:

the preferred time limit.

See Also:

setPreferredMaximalDuration(long)

setPreferredMaximalDuration

public void setPreferredMaximalDuration(long preferredMaximalDuration)

Sets a preferred time limit (in milliseconds) for the layout algorithm. Note that restricting the maximal duration may result in a worse layout quality. Furthermore, the actual runtime may exceed the maximal duration since the layout algorithm still has to find a valid solution.

Parameters:

preferredMaximalDuration - the preferred time limit.

See Also:

getPreferredMaximalDuration()

getLabelLayouter

public LayoutStage getLabelLayouter()

Returns the algorithm that is used for placing labels. By default an instance of class GreedyMISLabeling will be returned that considers edge labels only.

setLabelLayouter

public void setLabelLayouter(LayoutStage labeler)

Sets the algorithm that is used for placing labels. Note that assigning a new layout stage will not automatically activate it. To activate this stage use setLabelLayouterEnabled(boolean).

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.

Warning: 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.

calcLayout

public MultiPageLayout calcLayout(LayoutGraph graph)

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

Parameters:

graph - the input graph.

Returns:

an object that represents the results of the layout run.

See Also:

MultiPageLayout

removeConnectorPair

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

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. This method removes both connector nodes and restores the original edges. It calls method routeRestoredEdges(y.layout.LayoutGraph, y.base.DataProvider, y.geom.YRectangle) to route these edges.

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:

whether or not the removal of the connector pair was successful. If the method returns false the graph was not changed, i.e., the connector pair was not removed.

See Also:

routeRestoredEdges(y.layout.LayoutGraph, y.base.DataProvider, y.geom.YRectangle)

canLayout

public boolean canLayout(LayoutGraph graph)

Description copied from interface: Layouter

Returns true iff the given graph can be laid out by this algorithm. Calling doLayout with the given graph as its argument will only success if this method returns true.

getMaxPageSize

public YDimension getMaxPageSize()

Returns the maximum size allowed for a single page. The default value is width = height = 1000.

Returns:

the maximum size allowed for a single page.

setMaxPageSize

public void setMaxPageSize(YDimension maxPageSize)

Specifies the maximum size allowed for a single page. The default value is width = height = 1000. Note that a large page size may increase runtime significantly. To limit runtime use method setPreferredMaximalDuration(long).

Parameters:

maxPageSize - the maximum size for a single page.

See Also:

setPreferredMaximalDuration(long)

doIncrementalLayout

protected void doIncrementalLayout(LayoutGraph graph,
                                   DataProvider incrementalNodesDP,
                                   LayoutContext context)

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

Parameters:

graph - the graph to layout.

incrementalNodesDP - a DataProvider that marks nodes that should be placed (nodes for which getBool() returns true). The position of the other nodes is not allowed to change.

context - the current layout context.

See Also:

LayoutContext

routeRestoredEdges

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

Called by method removeConnectorPair(y.base.Node, y.base.Node, y.base.YList, LayoutContext) to route the restored edges.

Parameters:

graph - the relevant graph.

selectedEdgesDP - marks the edges that 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)