HierarchicalLayout

When running in fromSketchMode,, the alternative edge paths are considered during the routing of fixed (i.e., non-incremental) edges.

The alternative paths should be used in conjunction with alternative group bounds to achieve more stable layout results when collapsing/expanding a group node as follows:

1. Collapsing: edges adjacent to the group itself and edges where one of the endpoints (source/target) lies inside the group should get the path before collapsing the group as alternative path. If both endpoints are either inside or outside the group, no alternative path is required.
2. Expanding: edges adjacent to the expanded folder node (which is now a group) should get the path before expanding as alternative path.

Assign a collection of Points to an edge as the alternative path of this edge connecting to the content of the expanded/collapsed group or null for all other edges.

When running in fromSketchMode, the alternative bounds of the collapsed/expanded group will be used during the layering and sequencing phase of the algorithm.

Assign a Rect as the alternative bounds of a collapsed/expanded group or null for all other nodes.

Critical edges highlight different edge paths that are relevant for a user. The layout tries to vertically align each node pair that is connected by a critical edge. Conflicts between different critical edges are always resolved in favor of the higher priority.

Critical edges do not automatically affect the result of the crossing minimization phase. If crossings between critical edges should be avoided, one can assign individual crossing costs by using EDGE_CROSSING_COST_DATA_KEY. Critical edges need to get a larger crossing cost than other, non-critical edges. This is recommended if critical edges should not only highlight a relevant path but also crossings with them should be avoided. Note, however, that the crossing minimization is only a heuristic and there is no guarantee for an optimal solution in all cases.

Assign the positive priority value for a critical edge, or, to indicate a non-critical edge, use zero or any negative value.

The crossing costs of the edges are considered during the crossing minimization phase. The total crossing costs are minimized using a heuristic where the cost of a crossing between two edges is defined as the product of the edges' crossing costs.

If no individual crossing costs are defined, each crossing has a cost of 1. A crossing with an edge that has a cost of zero is cost-free and such a crossing will therefore not be avoided.

When using recursive edges (recursiveEdgePolicy) in fromSketchMode, edges will also start at the bottom and end at the top of marked folder nodes. This will keep the edge routes more stable since the connection sides won't change.

Assign true if the node is a folder node, or false otherwise.

Assign a GridComponentDescriptor to an edge to mark the edge and its source and target nodes as part of the represented grid component or null for edges that are not in such a component.

All edges with the same GridComponentDescriptor instance adjacent to a specific node (the root) and having the same direction are arranged in a compact, bus-like way. The edgeDirectedness is also considered here. The direction defines the placement of the grid component in the following way:

• Grid nodes connected by out-edges of the root are placed in layers starting with the layer immediately after the root's layer (e.g. below the root for top-to-bottom layout orientation).
• Grid nodes connected by in-edges of the root are placed in the layers ending with the layer immediately before the root's layer (e.g. above the root for top-to-bottom layout orientation).

The grid components are arranged using a style that yields more compact layout results. Edges to the child nodes, the so-called grid nodes, are routed using a shared segment that connects to the common root node. The grid nodes are arranged using several layers above or below the root node such that the whole substructure has a compact area. By default, each grid layer contains equally many grid nodes, grid nodes of adjacent layers are center-aligned and the shared bus segment is routed in the middle of the nodes. This produces compact, symmetric arrangements of the grid components.

The arrangement can be customized for each grid component individually, by using the settings offered by GridComponentDescriptor. It allows to configure the number of grid nodes before and after the common bus segment.

Some restrictions apply for grid components:

• Only nodes that are in the same LayoutGridCellDescriptor as the root node are included in the grid component.
• The grid nodes must all belong to the same group node. Also, a group node can not be part of a grid component; neither as grid element nor as the root.
• Grid structures can not be nested. That means that if a node is a grid node it can not be a root node of another grid component at the same time.
• For bus edges, the integrated edge labeling feature does not place port labels as close to the actual port as it does for other edges (see AT_SOURCE_PORT and AT_TARGET_PORT).
• Edge grouping constraints at the side of the grid root node are ignored for bus edges; the grouping induced by the grid component is considered to be stronger.
• If in incremental layout mode, the bus edges are always treated in an incremental way to ensure that the bus-style routing remains consistent (e.g. if a fixed bus edge contains bends that suggest another route, they are ignored). Furthermore, the location of the bus segment relative to the elements is not derived from the sketch but depends on the settings maximumNodesBeforeBus and maximumNodesAfterBus as well as the before/after constraints defined by nodesBeforeBus. This means that it can happen that a fixed grid node which was placed before the bus in the input drawing may be placed after the bus if the bus was enlarged due to the insertion of incremental grid nodes.
• It is not recommended to define grid components inside a group node which has an incremental group hint. Fixed grid nodes inside such a group are not necessarily kept fix but are treated like an incrementally inserted node.

Like edge crossing costs, these costs are considered during the crossing minimization phase. The total costs are minimized using a heuristic where the cost of a crossing between a group node border and an edge is defined as the product of the respective group border crossing cost and the edge crossing cost.

