Executes a ILayoutAlgorithm and optionally animates the transition to the calculated layout.
Remarks
This class is the preferred way to execute a layout on the current or main thread. The layout animation can be customized in various ways via this class' properties.
If no fine-grained control of the animation is required, the methods applyLayout and applyLayoutAnimated can be used instead.
For larger graphs and complicated layouts that have a greater execution time, blocking the main JavaScript thread of the browser can result in a poor user experience. In order to reduce the blocking time, a Web Worker or an external layout service process may be used. This can be implemented conveniently with the help of the LayoutExecutorAsync class, which is almost fully API compatible to this class, but requires a two-way communication setup between the main thread and the worker thread. It is thus recommended to start with using this approach and potentially blocking the main thread and only switch to the multi-threaded solution in a second step, if required. The code used for the solution, here, can be reused for the asynchronous solution, too.
Related Reading in the Developer's Guide
Type Details
- yFiles module
- view-layout-bridge
See Also
Constructors
Initializes a new instance of the LayoutExecutor class.
Remarks
Parameters
A map of options to pass to the method.
- graphComponent - GraphComponent
- The control which will be animated and provides the IGraph instance.
- layout - ILayoutAlgorithm
- The ILayoutAlgorithm to use.
- cancelDuration - TimeSpan
- The maximum runtime for the layout calculation before it is automatically canceled. This option sets the cancelDuration property on the created object.
- stopDuration - TimeSpan
- The maximum runtime for the layout calculation before it is automatically stopped. This option sets the stopDuration property on the created object.
- configureTableLayout - boolean
- A value indicating whether to automatically perform calls to prepare and restore in order to layout table nodes. This option sets the configureTableLayout property on the created object.
- animationDuration - TimeSpan
- The duration of the animation. This option sets the animationDuration property on the created object.
- labelPlacementPolicies - ItemMapping<ILabel,LabelPlacementPolicy>
- A mapping that specifies how ILabels should be placed by the layout algorithm. This option either sets the value directly or recursively sets properties to the instance of the labelPlacementPolicies property on the created object.
- portPlacementPolicies - ItemMapping<IPort,PortPlacementPolicy>
- A mapping that specifies how IPorts should be placed by the layout algorithm. This option either sets the value directly or recursively sets properties to the instance of the portPlacementPolicies property on the created object.
- animateViewport - boolean
- A value indicating whether the viewport should be animated to the new bounds of the graph. This option sets the animateViewport property on the created object.
- considerViewportLimiter - boolean
- A value indicating whether to respect the viewportLimiter of the GraphComponent of this instance. This option sets the considerViewportLimiter property on the created object.
- easedAnimation - boolean
- A value indicating whether to use eased animation. This option sets the easedAnimation property on the created object.
- targetBoundsPadding - Insets
- The padding (in world coordinates) that will be added to the content bounds when calculating the target viewport. This option sets the targetBoundsPadding property on the created object.
- updateContentBounds - boolean
- A value indicating whether the contentBounds property of the graphComponent should be updated upon completion. This option sets the updateContentBounds property on the created object.
- allowUserInteraction - boolean
- A value indicating whether user interaction should be allowed during the animation. This option sets the allowUserInteraction property on the created object.
- layoutData - LayoutData<INode,IEdge,ILabel,ILabel>
- The layout data that is applied when starting the executor. This option sets the layoutData property on the created object.
- portLabelPolicies - ItemMapping<ILabel,PortLabelPolicy>
- How ILabels at IPorts should be treated by the layout algorithm. This option either sets the value directly or recursively sets properties to the instance of the portLabelPolicies property on the created object.
- anchoredItems - ItemMapping<IModelItem,LayoutAnchoringPolicy>
- The mapping of graph items to LayoutAnchoringPolicy values, specifying which part of the items should be used to anchor the graph during layout. This option either sets the value directly or recursively sets properties to the instance of the anchoredItems property on the created object.
- hideEdgesAtEdges - boolean
- A value that controls whether edges at other edges will be hidden from the layout graph or included. This option sets the hideEdgesAtEdges property on the created object.
- portAdjustmentPolicies - ItemMapping<IPort,PortAdjustmentPolicy>
- The mapping from ports to a policy that specifies how port locations should be adjusted after a layout has been calculated. This option either sets the value directly or recursively sets properties to the instance of the portAdjustmentPolicies property on the created object.
- nodeComparator - function(INode, INode):number
- A comparison function that normalizes the order of the nodes for the layout calculation to ensure the same order for multiple layout invocations. This option sets the nodeComparator property on the created object.
- edgeComparator - function(IEdge, IEdge):number
- A comparison function that normalizes the order of the edges for the layout calculation to ensure the same order for multiple layout invocations. This option sets the edgeComparator property on the created object.
- sequentialExecution - boolean
- A value indicating whether this instance waits for other instances to finish their operations before it executes. This option sets the sequentialExecution property on the created object.
Initializes a new instance of the LayoutExecutor class.
Remarks
Parameters
A map of options to pass to the method.
- graphComponent - GraphComponent
- The control which will be animated and provides the IGraph instance.
- graph - IGraph
- The graph to layout.
- layout - ILayoutAlgorithm
- The ILayoutAlgorithm to use.
- cancelDuration - TimeSpan
- The maximum runtime for the layout calculation before it is automatically canceled. This option sets the cancelDuration property on the created object.
- stopDuration - TimeSpan
- The maximum runtime for the layout calculation before it is automatically stopped. This option sets the stopDuration property on the created object.
- configureTableLayout - boolean
- A value indicating whether to automatically perform calls to prepare and restore in order to layout table nodes. This option sets the configureTableLayout property on the created object.
- animationDuration - TimeSpan
- The duration of the animation. This option sets the animationDuration property on the created object.
- labelPlacementPolicies - ItemMapping<ILabel,LabelPlacementPolicy>
- A mapping that specifies how ILabels should be placed by the layout algorithm. This option either sets the value directly or recursively sets properties to the instance of the labelPlacementPolicies property on the created object.
- portPlacementPolicies - ItemMapping<IPort,PortPlacementPolicy>
- A mapping that specifies how IPorts should be placed by the layout algorithm. This option either sets the value directly or recursively sets properties to the instance of the portPlacementPolicies property on the created object.
- animateViewport - boolean
- A value indicating whether the viewport should be animated to the new bounds of the graph. This option sets the animateViewport property on the created object.
- considerViewportLimiter - boolean
- A value indicating whether to respect the viewportLimiter of the GraphComponent of this instance. This option sets the considerViewportLimiter property on the created object.
- easedAnimation - boolean
- A value indicating whether to use eased animation. This option sets the easedAnimation property on the created object.
- targetBoundsPadding - Insets
- The padding (in world coordinates) that will be added to the content bounds when calculating the target viewport. This option sets the targetBoundsPadding property on the created object.
- updateContentBounds - boolean
- A value indicating whether the contentBounds property of the graphComponent should be updated upon completion. This option sets the updateContentBounds property on the created object.
- allowUserInteraction - boolean
- A value indicating whether user interaction should be allowed during the animation. This option sets the allowUserInteraction property on the created object.
- layoutData - LayoutData<INode,IEdge,ILabel,ILabel>
- The layout data that is applied when starting the executor. This option sets the layoutData property on the created object.
- portLabelPolicies - ItemMapping<ILabel,PortLabelPolicy>
- How ILabels at IPorts should be treated by the layout algorithm. This option either sets the value directly or recursively sets properties to the instance of the portLabelPolicies property on the created object.
- anchoredItems - ItemMapping<IModelItem,LayoutAnchoringPolicy>
- The mapping of graph items to LayoutAnchoringPolicy values, specifying which part of the items should be used to anchor the graph during layout. This option either sets the value directly or recursively sets properties to the instance of the anchoredItems property on the created object.
- hideEdgesAtEdges - boolean
- A value that controls whether edges at other edges will be hidden from the layout graph or included. This option sets the hideEdgesAtEdges property on the created object.
- portAdjustmentPolicies - ItemMapping<IPort,PortAdjustmentPolicy>
- The mapping from ports to a policy that specifies how port locations should be adjusted after a layout has been calculated. This option either sets the value directly or recursively sets properties to the instance of the portAdjustmentPolicies property on the created object.
- nodeComparator - function(INode, INode):number
- A comparison function that normalizes the order of the nodes for the layout calculation to ensure the same order for multiple layout invocations. This option sets the nodeComparator property on the created object.
- edgeComparator - function(IEdge, IEdge):number
- A comparison function that normalizes the order of the edges for the layout calculation to ensure the same order for multiple layout invocations. This option sets the edgeComparator property on the created object.
- sequentialExecution - boolean
- A value indicating whether this instance waits for other instances to finish their operations before it executes. This option sets the sequentialExecution property on the created object.
Properties
Gets the layout graph adapter that is used by this instance to calculate the layout.
Property Value
Gets or sets a value indicating whether user interaction should be allowed during the animation.
Remarks
If false, the WaitInputMode is queried from the CanvasComponent and waiting is enabled during the animation.
The default value is false.
Gets or sets the mapping of graph items to LayoutAnchoringPolicy values, specifying which part of the items should be used to anchor the graph during layout.
Remarks
This property anchors the graph on an initial position based on either a single graph item or the alignment of the bounds of several items (but not the positions of the individual items).
The default LayoutAnchoringPolicy for all items is NONE, meaning items are not anchored unless explicitly specified.
Examples
Use the bounds of all items to anchor the graph, ensuring that the overall structure remains stable:
const layout = new HierarchicalLayout()
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
anchoredItems: LayoutAnchoringPolicy.BOUNDS,
}).start()Alternatively, anchor the graph using the location of a single item. In this example, the upper-left corner of a node is fixed. This is particularly useful when recalculating the layout for scenarios like expanding or collapsing a group node. To provide a seamless user experience, the group node itself remains in the same position, ensuring that the expand/collapse button stays directly under the mouse pointer:
const layout = new HierarchicalLayout()
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
anchoredItems: (item) =>
item === fixedNode
? LayoutAnchoringPolicy.LOWER_LEFT
: LayoutAnchoringPolicy.NONE,
}).start()Gets or sets a value indicating whether the viewport should be animated to the new bounds of the graph.
Remarks
The result when this property is true after the animation is the same as calling fitGraphBounds. Setting this property to true and changing animationDuration to ZERO will disable the animation, but still change the viewport to the new graph bounds.
When the viewport should stay the same, the layout algorithms often have to be coerced to keep parts of the graph in the same location. This can be done by wrapping the layout algorithm in an instance of LayoutAnchoringStage.
The default value is true.
Property Value
true if the viewport should be animated; false otherwise.See Also
Gets or sets the duration of the animation.
Gets or sets the maximum runtime for the layout calculation before it is automatically canceled.
Remarks
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the duration is negative
See Also
Gets or sets a value indicating whether to respect the viewportLimiter of the GraphComponent of this instance.
Remarks
true, but as updating the layout typically also updates the contentBounds, depending on the ViewportLimiter implementation and configuration, this could be set to false, instead.Property Value
Gets or sets a value indicating whether to use eased animation.
Remarks
true.Property Value
true if the animation should be done with eased; false otherwise.See Also
Gets or sets a comparison function that normalizes the order of the edges for the layout calculation to ensure the same order for multiple layout invocations.
Remarks
Among other factors, the results produced by layout algorithms usually depend on the order of the nodes and edges within a graph. Unfortunately, useful operations such as hiding or unhiding elements from a graph or simply invoking layout algorithms on a graph will have the potential side effect of changing that order.
With this comparison it is possible to establish a predefined order of edges within a graph to avoid non-deterministic layout behavior.
Signature Details
function(x: IEdge, y: IEdge) : number
Parameters
Returns
- number
- An integer value which is
<0ifxis less thany,0ifxis equal toy, or>0ifxis greater thany
See Also
Gets the graph this instance is working on.
Property Value
Gets the control this instance has been created for.
Property Value
Gets or sets a value that controls whether edges at other edges will be hidden from the layout graph or included.
Gets or sets a mapping that specifies how ILabels should be placed by the layout algorithm.
Remarks
This setting only affects layout algorithms which support label placement. Also, if EdgeLabelPreferredPlacements are already defined for a label, all values other than KEEP_PARAMETER are ignored for that label.
Default is PREFER_MODEL.
Examples
Maintain the current label positions as much as possible during layout:
const layout = new HierarchicalLayout({
edgeLabelPlacement: EdgeLabelPlacement.INTEGRATED,
})
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
labelPlacementPolicies: LabelPlacementPolicy.PREFER_PARAMETER,
}).start()Customize label placement individually for each label. In this example, the placement policy is determined by the type of the label's owner:
const layout = new HierarchicalLayout({
edgeLabelPlacement: EdgeLabelPlacement.INTEGRATED,
})
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
labelPlacementPolicies: (label) =>
label.owner instanceof INode
? LabelPlacementPolicy.PREFER_MODEL
: LabelPlacementPolicy.PREFER_PARAMETER,
}).start()See Also
Gets the ILayoutAlgorithm this instance is using.
Property Value
Gets or sets a comparison function that normalizes the order of the nodes for the layout calculation to ensure the same order for multiple layout invocations.
Remarks
Among other factors, the results produced by layout algorithms usually depend on the order of the nodes and edges within a graph. Unfortunately, useful operations such as hiding or unhiding elements from a graph or simply invoking layout algorithms on a graph will have the potential side effect of changing that order.
With this comparison it is possible to establish a predefined order of nodes within a graph to avoid non-deterministic layout behavior.
Signature Details
function(x: INode, y: INode) : number
Parameters
Returns
- number
- An integer value which is
<0ifxis less thany,0ifxis equal toy, or>0ifxis greater thany
See Also
Gets or sets the mapping from ports to a policy that specifies how port locations should be adjusted after a layout has been calculated.
Remarks
This can be useful if the port assignment calculated by the layout algorithm is insufficient.
Layout algorithms only consider rectangular nodes even though the actual shape of a node is, for example, circular. Hence, the ports are usually placed at the border of the nodes' bounds (except for some layout algorithms that produce straight-line edge routes and place the ports at the nodes' center).
Based on this setting the edges will be shortened or lengthened in a way that their sourcePorts and targetPorts will be placed on the node's outline.
The default is a constant ItemMapping<TItem,TValue> returning LENGTHEN for all ports.
Examples
Automatically lengthen or shorten edges at all ports if the port is not located on the owner's outline:
const layout = new HierarchicalLayout()
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
portAdjustmentPolicies: PortAdjustmentPolicy.ALWAYS,
}).start()Customize edge adjustments individually for each port. In this example, the policy is determined by the type of the port's owner:
const layout = new HierarchicalLayout()
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
portAdjustmentPolicies: (port) =>
port.owner instanceof INode
? PortAdjustmentPolicy.SHORTEN
: PortAdjustmentPolicy.LENGTHEN,
}).start()See Also
Gets or sets how ILabels at IPorts should be treated by the layout algorithm.
Remarks
Examples
Treat all port labels as edge labels during layout:
const layout = new HierarchicalLayout()
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
portLabelPolicies: PortLabelPolicy.EDGE_LABEL,
}).start()Customize the handling of port labels individually. In this example, the policy is determined by the type of the port's owner:
const layout = new HierarchicalLayout()
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
portLabelPolicies: (label) =>
label.owner instanceof IPort && label.owner.owner instanceof INode
? PortLabelPolicy.NODE_LABEL
: PortLabelPolicy.EDGE_LABEL,
}).start()See Also
Gets or sets a mapping that specifies how IPorts should be placed by the layout algorithm.
Remarks
This setting only affects layout algorithms which support PortCandidates. Also, if PortCandidates are already defined for an edge, they override the current port positions.
Default is PREFER_MODEL.
Examples
Maintain the current port locations as much as possible during layout:
const layout = new HierarchicalLayout()
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
portPlacementPolicies: PortPlacementPolicy.KEEP_SIDE,
}).start()Customize port locations individually for each port. In this example, the placement policy is determined by the type of the port's owner:
const layout = new HierarchicalLayout()
await new LayoutExecutor({
graphComponent: graphComponent,
layout: layout,
portPlacementPolicies: (port) =>
port.owner instanceof INode
? PortPlacementPolicy.KEEP_PARAMETER
: PortPlacementPolicy.PREFER_MODEL,
}).start()See Also
Gets a value indicating whether this instance is currently running.
Property Value
Gets or sets a value indicating whether this instance waits for other instances to finish their operations before it executes.
Remarks
The default value is true. In this case, this instance waits for other instances of LayoutExecutor that handle the same instance of GraphComponent to finish their operation before it executes.
If set to false, this instance ignores other potentially running instances, and doesn't try to stop them but rather executes immediately. Also it will not be stopped by other instances. This should only be used under special circumstances since it can result in race conditions if multiple animations or calculations are performed on the same graph instance.
Gets or sets the maximum runtime for the layout calculation before it is automatically stopped.
Remarks
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the duration is negative
See Also
Gets the tableLayoutConfigurator that is used if configureTableLayout is enabled.
Gets or sets a value indicating whether the contentBounds property of the graphComponent should be updated upon completion.
Remarks
true.Property Value
true if the content bounds should be updated; false otherwise.See Also
Methods
Factory method that creates the IAnimation that will be used by this instance after the layout has been calculated.
Factory method that creates the animation for the IGraph.
Creates the LayoutGraphAdapter which is used when a layout is executed.
Creates an animation that transitions the layout of all ITables in the graph.
Returns
- ↪IAnimation
- An animation that transitions the layout of all ITables in the graph.
Create a new instance of TableLayoutConfigurator that is used if configureTableLayout is enabled.
Remarks
Returns
- ↪TableLayoutConfigurator
- A new instance of the TableLayoutConfigurator class.
Factory method that creates the animation for the viewport.
Remarks
Parameters
A map of options to pass to the method.
- targetBounds - Rect
- The target bounds of the animation.
Returns
- ↪IAnimation
- The animation instance.
See Also
Calculate the target bounds to be used for the contentBounds as well as the ViewportAnimation after the layout has finished.
Returns
- ↪Rect
- The desired content bounds and the bounds for a viewport animation.
Uses tableLayoutConfigurator to prepare a LayoutGridData<TNode,TEdge,TNodeLabel,TEdgeLabel> for the layout.
Remarks
Returns
- ↪LayoutGridData<INode,IEdge,ILabel,ILabel>?
- The configured LayoutGridData<TNode,TEdge,TNodeLabel,TEdgeLabel> instance that's applied to the graph.
Writes the table layout information provided through tableLayoutConfigurator back to all tables.
Remarks
See Also
Actually starts the layout calculation and the optional animation asynchronously using a Promise<void>.
Remarks
This method will ultimately call the execute method. If the animationDuration is zero, no animation will be performed.
If this instance is already running, this method returns immediately without doing anything and returns the previous Promise<void>.
The layout algorithm itself is executed using a LayoutGraphAdapter instance which is created and configured in method createLayoutGraphAdapter.
Although this method returns a Promise and the animation will be performed asynchronously without blocking the UI thread, the actual calculation of the layout will block the UI thread. To mitigate this, check the advice in the developer's guide in the section Using Asynchronous Layout Execution .
Returns
- ↪Promise<void>
- A Promise<void> that will be fulfilled once the layout and optional animation is done.
See Also
Stops a currently running layout calculation or animation.
Remarks
If a layout calculation is still running, it will be requested to stop via stop and the animation will not run. If the layout calculation was already completed, the animation will be aborted immediately and the layout result will be shown immediately.
To just skip the animation but let the calculation finish normally, the animationDuration can be set to zero at any time before the animation was started.
Returns
- ↪Promise<void>
- A promise that will resolve once the layout calculation or animation is stopped.
Static Methods
Makes sure the LayoutExecutor code is not stripped by build optimizations like tree shaking.