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 morphLayout 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
- yfiles-umd modules
- view-layout-bridge
- Legacy UMD name
- yfiles.layout.LayoutExecutor
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.
- 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.
- duration - TimeSpan
The duration of the animation. This option sets the duration property on the created object.
- automaticEdgeGrouping - boolean
A value indicating whether edge groups are automatically created for edges that are connected to the same port. This option sets the automaticEdgeGrouping property on the created object.
- fixPorts - boolean
A value that controls whether strong port constraints are automatically created. This option sets the fixPorts property on the created object.
- labelPreferredPlacementPolicy - LabelPreferredPlacementPolicy
How ILabels at IEdges should be placed by the layout algorithm. This option sets the labelPreferredPlacementPolicy 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.
- targetBoundsInsets - Insets
The insets (in world coordinates) that will be added to the content rectangle when calculating the target viewport. This option sets the targetBoundsInsets property on the created object.
- updateContentRect - boolean
A value indicating whether the contentRect property of the graphComponent should be updated upon completion. This option sets the updateContentRect 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
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 sets the portLabelPolicies 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.
- portAdjustmentPolicy - PortAdjustmentPolicy
The policy that specifies how port locations should be adjusted after a layout has been calculated. This option sets the portAdjustmentPolicy 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.
- selectionModel - ISelectionModel<IModelItem>
The ISelectionModel<T> to use for the automatically registered IDataProvider instances for AFFECTED_NODES_DP_KEY and AFFECTED_EDGES_DP_KEY. This option sets the selectionModel property on the created object.
Initializes a new instance of the LayoutExecutor class.
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.
- 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.
- duration - TimeSpan
The duration of the animation. This option sets the duration property on the created object.
- automaticEdgeGrouping - boolean
A value indicating whether edge groups are automatically created for edges that are connected to the same port. This option sets the automaticEdgeGrouping property on the created object.
- fixPorts - boolean
A value that controls whether strong port constraints are automatically created. This option sets the fixPorts property on the created object.
- labelPreferredPlacementPolicy - LabelPreferredPlacementPolicy
How ILabels at IEdges should be placed by the layout algorithm. This option sets the labelPreferredPlacementPolicy 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.
- targetBoundsInsets - Insets
The insets (in world coordinates) that will be added to the content rectangle when calculating the target viewport. This option sets the targetBoundsInsets property on the created object.
- updateContentRect - boolean
A value indicating whether the contentRect property of the graphComponent should be updated upon completion. This option sets the updateContentRect 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
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 sets the portLabelPolicies 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.
- portAdjustmentPolicy - PortAdjustmentPolicy
The policy that specifies how port locations should be adjusted after a layout has been calculated. This option sets the portAdjustmentPolicy 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.
- selectionModel - ISelectionModel<IModelItem>
The ISelectionModel<T> to use for the automatically registered IDataProvider instances for AFFECTED_NODES_DP_KEY and AFFECTED_EDGES_DP_KEY. This option sets the selectionModel property on the created object.
Properties
Gets the AbortHandler that is used during the layout calculation, unless another AbortHandler has been configured via layoutData or by registering an IMapper<K,V> in the graph's mapperRegistry.
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 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 duration 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 FixNodeLayoutStage.
The default value is false.
See Also
Gets or sets a value indicating whether edge groups are automatically created for edges that are connected to the same port.
Remarks
If this property is enabled and no edge groups are explicitly created (no IMapper<K,V> are registered for the keys SOURCE_GROUP_ID_DP_KEY and TARGET_GROUP_ID_DP_KEY), for each port with multiple outgoing resp. incoming edges these edges will be assigned to the same edge group. The necessary IDataProviders will be created automatically.
Without an ILayoutAlgorithm that supports edge groups, this property has no visual effect.
The default value is true.
See Also
Gets or sets a value indicating whether to respect the viewportLimiter of the GraphComponent of this instance.
Remarks
false.Gets or sets the duration of the animation.
Gets or sets a value indicating whether to use eased animation.
Gets or sets a value that controls whether strong port constraints are automatically created.
Remarks
If this property is enabled and no port constraints have been added explicitly (no IMapper<K,V> are registered for the keys SOURCE_PORT_CONSTRAINT_DP_KEY and TARGET_PORT_CONSTRAINT_DP_KEY), strong source and target port constraints are created automatically. The necessary IDataProviders will be created automatically. The PortSide is inferred from the location of the port relative to the node.
This ensures that view IPorts are not moved during the layout, if the ILayoutAlgorithm supports port constraints.
The default value is false.
See Also
Gets the graph this instance is working on.
Gets the control this instance has been created for.
Gets or sets a value that controls whether edges at other edges will be hidden from the layout graph or included.
Gets or sets how ILabels at IEdges should be placed by the layout algorithm.
Remarks
This setting only affects layout algorithms which support label placement. Also, if PreferredPlacementDescriptors are already defined this setting is ignored.
Default is FROM_DESCRIPTOR.
Examples
const layout = new HierarchicLayout({ integratedEdgeLabeling: true })
await new LayoutExecutor({
graphComponent: graphComponent,
graph: graphComponent.graph,
layout: layout,
labelPreferredPlacementPolicy: 'from-parameter'
}).start()See Also
Gets the ILayoutAlgorithm this instance is using.
Gets the layout graph that is used by this instance to calculate the layout.
Gets or sets the 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' bounding boxes (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 value is NEVER.
See Also
true.Gets or sets how ILabels at IPorts should be treated by the layout algorithm.
Remarks
See Also
Gets or sets the ISelectionModel<T> to use for the automatically registered IDataProvider instances for AFFECTED_NODES_DP_KEY and AFFECTED_EDGES_DP_KEY.
Remarks
null and graph is the same instance as graphComponent's IGraph instance, the selection model from graphComponent is used instead.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 the tableLayoutConfigurator that is used if configureTableLayout is enabled.
Gets or sets a value indicating whether the contentRect property of the graphComponent should be updated upon completion.
Methods
Creates an instance of AbortHandler.
Remarks
Returns
- ↪AbortHandler
- A new AbortHandler instance to use during layout calculation.
Factory method that creates the IAnimation that will be used by this instance after the layout has been calculated.
Creates the LayoutGraphAdapter which is used when a layout is executed.
Factory method that creates the animation for the IGraph.
Creates an animation that morphs 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 contentRect as well as the ViewportAnimation after the layout has finished.
Remarks
Returns
- ↪Rect
- The desired content rectangle and the bounds for a viewport animation.
Set up tableLayoutConfigurator for a layout.
Remarks
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 duration 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 stopped 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 duration can be set to zero at any time before the animation was started.