Clear and Fill Area Layout
Class ClearAreaLayout is a layout algorithm that clears a user-specified area in a given input graph layout. Therefore, it moves elements intersecting this area, while trying to minimize the changes in the given layout of the graph.
Class FillAreaLayout is a counterpart of ClearAreaLayout and tries to fill a user-specified area by moving elements towards it.
Both clearing and filling of an area has several practical applications. We can, for example, add a new node or a whole subgraph component to an existing graph layout at a specific location and use ClearAreaLayout to ensure that there is enough space such that there are no overlaps between the new component’s elements and the existing nodes (see areaNodes). Another, more general use case that requires clearing of an area are nodes that grow in size, like a folder node that is expanded and converted to a larger group node and, thus, requires more space. Analogously, folding a group node is a possible use-case for FillAreaLayout as well as removing nodes/subgraph components from a given graph layout.
The result produced by FillAreaLayout is not the exact inverse of that of ClearAreaLayout, i.e., applying both algorithms successively using the same area doesn’t yield the original layout. Furthermore, FillAreaLayout doesn’t guarantee that the area is filled with elements after calling the algorithm.
Input
Both algorithms, ClearAreaLayout and FillAreaLayout, assume that the input graph has a suitable layout that should be maintained. For the specification of the area both algorithms allow to define a rectangle that must be cleared or should be filled, respectively. Fore more information, see area and area.
ClearAreaLayout also allows to provide an array of type BorderLine that specifies the outline that must be cleared. This input allows to describe more complex shapes, i.e., a BorderLine for each of the four sides of the area. Fore more information, see areaOutline.
Furthermore, ClearAreaLayout provides two more ways for specifying the area. They are described in the following two sections.
Area defined by a set of nodes (AreaNodes)
The user can specify a set of nodes that define the area which should be cleared, see property areaNodes (or AREA_NODES_DP_KEY). The clear area will exactly be defined by the current locations of these nodes (including the edges among them) such that, after the layout run, there won’t be any other elements intersecting with them (the nodes of this set are not moved). This type of input is convenient, e.g., if a sub-set of nodes was moved to new locations or if multiple new nodes were added to the diagram.
Area defined by a single expanded node
The property expandedNode allows to define a single node for which it is assumed that it changed size (i.e. was enlarged) and, therefore, the area defined by the enlarged bounds of the node must be cleared of any other elements. Specifying the area this way is especially convenient when implementing a folder expansion use-case where a folder node is expanded (revealing its content) such that it now requires more space. Note that the now visible descendant nodes of the expanded folder are not moved. Of course, it must not be a folder node but can also just be any node which was enlarged for some reason.
This kind of input is similar to the AreaNodes discussed in the previous section, but it expects only a single changed node and offers an advantage when used in conjunction with properties expandedNodeOriginalBounds and expandedNodeOriginalEdgePaths. The properties provide information about the diagram state before expanding the node. Considering this additional information, the algorithm tries to preserve the mental map of the diagram. The expandedNodeOriginalBounds are the bounds of the node before the size was changed. The expandedNodeOriginalEdgePaths are the paths of all edges adjacent to the node before the size was changed. This should include edges that are now connect to descendants of the expanded folder and did connect to the folder only before expansion.
The ways for specifying the input described in the last two sections exclude each other and may not be used at the same time.
Basic Options
The most important options to configure ClearAreaLayout are mentioned in the following.
ClearAreaStrategy
clearAreaStrategy specifies the strategy applied for clearing the desired area.
- LOCAL
- This approach clears the area by trying to minimize the number of moved nodes, changing the layout rather locally.
- LOCAL_UNIFORM
- This approach is very similar to LOCAL but moves all necessary nodes by a uniform offset.
- PRESERVE_SHAPES
- This approach clears the area while trying to preserve the shape of the existing edge paths. Preserving the shapes means that the direction of the edge segments is not changed and no new bends are created. The segment lengths may change in order to generate free space.
- PRESERVE_SHAPES_UNIFORM
- This approach is very similar to PRESERVE_SHAPES but moves all elements by a uniform offset.
- GLOBAL
- This approach clears the area by globally partitioning the input into two parts and moving them apart. The division can be vertical or horizontal.
Figure Comparison of Clear Area Strategies shows the difference between some of the different strategies.
More Settings for ClearAreaLayout
There are several additional settings that allow to customize the processing of the ClearAreaLayout. The following list gives an overview (for more details, see the API documentation):
- componentAssignmentStrategy
- considerEdgeLabels
- considerNodeLabels
- considerEdges
- edgeRoutingStrategy
- fixPorts
- gridSpacing
- layoutOrientation
- maximumDuration
- spacing
The most important options to configure the FillAreaLayout are mentioned in the following.
Settings for FillAreaLayout
The following settings allow to customize the processing of the FillAreaLayout:
Layout Data
When using class ClearAreaLayout, supplemental layout data for a graph’s elements can be specified either by using class ClearAreaLayout or by registering data providers with the graph using given look-up keys. Supplemental layout data for ClearAreaLayout lists all properties of ClearAreaLayoutData and the corresponding look-up keys that ClearAreaLayout tests during the layout process in order to query supplemental data.
Providing supplemental layout data is described in detail in Layout Data.
| ClearAreaLayoutData Property | Data Provider Key | Element Type | Value Type | Description |
|---|---|---|---|---|
Analogously, when using class FillAreaLayout, supplemental layout data for a graph’s elements can be specified either by using class FillAreaLayout or by registering data providers with the graph using given look-up keys. Supplemental layout data for FillAreaLayout lists all properties of FillAreaLayoutData and the corresponding look-up keys that FillAreaLayout tests during the layout process in order to query supplemental data.
| FillAreaLayoutData Property | Data Provider Key | Element Type | Value Type | Description |
|---|---|---|---|---|