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.
Remarks
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).
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. Furthermore, while the MultiPageLayout is able to support groups (see groupingMode), 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, 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.
Default Values of Properties
| additionalParentCount | 0 | No additional parent proxies are placed on a page. |
| createProxyReferenceNodes | true | The algorithm creates proxy reference nodes. |
| edgeBundleModeMask | 0 | All multi-edges belong to the same edge bundle. |
| elementFactory | DefaultElementFactory | If no element factory is set explicitly, the algorithm uses an instance of |
| groupingMode | ALL_NODES | Special nodes are also assigned to the associated groups. |
| labeling | GenericLabeling | An instance of 0. |
| labelingEnabled | false | The given labeling algorithm does not place labels. |
| layoutCallback | null | No layout callback is set. |
| maximumDuration | <code>0x7FFFFFFF</code> | The layout algorithm runs unrestricted. |
| maximumPageSize | 1000x1000 | The width and height of the page are set to 1000. |
| multipleComponentsOnSinglePage | true | Different components may be placed on a single page. |
| strictClusterSeparation | false | Nodes with different cluster IDs may be placed on the same page. |
Type Details
- yfiles module
- layout-multipage
- yfiles-umd modules
- layout-multipage, layout
- Legacy UMD name
- yfiles.multipage.MultiPageLayout
See Also
Constructors
Creates a new MultiPageLayout instance.
Parameters
A map of options to pass to the method.
- coreLayout - ILayoutAlgorithm
- the layout algorithm used for a single page
- createProxyReferenceNodes - boolean
Whether or not the algorithm should create proxy reference nodes. This option sets the createProxyReferenceNodes property on the created object.
- strictClusterSeparation - boolean
Whether or not the algorithm should separate nodes with different cluster IDs. This option sets the strictClusterSeparation property on the created object.
- labelingEnabled - boolean
Whether or not the given labeling algorithm places the labels of the input graph. This option sets the labelingEnabled property on the created object.
- elementFactory - IElementFactory
The element factory for creating special nodes and edges in a multi-page layout. This option sets the elementFactory property on the created object.
- layoutCallback - ILayoutCallback
The callback that is notified upon completion of multi-page layout calculation runs. This option sets the layoutCallback property on the created object.
- additionalParentCount - number
The number of additional tree parent proxies that the algorithm tries to place on a page. This option sets the additionalParentCount property on the created object.
- edgeBundleModeMask - EdgeBundleModes
The bit mask for defining edge bundles. This option sets the edgeBundleModeMask property on the created object.
- groupingMode - GroupingMode
How to handle special nodes (like connector and proxy nodes) with respect to groups. This option sets the groupingMode property on the created object.
- maximumDuration - number
The preferred time limit (in milliseconds) for the layout algorithm. This option sets the maximumDuration property on the created object.
- labeling - ILayoutStage
The ILayoutStage that places the labels of the input graph. This option sets the labeling property on the created object.
- multipleComponentsOnSinglePage - boolean
Whether or not different connected components may be placed on a single page. This option sets the multipleComponentsOnSinglePage property on the created object.
- maximumPageSize - YDimension
The maximum size of a single page. This option sets the maximumPageSize property on the created object.
See Also
Properties
Gets or sets the number of additional tree parent proxies that the algorithm tries to place on a page.
Remarks
Default Value
0.No additional parent proxies are placed on a page.
Throws
- Exception({ name: 'ArgumentError' })
- if the given additional parent count is negative
Gets or sets the core layout algorithm that is wrapped by this stage.
Gets or sets whether or not the algorithm should create proxy reference nodes.
Remarks
Default Value
true.The algorithm creates proxy reference nodes.
See Also
Gets or sets the bit mask for defining edge bundles.
Remarks
Default Value
0.All multi-edges belong to the same edge bundle.
See Also
Gets or sets the element factory for creating special nodes and edges in a multi-page layout.
Remarks
Default Value
If no element factory is set explicitly, the algorithm uses an instance of
See Also
Gets or sets how to handle special nodes (like connector and proxy nodes) with respect to groups.
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if the specified group mode is unknown
See Also
Gets or sets the ILayoutStage that places the labels of the input graph.
Gets or sets whether or not the given labeling algorithm places the labels of the input graph.
Remarks
Default Value
false.The given labeling algorithm does not place labels.
See Also
Gets or sets the callback that is notified upon completion of multi-page layout calculation runs.
Default Value
null.No layout callback is set.
See Also
Gets or sets the preferred time limit (in milliseconds) for the layout algorithm.
Remarks
Default Value
<code>0x7FFFFFFF</code>.The layout algorithm runs unrestricted.
Throws
- Exception({ name: 'ArgumentError' })
- if the preferred time limit is negative
See Also
Gets or sets the maximum size of a single page.
Remarks
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.
Default Value
1000x1000.The width and height of the page are set to 1000.
Throws
- Exception({ name: 'ArgumentError' })
- if the specified width or height is not positive
See Also
Sample Graphs
Gets or sets whether or not the algorithm should separate nodes with different cluster IDs.
Remarks
Default Value
false.Nodes with different cluster IDs may be placed on the same page.
See Also
Methods
applyIncrementalLayout
(graph: LayoutGraph, incrementalNodesDP: IDataProvider, context: LayoutContext)This method is called to further improve the layout results.
Remarks
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
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
- incrementalNodesDP - IDataProvider
- 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
Domain YNode Values boolean trueif the node is marked,falseotherwise - context - LayoutContext
- the current layout context
See Also
Calculates a new multi-page layout for the specified graph.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
Invokes the layout process of the core layout algorithm.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Defined in
Calculates a new multi-page layout for the specified graph.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Returns
- ↪MultiPageLayoutResult
- an instance of MultiPageLayoutResult that represents the result of the layout run
Throws
- Exception({ name: 'ArgumentError' })
- if for one of the keys NODE_ID_DP_KEY, EDGE_ID_DP_KEY, NODE_LABEL_ID_DP_KEY and EDGE_LABEL_ID_DP_KEY no IDataProvider is registered with the given graph
See Also
This method creates the element factory for multi-page layouts.
Remarks
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
- ↪IElementFactory
- the created element factory
See Also
removeConnectorPair
(connector1: YNode, connector2: YNode, originalEdgeIds: YList, context: LayoutContext) : booleanThis method is called during a postprocessing step that reduces the number of connectors.
Remarks
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.
Subclasses may implement a custom remove/restore strategy.
Parameters
A map of options to pass to the method.
- connector1 - YNode
- the first connector of the connector pair
- connector2 - YNode
- the second connector of the connector pair
- originalEdgeIds - YList
- the IDs of the original edges that have to be restored
- context - LayoutContext
- the current layout context
Returns
- ↪boolean
trueif the removal of the connector pair was successful,falseotherwise
See Also
false the graph was not changed, i.e., the connector pair still exists.routeRestoredEdges
(graph: LayoutGraph, selectedEdgesDP: IDataProvider, boundingRectangle: YRectangle)This method is called whenever some single edges have to be routed without changing the position of nodes (e.g., by removeConnectorPair to route the restored edges).
Remarks
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
A map of options to pass to the method.
- graph - LayoutGraph
- the relevant graph
- selectedEdgesDP - IDataProvider
- a IDataProvider that returns a boolean value indicating whether or not an edge should be rerouted
Domain Edge Values boolean trueif an edge should be rerouted,falseotherwise - boundingRectangle - YRectangle
- the edge routes should be fully contained within this rectangle
See Also
Constants
A data provider key for mapping each edge of the input graph to a unique ID.
| Domain | Edge | the edges of the input graph |
| Values | Object | an arbitrary object that defines a unique ID for an edge |
See Also
A data provider key for mapping each edge label of the input graph to a unique ID.
| Domain | IEdgeLabelLayout | the edge labels of the input graph |
| Values | Object | an arbitrary object that defines a unique ID for an edge label |
See Also
A data provider key for specifying the type of multi-edges.
Remarks
| Domain | Edge | the edges of the input graph |
| Values | Object | an arbitrary object that specifies the type of an edge |
See Also
A data provider key for assigning a cluster ID to common (non-group) nodes.
| Domain | YNode | the common (non-group) nodes of the input graph |
| Values | Object | nodes associated with the same object (cluster ID) should preferably be placed on the same page |
See Also
A data provider key for mapping each node of the input graph to a unique ID.
| Domain | YNode | the nodes of the input graph |
| Values | Object | an arbitrary object that defines a unique ID for a node |
See Also
A data provider key for mapping each node label of the input graph to a unique ID.
| Domain | INodeLabelLayout | the node labels of the input graph |
| Values | Object | an arbitrary object that defines a unique ID for a node label |