This layout algorithm subdivides the input graph into several LayoutGraphs (called page graphs) such that the layout (calculated by the specified coreLayout) of each graph fits the maximumPageSize.
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 coreLayout 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 coreLayout. Note that due to the underlying approach of the MultiPageLayout it doesn't support LayoutGrids. Furthermore, while the MultiPageLayout is able to support groups (see groupingPolicy), 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 weight as much as possible from existing layout support, this layout algorithm implements the ILayoutAlgorithm interface, although method applyLayoutImpl does not specify a return value. Therefore, client code has to set a layoutCallback 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. |
| elementFactory | MultiPageElementFactory | |
| genericLabeling | GenericLabeling | A disabled instance with |
| groupingPolicy | ALL_NODES | Special nodes are also assigned to the associated groups. |
| layoutCallback | null | No layout callback is set. |
| maximumPageSize | 1000x1000 | The width and height of the page are set to 1000. |
| multipleComponentsOnSinglePage | true | Different components may be placed on a single page. |
| stopDuration | MAX_VALUE | The layout algorithm runs unrestricted. |
| strictClusterSeparation | false | Nodes with different cluster IDs may be placed on the same page. |
| useProxyReferenceNodes | true | The algorithm creates proxy reference nodes. |
Type Details
- yFiles module
- algorithms
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
- useProxyReferenceNodes - boolean
- Whether or not the algorithm should create PROXY_REFERENCE nodes. This option sets the useProxyReferenceNodes 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.
- elementFactory - MultiPageElementFactory
- The element factory for creating special nodes and edges during the layout process. This option sets the elementFactory property on the created object.
- layoutCallback - function(MultiPageLayoutResult):void
- A callback that is notified upon completion of multi-page layout calculation. This option sets the layoutCallback property on the created object.
Signature Details
function(obj: MultiPageLayoutResult)Encapsulates a method that has a single parameter and does not return a value.Parameters
- obj - MultiPageLayoutResult
- The parameter of the method that this delegate encapsulates.
- 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.
- multiEdgeConnectorPolicy - MultiEdgeConnectorPolicy
- The policy for defining which multi-edges may share a connector node. This option sets the multiEdgeConnectorPolicy property on the created object.
- groupingPolicy - MultiPageGroupingPolicy
- How to handle special nodes (like connector and proxy nodes) with respect to groups. This option sets the groupingPolicy property on the created object.
- stopDuration - TimeSpan
- The preferred time limit for the layout algorithm. This option sets the stopDuration 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 - Size
- The maximum size of a single page. This option sets the maximumPageSize property on the created object.
- enabled - boolean
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.
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the given additional parent count is negative
Gets or sets the core ILayoutAlgorithm that is wrapped by this stage.
Gets or sets the element factory for creating special nodes and edges during the layout process.
Default Value
Property Value
See Also
Gets or sets a value that determines whether this stage should do anything but execute the coreLayout.
Remarks
By default, when constructed, stages should be enabled. Users may disable a stage's functionality by setting this property to false.
Stages that can guarantee that the graph will not change can choose to not even execute the coreLayout when disabled.
Implements
Gets the labeling algorithm that places the labels of the input graph.
Default Value
Property Value
See Also
Gets or sets how to handle special nodes (like connector and proxy nodes) with respect to groups.
Default Value
Property Value
See Also
Gets or sets a callback that is notified upon completion of multi-page layout calculation.
Default Value
null.No layout callback is set.
Property Value
Signature Details
function(obj: MultiPageLayoutResult)
Parameters
- obj - MultiPageLayoutResult
- The parameter of the method that this delegate encapsulates.
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.
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the specified width or height is not positive
See Also
Sample Graphs
Gets or sets the policy for defining which multi-edges may share a connector node.
Remarks
Default Value
MultiEdgeConnectorPolicy.Share.All split multi-edges use the same connector nodes.
See Also
Gets or sets whether or not different connected components may be placed on a single page.
Default Value
true.Different components may be placed on a single page.
Property Value
true if different connected components may be placed on a single page, false otherwiseGets or sets the preferred time limit for the layout algorithm.
Remarks
Default Value
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the preferred time limit is negative
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.
Property Value
true if the algorithm separates nodes with different cluster IDs, false otherwiseSee Also
Gets or sets whether or not the algorithm should create PROXY_REFERENCE nodes.
Remarks
Default Value
true.The algorithm creates proxy reference nodes.
Property Value
true if the algorithm creates proxy reference nodes, false otherwiseSee Also
Methods
Implementation of the ILayoutAlgorithm interface and main entry point for the layout calculation.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- The graph to apply the layout to.
Implements
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
Throws
- Exception({ name: 'ArgumentError' })
- if no unique ids are defined with NODE_ID_DATA_KEY, EDGE_ID_DATA_KEY, NODE_LABEL_ID_DATA_KEY, or EDGE_LABEL_ID_DATA_KEY.
Implements
createLayoutData
(graph: LayoutGraph) : MultiPageLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the MultiPageLayout.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the graph that determines the generic type arguments of the created layout data
Returns
- ↪MultiPageLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>
- an instance of layout data that can be used to perform item-specific configurations for the given MultiPageLayout.
Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the MultiPageLayout.
Remarks
Parameters
A map of options to pass to the method.
- graph - IGraph
- the graph that determines the generic type arguments of the created layout data
Returns
- ↪MultiPageLayoutData<INode,IEdge,ILabel,ILabel>
- an instance of layout data that can be used to perform item-specific configurations for the given MultiPageLayout.
LayoutExecutor type is available at runtime.Constants
A data key for mapping each edge of the input graph to a unique ID.
A data key for mapping each edge label of the input graph to a unique ID.
A data key for specifying which multi-edges may share a connector node.
Remarks
Multi-edges are edges with the same endpoints. If multi-edges are split because their endpoints are placed on different pages, all multi-edges with the same connector id use the same connector node.
If the predefined multi-edge connector policies for controlling which multi-edges should share connectors are not sufficient for your use case, you can manually select these multi-edges using this data key.
See Also
A data key for assigning a cluster ID to common (non-group) nodes.
Remarks
See Also
A data key for mapping each node of the input graph to a unique ID.
A data key for mapping each node label of the input graph to a unique ID.