Executes an algorithm or ILayoutAlgorithm on a graph asynchronously and optionally animates the transition to the new layout, afterwards.
Remarks
In contrast to LayoutExecutor, this class serves as one half of the pair of two classes that perform the calculation in separate contexts, asynchronously to the main thread that starts the layout. This allows the main thread to continue and the UI to stay responsive when longer layout calculations need to be performed, or multiple layout calculations should be carried out in parallel.
Instances of this class will serialize all the information that is required to execute the algorithm and send that information to a separate context, which processes the data with the help of the LayoutExecutorAsyncWorker class. The context that worker executes in often is a Web Worker, but it could also be running on a different machine or a server.
The actual transmission of the serialized data to the other context is not part of this implementation. Rather, it can be added by means of passing a function callback to the constructor. That function will be given an opaque blob that can be serialized and sent to the second context where it will be processed by a call to process. Once the the response is received from the other context, the function callback resolves the Promise and the results are applied to the graph.
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.LayoutExecutorAsync
See Also
Constructors
LayoutExecutorAsync
(messageHandler: function(Object):Promise<Object>, graphComponent: GraphComponent, layoutDescriptor?: LayoutDescriptor, layoutData?: LayoutData)Creates a new instance of a layout execution helper that will asynchronously perform the calculations and optionally animate the layout on the given graphComponent.
Remarks
messageHandler will be given the serialized information to pass to the layout worker. Once the worker returns the results, the handler will need to resolve the Promise and the results will be deserialized and applied to the graph. If you don't have a graphControl, use the constructor variant that takes the IGraph, instead.Parameters
A map of options to pass to the method.
- messageHandler - function(Object):Promise<Object>
- The function that will send the data to the remote worker. It's an asynchronous function that will need to resolve it's
Promiseonce it receives the processed data from the worker. The parameter passed to (and returned from) the function is JSON serializable and structurally cloneable. Otherwise, the contents of the data blob are considered an implementation detail and may change at any time between releases.Signature Details
function(data: Object) : Promise<Object>Implements message passing between two contexts.LayoutExecutorAsync uses this function to senddatato the LayoutExecutorAsyncWorker. After the worker has performed its task, it will send back the results and the need to be returned (resolved via thePromise) to the calling code. Implementations can expect the values to be JSON serializable and structurally cloneable. Otherwise, the contents of the data blob are considered an implementation detail and may change at any time between releases.Parameters
- data - Object
- The data to send to the
method in the worker context.
Returns
- graphComponent - GraphComponent
- layoutDescriptor - LayoutDescriptor
- The optional descriptor to serialize and send to the worker. This property can later be set and reset via the layoutDescriptor property.
- layoutData - LayoutData
- The optional data that is associated with the graph items that needs to be transferred to the worker. This property can also later be set and reset via the layoutData property.
- 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 graphControl 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 execution and animation. This option sets the allowUserInteraction 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.
- edgePortNodeSize - Size
The size of the nodes that are inserted for the ports that are created for IEdges that are connected at other IEdges. This option sets the edgePortNodeSize 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.
- 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.
- 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.
- cancelDuration - TimeSpan
The duration a layout may run before being cancelled automatically. This option sets the cancelDuration property on the created object.
- stopDuration - TimeSpan
The duration a layout may run before being stopped automatically. This option sets the stopDuration property on the created object.
- sendLabelCandidates - boolean
A value that controls whether the possible candidates for label positions are also serialized. This option sets the sendLabelCandidates property on the created object.
LayoutExecutorAsync
(messageHandler: function(Object):Promise<Object>, graph: IGraph, layoutDescriptor?: LayoutDescriptor, layoutData?: LayoutData)Creates a new instance of a layout execution helper that will asynchronously perform the calculations and apply the results on the provided graph.
Remarks
messageHandler will be given the serialized information to pass to the layout worker. Once the worker returns the results, the handler will need to resolve the Promise and the results will be deserialized and applied to the graph.Parameters
A map of options to pass to the method.
- messageHandler - function(Object):Promise<Object>
- The function that will send the data to the remote worker. It's an asynchronous function that will need to resolve it's
Promiseonce it receives the processed data from the worker. The parameter passed to (and returned from) the function is JSON serializable and structurally cloneable. Otherwise, the contents of the data blob are considered an implementation detail and may change at any time between releases.Signature Details
function(data: Object) : Promise<Object>Implements message passing between two contexts.LayoutExecutorAsync uses this function to senddatato the LayoutExecutorAsyncWorker. After the worker has performed its task, it will send back the results and the need to be returned (resolved via thePromise) to the calling code. Implementations can expect the values to be JSON serializable and structurally cloneable. Otherwise, the contents of the data blob are considered an implementation detail and may change at any time between releases.Parameters
- data - Object
- The data to send to the
method in the worker context.
Returns
- graph - IGraph
- The graph that will be serialized and transferred to the worker.
- layoutDescriptor - LayoutDescriptor
- The optional descriptor to serialize and send to the worker. This property can later be set and reset via the layoutDescriptor property.
- layoutData - LayoutData
- The optional data that is associated with the graph items that needs to be transferred to the worker. This property can also later be set and reset via the layoutData property.
- cancelDuration - TimeSpan
The duration a layout may run before being cancelled automatically. This option sets the cancelDuration property on the created object.
- stopDuration - TimeSpan
The duration a layout may run before being stopped automatically. This option sets the stopDuration 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- edgePortNodeSize - Size
The size of the nodes that are inserted for the ports that are created for IEdges that are connected at other IEdges. This option sets the edgePortNodeSize 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.
Properties
Gets or sets a value indicating whether user interaction should be allowed during the execution and 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 changes 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.
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 the duration a layout may run before being cancelled automatically.
Remarks
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
false.Gets a mapping from edges in the graph to their new layout, after the results are in.
Remarks
Throws
- Exception({ name: 'InvalidOperationError' })
- Throws when the results are not yet available.
See Also
Gets or sets the size of the nodes that are inserted for the ports that are created for IEdges that are connected at other IEdges.
Remarks
3x3.See Also
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_GROUP_ID_DP_KEY and TARGET_GROUP_ID_DP_KEY), strong source and target port constraints are created automatically. The necessary IDataProviders will be created automatically. The edge direction 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.
Remarks
Gets the component this instance has been created for.
Remarks
Gets the component this instance has been created for.
Remarks
See Also
Deprecation warning
Use the graphComponent property instead.Gets or sets a value that controls whether edges at other edges will be hidden from the layout graph or included.
Gets a mapping from labels in the graph to their new layout, after the results are in.
Remarks
Throws
- Exception({ name: 'InvalidOperationError' })
- Throws when the results are not yet available.
See Also
Gets a mapping from labels in the graph to their new layout parameters, after the results are in.
Remarks
Throws
- Exception({ name: 'InvalidOperationError' })
- Throws when the results are not yet available.
See Also
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 or sets the descriptor that will be sent to the worker.
Remarks
See Also
Gets a mapping from nodes in the graph to their new layout, after the results are in.
Remarks
Throws
- Exception({ name: 'InvalidOperationError' })
- Throws when the results are not yet available.
See Also
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.
This happens after the layout result is returned to the main thread and before the results are applied to the graph.
The default value is NEVER.
See Also
true.Gets a mapping from ports in the graph to their new location parameters, after the results are in.
Remarks
Throws
- Exception({ name: 'InvalidOperationError' })
- Throws when the results are not yet available.
See Also
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 graphControl's IGraph instance, the selection model from graphControl is used instead.Gets or sets a value that controls whether the possible candidates for label positions are also serialized.
Remarks
If this property is set to true, the set of possible discrete label position candidates for those labels that support these is also included in the serialized data. The LayoutExecutorAsyncWorker can use this information to setup the labeling information accordingly.
The default is false. Since the candidates are determined for the original graph, this feature is most useful together with a GenericLabeling that only places the labels.
See Also
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, and LayoutExecutorAsync respectively, that work on the same instance of GraphComponent to finish their operation before it starts execution.
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 duration a layout may run before being stopped automatically.
Remarks
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 contentRect property of the graphControl should be updated upon completion.
Remarks
true.Methods
Cancels a currently running layout calculation or animation.
Remarks
If a layout calculation is still running, the results of the other LayoutExecutorAsyncWorker are discarded and not applied to the graph. If the layout calculation was already completed and an animation is running, it will be aborted immediately and the layout result will be applied and shown immediately.
The promise returned from start is resolved immediately, without waiting for pending layout results. Results returned from running workers are silently discarded when passed on to this instance. The workers are not terminated when this method was called.
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.
See Also
Factory method that creates the IAnimation that will be used by this instance after the layout has been calculated.
Remarks
Returns
- ↪IAnimation
- The animation to use after the layout.
See Also
Callback factory method that creates the IRectangle for the given IPort that is used as a dummy to represent the port at the IEdge that owns port.
Parameters
A map of options to pass to the method.
- port - IPort
- The port to create the layout for.
Returns
- ↪IRectangle
- An IRectangle that uses the port's location as the center of the node.
See Also
Factory method that creates the animation for the IGraph.
Remarks
Returns
- ↪IAnimation
- The animation instance.
See Also
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.
Sets up partition grid information from tables in the graph.
Remarks
See Also
Writes the table layout information provided through tableLayoutConfigurator back to all tables.
Remarks
See Also
Triggers the asynchronous execution and returns a Promise that resolves when the calculation is done.
Remarks
This will serialize the graph, as well as selection information, the layoutDescriptor, and the layoutData and send that information via the callback function that was passed to the constructor at construction time to the remote worker
After the results have been returned, they will be parsed by this instance, the results will be applied to the graph, either in an animated fashion or directly.
Returns
- ↪Promise<void>
- The promise to track the progress of the execution.
Throws
- Exception({ name: 'Error' })