This layout algorithm clears a specified area by moving intersecting elements, while trying to minimize the changes in the given layout.
Remarks
Layout Style
The algorithm can be applied if it is necessary to make space within a specific region/area in an existing graph layout. It tries to keep the given layout style as much as possible. Ideally, only local changes in and around the marked area are made, such that the mental map for the user is preserved.
An example application is the use case where new nodes or a whole graph component were added to the graph and should be placed in a specific region of an existing graph layout. The region can then first be cleared using this algorithm such that afterwards the nodes or the component could be inserted without overlaps with other elements. This specific case can conveniently be implemented by defining a set of so-called area nodes, via areaNodes. Another, more general use case would be nodes that grow in size, including the case that a folder node is expanded and converted to a larger group node. This case is easily realized by specifying the expanded node via expandedNode.
Concept
The area, which can be defined as a rectangle or an outline, defines a region in the given input graph which must be cleared. Clearing the area means no graph elements are allowed to intersect with it. This includes nodes and, depending on settings also edges, node labels and edge labels.
In order to clear the area, the graph elements must be moved. Moving an element often induces the necessity to move further elements along with them. Thus, depending on where the area is located in the input drawing, many elements may be moved to make the necessary space. How elements are selected and how they are moved highly depends on the chosen clearing strategy.
Features
For grouped graphs, the group nodes are also correctly handled by this algorithm. However, it is important to note that there is always one so-called area group node. It is the group node inside which the free space should be created and which may in consequence need to grow, see areaGroupNode for more details. When defining the free space via area nodes (see above), this group is automatically determined, otherwise it must explicitly be specified. If not specified, the free space is created in the top-level hierarchy.
The algorithm is able to consider a specified LayoutGrid as long as there are no group nodes that span multiple grid cells. Note that the cleared area is always allocated to a single cell of the grid, i.e., it is not possible that the area spans multiple 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 ClearAreaLayout 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 ClearAreaLayout 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 ClearAreaLayout should be applied, then the 'computed' values of the first algorithm should be written to the 'original' values prior to the run of the ClearAreaLayout.
The algorithm considers port placements constraints only during the rerouting of edges using the specified edgeRouter. The applied routing algorithm must support port placement constraints to have an effect.
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 cleared. |
| clearAreaStrategy | PRESERVE_SHAPES | |
| componentAssignmentStrategy | SINGLE | Each node is a separate component. |
| considerEdges | true | Edges are not allowed to intersect the area. |
| edgeLabelPlacement | CONSIDER | Edge labels intersecting the clearing area are considered and rearranged. |
| edgeRoutingStyle | AUTOMATIC | The routing style is automatically determined. |
| fixPorts | true | Ports are fixed and not allowed to change when adjusting the edge paths. |
| 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
See Also
Constructors
Creates a new instance of ClearAreaLayout with default settings.
Parameters
A map of options to pass to the method.
- clearAreaStrategy - ClearAreaStrategy
- The strategy applied for clearing the desired area. This option sets the clearAreaStrategy property on the created object.
- gridSpacing - number
- The current grid spacing. This option sets the gridSpacing property on the created object.
- edgeRouter - ILayoutAlgorithm
- The custom edge router instance that is applied to reroute edges. This option sets the edgeRouter property on the created object.
- edgeRoutingStyle - PartialLayoutRoutingStyle
- The routing style that is preserved while clearing the area and applied when rerouting edges. This option sets the edgeRoutingStyle 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.
- fixPorts - boolean
- Whether the ports of the input graph must be fixed or if they can be changed. This option sets the fixPorts property on the created object.
- considerEdges - boolean
- Whether or not edges are considered when clearing the area such that no segments intersecting the area are allowed. This option sets the considerEdges property on the created object.
- area - Rect
- The rectangular area that must be cleared. This option sets the area property on the created object.
- areaOutline - BorderLine[]
- The outline describing the shape of the area that must be cleared. This option sets the areaOutline property on the created object.
- layoutOrientation - PartialLayoutOrientation
- The layout orientation that is considered during the clearing of the area. This option sets the layoutOrientation 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 - ClearAreaLayoutEdgeLabelPlacement
- How the layout handles the position of edge labels. This option sets the edgeLabelPlacement property on the created object.
- spacing - number
- The spacing that is considered between elements when they are moved to clear the area. This option sets the spacing property on the created object.
Properties
Gets or sets the rectangular area that must be cleared.
Remarks
Default Value
null.There is no area to be cleared.
Property Value
See Also
Gets or sets the outline describing the shape of the area that must be cleared.
Remarks
- index
0: the top border line - index
1: the right border line - index
2: the bottom border line - index
3: the left border line
Default Value
null.There is no outline to be cleared.
Property Value
Throws
- Exception({ name: 'ArgumentError' })
- if the given array does not contain exactly four non-null
s
See Also
Gets or sets the strategy applied for clearing the desired area.
Remarks
Default Value
Property Value
See Also
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 whether or not edges are considered when clearing the area such that no segments intersecting the area are allowed.
Remarks
If enabled, edges that must be rerouted are not allowed to intersect the area that is cleared. Furthermore, edges whose source and target node are not moved but where segments intersect the area in the input graph are rerouted in order to remove that intersection.
If disabled, edges are allowed to intersect the area that is cleared. This has the effect that the area is cleared of nodes only.
Default Value
true.Edges are not allowed to intersect the area.
Property Value
true if edges are considered and edge intersections with the area are removed, false otherwiseSample Graphs
Gets or sets how the layout handles the position of edge labels.
Default Value
Edge labels intersecting the clearing area are considered and rearranged.
Property Value
See Also
Gets or sets the custom edge router instance that is applied to reroute edges.
Remarks
Several types of edges can be routed by this algorithm:
- Edges where one or both endpoints were displaced in order to clear the area. It depends on the strategy if such edges are actually handled by the routing algorithm or if they are implicitly moved. For example, strategy PRESERVE_SHAPES tries to keep the shapes and can avoid rerouting in many cases.
- So-called inter-edges resulting from the areaNodes component. If such a component exists, the inter-edges are the edges connecting area nodes with non-area nodes. They are always handled by this routing algorithm, independent of the strategy.
- Edges connecting to a specifically marked expandedNode and to the descendants of the expanded node in case it is a group node.
Changing the value of property edgeRoutingStyle automatically sets a new edge router instance according to the specified routing style, thus, overwriting any previously set instances. The following routing algorithms are set:
- EdgeRouter for strategies ORTHOGONAL and OCTILINEAR.
- OrganicEdgeRouter for style ORGANIC.
- StraightLineEdgeRouter for style STRAIGHT_LINE.
Default Value
null.There is no custom router and the routing style is automatically determined.
Property Value
See Also
Gets or sets the routing style that is preserved while clearing the area and applied when rerouting edges.
Remarks
The algorithm assumes that the existing edges have paths according to the specified style and takes this into account when moving nodes and edges in order to clear the area. If the AUTOMATIC style is set, then no assumptions are made but the given paths are analyzed to derive the best fitting routing style. Note that in this case, the algorithm may use different routing styles for the edges.
This routing style is also relevant when edges need to be rerouted, as it determines the routing algorithm used for rerouting, see edgeRouter for more details.
Default Value
Property Value
See Also
Gets or sets whether the ports of the input graph must be fixed or if they can be changed.
Remarks
This property is relevant for edges that are rerouted in order to clear the area, i.e., edges where one or both endpoints are displaced or edges that intersect the area in the input graph (depending on property considerEdges) and that are consequently handled by the specified edgeRouter. Inter-edges resulting from the areaNodes component are not affected by this property (edges connecting area nodes with non-area nodes). For such edges, the behavior is the same as if this property would be disabled, see the following description. The same applies for edges incident to the expandedNode or the descendants of the expanded node (if one endpoint is not the expanded node or a descendant).
If the ports are fixed, then the port side and location are not changed, except for group nodes that grow due to the area inside them. Edges at these groups keep the port side, but the absolute location is not fixed.
If disabled, the algorithm considers specified LayoutPortCandidates when rerouting edges. If there are no such constraints for an edge, then the ports of that edge can be freely placed. This can often produce better edge routes in the resulting drawing, however, the overall shape of the edge may then not be preserved.
Default Value
true.Ports are fixed and not allowed to change when adjusting the edge paths.
Property Value
true if ports of the input are fixed, false otherwiseGets 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 clearing of the area.
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
See Also
Gets or sets the spacing that is considered between elements when they are moved to clear the area.
Remarks
This spacing only affects the moving of elements out of the area. Elements keep the specified distance to other elements. Carefully observe that if the distance between two elements is already smaller, then they may not be moved apart.
Strategies PRESERVE_SHAPES, PRESERVE_SHAPES_UNIFORM and GLOBAL consider the spacing for all graph elements, including nodes, edges, node labels and edge labels when they are encountered during the movement process. On the other hand, strategies LOCAL and LOCAL_UNIFORM consider the spacing only with respect to nodes.
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
Throws
- Exception({ name: 'ArgumentError' })
- if the stop duration is negative
See Also
Methods
Clears the specified rectangular area, the area defined via areaNodes or expandedNode by moving all other graph elements currently intersecting with it.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
Clears the specified rectangular area, the area defined via areaNodes or expandedNode by moving all other graph elements currently intersecting with it.
Creates and sets the value of the property areaOutline of the layout determined from the items.
Remarks
Parameters
A map of options to pass to the method.
- items - IEnumerable<IModelItem>
- The IModelItems from which the BorderLines are determined.
- spacing - number
- The spacing that is considered between the area and the elements.
- closed - boolean
- Whether the area is closed or can be traversed by other elements (without overlaps).
LayoutExecutor type is available at runtime.createAreaOutline
(graph: LayoutGraph, areaNodes: IEnumerable<LayoutNode>, areaEdges: IEnumerable<LayoutEdge>) : BorderLineCreates the outline that describes the shape of the given nodes and edges.
Remarks
This method is called when the area to be cleared is derived from a specified set of area nodes, see areaNodes. The outline is defined by four BorderLines, which are then used as the areaOutline for the layout run.
The default implementation of this method includes the bounds of the given nodes, the bounds of the segments of the given edges, as well as the bounds of the corresponding node and edge labels (depending on the properties nodeLabelPlacement and edgeLabelPlacement. This method may be overridden if another way of deriving the area shape from the defined nodes and edges is desired (e.g. if only nodes shall be considered, ignoring edges).
The returned array must contain exactly four BorderLine instances where the indices are interpreted as follows:
- index
0: the top border line - index
1: the right border line - index
2: the bottom border line - index
3: the left border line
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
- areaNodes - IEnumerable<LayoutNode>
- the nodes that are part of the area that should be cleared
- areaEdges - IEnumerable<LayoutEdge>
- the edges that are adjacent to the given area nodes
Returns
- ↪BorderLine[]
- an array of four BorderLines describing the outline of the area to be cleared
createLayoutData
(graph: LayoutGraph) : ClearAreaLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the ClearAreaLayout.
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
- ↪ClearAreaLayoutData<LayoutNode,LayoutEdge,LayoutNodeLabel,LayoutEdgeLabel>
- an instance of layout data that can be used to perform item-specific configurations for the given ClearAreaLayout.
Returns an instance of LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> that can be used to perform item-specific configurations for the ClearAreaLayout.
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
- ↪ClearAreaLayoutData<INode,IEdge,ILabel,ILabel>
- an instance of layout data that can be used to perform item-specific configurations for the given ClearAreaLayout.
See Also
LayoutExecutor type is available at runtime.Moves the areaOutline by the given delta.
Remarks
Parameters
A map of options to pass to the method.
- delta - IPoint
- the delta to move the areaOutline
Constants
A data key for specifying the group node inside which the cleared area should be located.
Remarks
The area that is cleared of elements can be associated to one specific group node. This means that this group can grow because the free space must be created inside it. In consequence, all ancestor nodes of the group may grow, too. Other groups are treated as fixed and must be moved in order to avoid an overlap with the specified area.
If no group is specified, the free space will be created in the top-level hierarchy.
See Also
Sample Graphs
A data key for specifying a set of nodes that define the area which should be cleared.
Remarks
Assign true to a node if it should be considered part of the area component, or false otherwise.
These nodes define a sort of component from which the area that must be cleared is derived by calling method createAreaOutline . This means that the area will exactly be defined by the current locations of these nodes (including the edges among them) such that after the algorithm execution there will not be any other elements intersecting with them.
Carefully observe that if group nodes are marked, all their descendants are treated as area nodes too.
The area group node can not be defined manually, but the nearest common ancestor of all area nodes will become the area group node. For group nodes other than the area group either all their descendants including the group itself must be area nodes or all their descendants including the group must not be area nodes. If the input is not complete in this matter, the required nodes are internally automatically treated as area nodes too.
See Also
Sample Graphs
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 the node that was expanded and, thus, defines the area that must be cleared.
Remarks
The value true is assigned if the node was enlarged, and false otherwise.
When an expanded node is provided, the area that must be cleared is directly derived from the size of the expanded node. Defining an expanded node is intended for the case that a node's size increased such that it might now overlap with other graph elements. This includes the use case of expanding a folder node.
It is strongly recommended to additionally provide the original (smaller) bounds of the expanded node via EXPANDED_NODE_ORIGINAL_BOUNDS_DATA_KEY. If the node has incident edges, it is also recommended to provide the original paths of these edges via key EXPANDED_NODE_ORIGINAL_EDGE_PATH_DATA_KEY, i.e. the edge paths before the size of the node was changed (for example, before expanding a folder node). This includes paths of edges that were only incident to the non-expanded node and are now incident to descendants of it. Using this knowledge the algorithm clears the area occupied by the expanded node but also considers how the layout looked before the change. This way the mental map may be preserved to a higher degree.
See Also
A data key for specifying the original, non-expanded bounds of the expanded node.
Remarks
See Also
A data key for associating original paths for edges connecting to the expanded node, including edges that did so only when the node was not yet expanded.
Remarks
When an expanded node is provided, the area that must be cleared is directly derived from the bounds of the expanded node. The original paths together with the original, non-expanded (smaller) bounds (see EXPANDED_NODE_ORIGINAL_BOUNDS_DATA_KEY) of the expanded node are helpful to preserve the mental map of the overall drawing by providing knowledge about the previous layout state. Note, however, that only strategies PRESERVE_SHAPES, PRESERVE_SHAPES_UNIFORM and GLOBAL will significantly profit from it.
Carefully observe that the original paths must correspond to the ones that were valid when the expanded node still had its original, non-expanded bounds. Thus, they should only be provided when the original bounds are provided too.