ClearAreaLayout

• CUSTOMIZED: the components can be user-defined. If the user does not specify any, there are no components that should explicitly be kept together, which is equal to the behavior of SINGLE.
• 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.

When enabled, the edge labels intersecting the area are explicitly rearranged even if the corresponding edges would not be changed.

If disabled, edge labels may remain intersecting with the area. In addition, after moving elements to clear the area, there may be new edge label overlaps.

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.

Internally, nodes are treated like they would have a size including their labels. Therefore, layout results can get significantly less compact if this feature is enabled.

If this feature is disabled, node labels may remain intersecting with the area. In addition, after moving elements to clear the area, there may be new node label overlaps.

Several types of edges can be routed by this algorithm:

1. Edges where one or both endpoints where 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.
2. So-called inter-edges resulting from the area nodes 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.
3. Edges connecting to a specifically marked expanded node and to the descendants of the expanded node in case it is a group node.

Changing the value of property edgeRoutingStrategy automatically sets a new edge router instance according to the specified routing strategy, thus, overwriting any previously set instances. The following routing algorithms are set:

• EdgeRouter for strategies ORTHOGONAL and OCTILINEAR.
• OrganicEdgeRouter for strategy ORGANIC.
• StraightLineEdgeRouter for strategy STRAIGHTLINE.

The algorithm assumes that the existing edges have paths according to the specified strategy and takes this into account when moving nodes and edges in order to clear the area. If the automatic strategy is set, then no assumptions are made but the given paths are analyzed to derive the best fitting routing strategy. Note that in this case, the algorithm may use different routing styles for the edges.

This routing strategy is also relevant when edges need to be rerouted, as it determines the routing algorithm used for rerouting, see edgeRouter for more details.

This property is relevant for edges that are rerouted in order to clear the area, i.e., edges where one or both endpoints where displaced or edges that intersect the area in the input graph (depending on property considerEdges) and that are consequently handled by the specified edge router. Inter-edges resulting from the area nodes 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 expanded node 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 PortConstraint and PortCandidates 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.

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.

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 directions, 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.

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.

This method may be overridden to customize the settings of the applied routing algorithm without manually specifying a custom router instance. This can be beneficial because the basic configuration of the router has already been made upon calling this method (e.g. setting up the scope). This method can then be implemented to fine-tune further settings, like, for example, minimum distance values.

The type of the given instance depends on the edge routing strategy.

• EdgeRouter for strategies ORTHOGONAL and OCTILINEAR.
• OrganicEdgeRouter for strategy ORGANIC.
• StraightLineEdgeRouter for strategy STRAIGHTLINE.
• If strategy AUTOMATIC is selected, one of the mentioned types is chosen, depending on the style of the given edge routes.
• If a custom edgeRouter is set, its instance corresponds to that of the parameter.

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.

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.

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_DP_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_DP_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.

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_DP_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.