If no individual crossing costs are defined, the cost for crossing a group node border is 5. This means that by default, a crossing between an edge and a group node border is more expensive than a crossing between two edges. Also note that a crossing with a group node border that has a cost of zero is cost-free and such a crossing will therefore not be avoided.

Assign a HierarchicalLayoutSubcomponentDescriptor to a node to specify its subcomponent bor null if the node should not be part of a specific subcomponent.

A subcomponent is arranged by another ILayoutAlgorithm and its layout is finally embedded into the global hierarchical layout. This feature allows, for example, to highlight special substructures by arranging them in a different fashion. The sub-layout algorithm must be specified in the component descriptor registered with this key. All nodes associated with the same HierarchicalLayoutSubcomponentDescriptor instance are members of the same subcomponent.

Carefully note that nodes of a subcomponent can be connected to nodes of another subcomponent as well as to nodes that are not part of any subcomponent. Edges that model these connections are so-called inter-edges. It is recommended to keep the number of inter-edges small for better overall integration of the components.

If all inter-edges of a subcomponent connect to the same external node, that single external so-called connector node is included in the calculation of the component layout when using placement policy AUTOMATIC or ALWAYS_INTEGRATED. In case the result is feasible, this results in a better and more compact integration of the component in the main layout. In that case the sub-layout is fully responsible for the routing of inter-edges (meaning the restrictions below may not apply anymore).

For inter-edges there apply some restrictions with respect to the supported features:

• Their general style can somewhat differ from other, normal hierarchical edges. They do not fully comply with all RoutingStyleDescriptor settings.
• The backLoopRouting style is not applied for the part of an inter-edge that connects to a subcomponent node.
• The minimumFirstSegmentLength and the minimumLastSegmentLength can not always be fulfilled for the side of an inter-edge that lies inside a subcomponent. It is still kept on the side outside of subcomponents.
• The node-to-edge distance can not always be kept between inter-edges and nodes inside a subcomponent. This will mostly appear if a subcomponent has a rather large number of inter-edges connecting to it.
• The INTEGRATED edge labeling does not guarantee full support for all EdgeLabelPreferredPlacement configurations for inter-edges. This affects the side of the inter-edge that lies inside a subcomponent and when the label should be placed near the component node, i.e., using settings AT_SOURCE, AT_SOURCE_PORT, AT_TARGET or AT_TARGET_PORT.

subcomponents can be defined on grouped graphs with the following restrictions:

• All subcomponent nodes must be on the same hierarchy level if the group node itself is not part of the subcomponent.
• If a group is assigned to a subcomponent, all its descendants (including other group nodes) must be in that component, too.

When running in fromSketchMode, it is still up to the sub-layout algorithm to decide whether to treat a subcomponent element as incremental or fixed. If the given layout of the subcomponent should be considered, then the from-sketch mode of the used layout algorithm needs to be enabled (if such a mode is supported).

Layering and sequencing constraints are supported for subcomponents in the following way: all constraints from the subcomponent nodes are transferred to the component itself. Constraints between nodes of the same component are ignored. In the same way, a given layering provided by GivenLayersAssigner is supported for subcomponents.

Assign true to a group node if its children should be arranged in a tabular fashion, or false otherwise.

Children of marked groups are arranged in a compact tabular fashion as shown in the figure below. Groups contained in a tabular group behave like tabular groups as well.

Child nodes are placed next to each other within the same layer with a distance defined by tabularGroupChildDistance, which is zero by default.

There are some setups for which a tabular group may not be tight (i.e., maximally compact):

• If edges directly connect to a tabular group (not to its content), then it is not guaranteed that the group becomes maximally compact. Children may be placed a little further apart to fulfill the defined edgeDistance.
• The same is true if there are children with self-loops. Such self-loops are always drawn within the tabular group.
• In addition, labels of edges connecting two children of the same tabular group may intersect with other edge segments.

Besides, the tabular groups may not be tight if there are user specified constraints like node margins, node labels that exceed the size of the associated child node, and port constraints connecting to a side orthogonal to the layout orientation.

Assign true to a group node if its ports should be uniformly distributed, or false otherwise.

This setting only affects the two sides of a group node that are in flow and against the flow of the layout orientation. For example, for orientation TOP_TO_BOTTOM only the edges incident to the top and bottom group node side are considered but not the edges at the left and right side.

If no IMapper<K,V> is registered with this key, then the ports at group nodes are not explicitly distributed in a uniform way.

The uniform group port assignment considers the edgeDistance such that two ports keep the specified distance to each other. Group nodes may in consequence be enlarged to satisfy that constraints, potentially generating less compact layouts. The distance from the group node border to the first/last port on each group side may be influenced by using group node padding.

Importantly, it is not guaranteed that the group node ports of a specific side can be uniformly distributed. In the following cases ports of a specific side are not uniformly distributed:

1. There are edges that cross the group node border because they connect to a child node of the group.
2. There is a self-loop at the group node which has its source and target port at the same group node side.