C

MultiPageLayout

Show Usages
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).

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

NameDefaultDescription
additionalParentCount0
No additional parent proxies are placed on a page.
coreLayoutnull
elementFactoryMultiPageElementFactory
genericLabelingGenericLabeling
A disabled instance with stopDuration set to ZERO.
groupingPolicyMultiPageGroupingPolicy.ALL_NODES
Special nodes are also assigned to the associated groups.
layoutCallbacknull
No layout callback is set.
maximumPageSize1000x1000
The width and height of the page are set to 1000.
multipleComponentsOnSinglePagetrue
Different components may be placed on a single page.
stopDurationTimeSpan.MAX_VALUE
The layout algorithm runs unrestricted.
strictClusterSeparationfalse
Nodes with different cluster IDs may be placed on the same page.
useProxyReferenceNodestrue
The algorithm creates proxy reference nodes.

See Also

Developer's Guide

Members

Show:

Constructors

MultiPageLayout

(coreLayout?: ILayoutAlgorithm)
Creates a new MultiPageLayout instance.

Parameters

coreLayout?: ILayoutAlgorithm
the layout algorithm used for a single page

Properties

additionalParentCount

: number
Gets or sets 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 coreLayout is an instance of TreeLayout, 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 coreLayout is an instance of TreeLayout.
final

Property Value

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

Throws

Exception ({ name: 'ArgumentError' })
if the given additional parent count is negative

Default Value

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

coreLayout

: ILayoutAlgorithm
Gets or sets the core ILayoutAlgorithm that is wrapped by this stage.
final

Property Value

the core layout routine

Default Value

The default value is: null

enabled

: boolean
Gets or sets a value that determines whether this stage should do anything but execute the coreLayout.

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.

final

genericLabeling

: GenericLabeling
readonly
Gets the labeling algorithm that places the labels of the input graph.
This ILayoutStage needs to be activated in order to take effect.
readonlyfinal

Property Value

The labeling algorithm instance.

Default Value

The default value is: GenericLabeling
A disabled instance with stopDuration set to ZERO.

See Also

API
GenericLabeling, enabled

groupingPolicy

: MultiPageGroupingPolicy
Gets or sets how to handle special nodes (like connector and proxy nodes) with respect to groups.
While the MultiPageLayout is able to handle groups (see groupingPolicy), it doesn't support edges incident to group nodes.
conversionfinal

Property Value

the current node grouping specifier

Default Value

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

See Also

API
CONNECTOR, PROXY

layoutCallback

: function(MultiPageLayoutResult): void
Gets or sets a callback that is notified upon completion of multi-page layout calculation.
final

Property Value

The delegate that will be called when the MultiPageLayoutResult is ready.

Default Value

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

See Also

Developer's Guide

maximumPageSize

: Size
Gets or 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.

A large page size may increase runtime significantly. To limit the runtime use stopDuration.
conversionfinal

Property Value

the maximum size for a single page

Throws

Exception ({ name: 'ArgumentError' })
if the specified width or height is not positive

Default Value

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

Sample Graphs

ShownSetting:

Size 250x250

The whole graph fits onto a single page.

See Also

Developer's Guide
API
stopDuration

multiEdgeConnectorPolicy

: MultiEdgeConnectorPolicy
Gets or sets the policy for defining which multi-edges may share a connector node.
Multi-edges are edges with the same endpoints. For multi-edges that are split because their endpoints are placed on different pages, this policy allows to specify if these multi-edges may use the same connector node.
conversionfinal

Default Value

The default value is: MultiEdgeConnectorPolicy.Share
All split multi-edges use the same connector nodes.

See Also

API
CONNECTOR

multipleComponentsOnSinglePage

: boolean
Gets or sets whether or not different connected components may be placed on a single page.
final

Property Value

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

Default Value

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

stopDuration

: TimeSpan
Gets or sets the preferred time limit for the layout algorithm.
The specified value has to be non-negative.
Restricting the stop duration may result in a worse layout quality. Furthermore, the actual runtime may exceed the stop duration since the layout algorithm still has to find a valid solution.
conversionfinal

Property Value

the preferred time limit

Throws

Exception ({ name: 'ArgumentError' })
if the preferred time limit is negative

Default Value

The default value is: TimeSpan.MAX_VALUE
The layout algorithm runs unrestricted.

See Also

Developer's Guide

strictClusterSeparation

: boolean
Gets or 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.
The cluster IDs are only considered for REGULAR nodes and the associated proxies. CONNECTOR and PROXY_REFERENCE nodes may be placed on any page, otherwise information about the relationships would get lost.
final

Property Value

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

Default Value

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

See Also

API
nodeClusterIds, NODE_CLUSTER_ID_DATA_KEY

useProxyReferenceNodes

: boolean
Gets or sets 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.
final

Property Value

true if the algorithm creates proxy reference nodes, false otherwise

Default Value

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

See Also

API
PROXY_REFERENCE, PROXY

Methods

applyLayout

(graph: LayoutGraph)
Implementation of the ILayoutAlgorithm interface and main entry point for the layout calculation.
This implementation checks the enabled state and when it's not enabled, will delegate to the coreLayout, directly. When the stage is enabled, all the work will be delegated to applyLayoutImpl, instead.
final

Parameters

graph: LayoutGraph
The graph to apply the layout to.

applyLayoutImpl

(graph: LayoutGraph)
protected
Calculates a new multi-page layout for the specified graph.
This method executes the layout algorithm and then notifies the registered layoutCallback, providing the actual MultiPageLayoutResult.
Unlike other implementations of applyLayout method, the result of the layout calculation will not be applied to the input graph.
protected

Parameters

graph: LayoutGraph
the input graph

Throws

Exception ({ name: 'ArgumentError' })

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.
The generic type arguments of the created layout data are compatible with instances of LayoutGraph, but the layout data is not bound to a specific graph instance. Therefore, the created layout data still has to be passed as an argument of applyLayout in order to be applied.

Parameters

graph: LayoutGraph
the graph that determines the generic type arguments of the created layout data

Return Value

MultiPageLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
an instance of layout data that can be used to perform item-specific configurations for the given MultiPageLayout.

createLayoutData

(graph?: IGraph): MultiPageLayoutData<INode, IEdge, ILabel, ILabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to perform item-specific configurations for the MultiPageLayout.
The layout data is not bound to a specific graph instance. Therefore, the created layout data still has to be passed as an argument of applyLayout in order to be applied.
This method is not available unless the module view-layout-bridge is loaded. Either load the module 'view-layout-bridge' explicitly or ensure that the LayoutExecutor type is available at runtime.

Parameters

graph?: IGraph
the graph that determines the generic type arguments of the created layout data

Return Value

MultiPageLayoutData<INode, IEdge, ILabel, ILabel>
an instance of layout data that can be used to perform item-specific configurations for the given MultiPageLayout.

See Also

Developer's Guide

Constants

All constants are filtered. Go to Filters.