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 not 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 considerNodeLabels and considerEdgeLabels.
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 PartitionGrid 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 originalPosition, originalPosition originalWidth and originalHeight 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. computedPosition), 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.
Default Values of Properties
| area | null | There is no area to be filled. |
| componentAssignmentStrategy | CUSTOMIZED | Components can be user-defined and if none are defined, each node is a separate component. |
| considerEdgeLabels | true | Edge labels are considered. |
| considerNodeLabels | true | Node labels are considered. |
| gridSpacing | 0 | No grid is considered. |
| layoutOrientation | NONE | The layout is considered to have no specific orientation. |
| maximumDuration | <code>0x7FFFFFFF</code> | |
| spacing | 10 |
Type Details
- yfiles module
- layout-area
- yfiles-umd modules
- layout-area, layout
- Legacy UMD name
- yfiles.partial.FillAreaLayout
See Also
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.
- maximumDuration - number
The time limit in milliseconds for the layout algorithm. This option sets the maximumDuration property on the created object.
- area - YRectangle
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.
- considerNodeLabels - boolean
Whether or not the layout algorithm considers node labels. This option sets the considerNodeLabels property on the created object.
- considerEdgeLabels - boolean
Whether or not the layout algorithm considers edge labels. This option sets the considerEdgeLabels 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.
See Also
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
- 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.
Default Value
Components can be user-defined and if none are defined, each node is a separate component.
Throws
- Exception({ name: 'ArgumentError' })
- if the specified strategy does not match one of the predefined strategies
See Also
Gets or sets whether or not the layout algorithm considers edge labels.
Remarks
If enabled, edge labels are considered when moving elements such that overlaps with them are not allowed. Furthermore, they are correctly moved along with an edge if an edge is moved.
If disabled, elements that are moved may overlap with edge labels, even if they did not overlap in the input.
Default Value
true.Edge labels are considered.
See Also
Gets or sets whether or not the layout algorithm considers node labels.
Remarks
If enabled, node labels are considered when moving elements such that overlaps with them are not allowed.
If disabled, elements that are moved may overlap with node labels, even if they did not overlap in the input.
Default Value
true.Node labels are considered.
See Also
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.
Throws
- Exception({ name: 'ArgumentError' })
- if the given spacing is negative
See Also
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 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.
Default Value
Throws
- Exception({ name: 'ArgumentError' })
- if the specified orientation does not match one of the predefined orientations
See Also
Gets or sets the time limit in milliseconds for the layout algorithm.
Remarks
0.Default Value
<code>0x7FFFFFFF</code>.Throws
- Exception({ name: 'ArgumentError' })
- if the maximum duration is negative
See Also
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.Throws
- Exception({ name: 'ArgumentError' })
- if the given spacing is negative
See Also
Sample Graphs
Methods
Tries to fill the specified area in the given graph with elements, such that the resulting layout is more compact.
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
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.
Class.ensure(LayoutExecutor) More information.Constants
A data provider key for defining custom components whose elements should preferably not be separated.
Remarks
| Domain | YNode | the nodes of the input graph |
| Values | Object | all nodes associated with the same object are assigned to the same component |
See Also
A data provider key for marking nodes as fixed.
Remarks
| Domain | YNode | |
| Values | boolean | true if the node should be fixed, false otherwise |