This layout algorithm tries to fill a specified area with graph elements by moving nearby elements towards it, with the goal to make the existing layout more compact and not changing it too much.
Remarks
Layout Style
The algorithm can make an existing layout more compact in the region of the defined area. It moves nearby graph elements, while keeping the given layout style as much as possible. Ideally, only local changes around the marked area are made such that the mental map for the user is preserved. The best applications are those where it shall be avoided to calculate a completely new layout after local changes have been made to an already existing and good layout. Also note that the results for this application are much better when the edge paths are already good orthogonal, polyline or octilinear paths. For straight-line edge routes, the shape and overall mental map of the layout can not be preserved that well and the changes may be more global.
An example application is the use case that nodes were removed from the graph. The region where the nodes have been removed can then be defined as the area so that the algorithm can try to fill/use this free space and make the layout more compact. This way it can be avoided to compute a completely new layout for such cases. Another use case would be when a group node is collapsed and converted to a smaller folder node. In that case the folder node should be marked as fixed. Note that it isn't guaranteed that the area is filled with elements after calling the algorithm.
Concept
The area (see area) defines a region in the given graph which should be filled with elements, with the goal to make the overall layout more compact. To do so, graph elements must be moved. This includes nodes, edges and their labels. Whether node labels and edge labels should be considered can be controlled via settings nodeLabelPlacement and edgeLabelPlacement.
Keep in mind that the goal is to make the layout more compact. Therefore, if the area is located such that it brings no advantage to move elements towards it, the algorithm may also do nothing - based on a heuristic decision. This means that it does not fill the specified area in any case.
Features
The algorithm is able to consider a specified LayoutGrid as long as there are no group nodes that span multiple grid cells. For this feature to work properly it is required that the values of the properties position, position, width and height are correctly specified. This is usually automatically the case when executing the FillAreaLayout as a standalone algorithm via layout execution convenience methods (e.g. the values are taken from the table visualization of the grid). However, if the FillAreaLayout is applied as part of a more complex layout pipeline it may be necessary to specify the values manually. For example, if another algorithm previously computed the grid position values and stored them in the respective 'computed' properties (e.g. position), and afterwards FillAreaLayout should be applied, then the 'computed' values of the first algorithm should be written to the 'original' values prior to the run of the FillAreaLayout.
Layout Stages
This class provides a configurable pipeline that contains various ILayoutStages. Each ILayoutStage can incorporate preprocessing or postprocessing steps into the layout calculation to streamline the input graph and enhance the resulting layout. Additionally, custom ILayoutStages can be added and executed either before or after the predefined ones.
The following default ILayoutStages are included:
- GenericLabeling: Efficiently places node and edge labels. The property fillEmptyScope is set to
falseand stopDuration is set to ZERO.
With these layoutStages the layout algorithm is configured well, so they usually don't need to be changed.
Default Values of Properties
| area | null | There is no area to be filled. |
| componentAssignmentStrategy | SINGLE | Each node is a separate component. |
| edgeLabelPlacement | CONSIDER | Edge labels are considered. |
| gridSpacing | 0 | No grid is considered. |
| layoutOrientation | NONE | The layout is considered to have no specific orientation. |
| nodeLabelPlacement | CONSIDER | Node labels are considered. |
| spacing | 10 | |
| stopDuration | MAX_VALUE |
Type Details
- yFiles module
- algorithms
Constructors
Creates a new instance of FillAreaLayout with default settings.
Parameters
A map of options to pass to the method.
- gridSpacing - number
- The current grid spacing. This option sets the gridSpacing property on the created object.
- componentAssignmentStrategy - ComponentAssignmentStrategy
- The strategy that assigns nodes to components whose elements should preferably not be separated. This option sets the componentAssignmentStrategy property on the created object.
- stopDuration - TimeSpan
- The time limit for the layout algorithm. This option sets the stopDuration property on the created object.
- area - Rect
- The rectangular area that should be filled. This option sets the area property on the created object.
- spacing - number
- The spacing that is considered between elements when they are moved. This option sets the spacing property on the created object.
- nodeLabelPlacement - NodeLabelPlacement
- How the layout handles the position of node labels. This option sets the nodeLabelPlacement property on the created object.
- edgeLabelPlacement - FillAreaLayoutEdgeLabelPlacement
- How the layout handles the position of edge labels. This option sets the edgeLabelPlacement property on the created object.
- layoutOrientation - PartialLayoutOrientation
- The layout orientation that is considered during the compaction process. This option sets the layoutOrientation property on the created object.
Properties
Gets or sets the rectangular area that should be filled.
Remarks
Default Value
null.There is no area to be filled.
Property Value
null (default) or if it is specified and contains all elements of the graph, the algorithm terminates without changing anything.Gets or sets the strategy that assigns nodes to components whose elements should preferably not be separated.
Remarks
To define custom components instead of using the predefined strategies, use componentIds. In this case, the value of componentAssignmentStrategy will be ignored.
While the algorithm may move a whole component, it tries to not move only a subset of its elements, thus, all elements of a component are not moved at all or moved by the same offset.
- CONNECTED components are defined by the connected components of the graph.
- CLUSTERING: components are defined by edge betweenness clustering.
- SINGLE: each node is a separate component which basically means that there are no components that should explicitly be kept together.
Default Value
Property Value
See Also
Gets or sets how the layout handles the position of edge labels.
Default Value
Property Value
Gets the GenericLabeling helper class from the layoutStages of this instance.
Remarks
Throws
- Exception({ name: 'InvalidOperationError' })
- If there is no instance of the respective type in the
Gets or sets the current grid spacing.
Remarks
Elements are moved by multiples of this value, thus, keeping their offset to the grid. That way, components or parts of them that were placed on a grid before, will stay on their original grid.
The grid spacing needs to be a non-negative value. If it is set to 0, no grid is considered.
Default Value
0.No grid is considered.
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the given spacing is negative
Gets or sets the layout orientation that is considered during the compaction process.
Remarks
The orientation affects the direction that the algorithm prefers when moving elements. For the vertical orientations TOP_TO_BOTTOM and BOTTOM_TO_TOP, moving elements horizontally (i.e. to the left and to the right) is preferred. For the horizontal orientations LEFT_TO_RIGHT and RIGHT_TO_LEFT, the vertical moving direction is preferred. This is mainly useful for layouts that have a clear direction and nodes are divided into layers with respect to this direction, like e.g., hierarchical layouts.
If this behavior is undesired, the orientation can be ignored by specifying NONE. No specific moving direction will be preferred in that case. The orientation can also be automatically detected based on the flow direction of the edges when choosing AUTO_DETECT.
Default Value
Property Value
Gets the mutable stack of ILayoutStage that will be applied to this layout.
Gets or sets how the layout handles the position of node labels.
Default Value
Property Value
Gets or sets the spacing that is considered between elements when they are moved.
Remarks
This spacing only affects the moving of elements towards the desired area. Elements keep the specified distance to other elements and among each other. Carefully observe that if the distance between two elements is already smaller, then they may not be moved apart.
The spacing is considered for all graph elements, including nodes, edges, node labels, and edge labels when they are encountered during the movement process.
Default Value
10.Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the given spacing is negative
Sample Graphs
Gets or sets the time limit for the layout algorithm.
Remarks
Default Value
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the stop duration is negative
Methods
Tries to fill the specified area in the given graph with elements, such that the resulting layout is more compact.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Implements
Tries to fill the specified area in the given graph with elements, such that the resulting layout is more compact.
Creates and sets the value of the property area of the layout determined from the items.
Parameters
A map of options to pass to the method.
- items - IEnumerable<IModelItem>
- The IModelItems from which the rectangular area is determined.
LayoutExecutor type is available at runtime.createLayoutData
(graph: LayoutGraph) : FillAreaLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the FillAreaLayout.
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
- ↪FillAreaLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>
- an instance of layout data that can be used to perform item-specific configurations for the given FillAreaLayout.
Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the FillAreaLayout.
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
- ↪FillAreaLayoutData<INode,IEdge,ILabel,ILabel>
- an instance of layout data that can be used to perform item-specific configurations for the given FillAreaLayout.
LayoutExecutor type is available at runtime.Constants
A data key for defining custom components whose elements should preferably not be separated.
Remarks
All nodes associated with the same Object are assigned to the same component.
While the algorithm may move a whole component, it should preferably not move only a subset of its elements. This means that the algorithm tries to move all elements of a component by the same offset (if at all). In order to achieve good results with this feature, the different components should not overlap in the initial drawing.
See Also
A data key for marking nodes as fixed.
Remarks
true to a node to mark it as fixed. This node will not be moved by this algorithm but stay at its current position.