HierarchicLayout

More precisely, the specified value is the minimum distance between the two vertical segments of these edges that traverse the layer. The algorithm does not consider this value if the layer contains other elements lying between the two edges (e.g., nodes or group node borders).

All values have to be greater than or equal to 0.

The layouter assigns the nodes to separate layers. The nodes within each layer will be placed on the same horizontal layer. The layers will be arranged vertically starting with the small-numbered layers.

An important layering strategy for the hierarchic layout style is called Hierarchical Layering. A hierarchical layering tries to assign nodes to layers in a way such that as much edges of the graph as possible will point to the main layout direction, i.e., the start nodes of the edges will be in a layer with a smaller number than the corresponding end nodes. Also, a hierarchical layering will never put two connected nodes in the same layer.

This method wraps the internal implementations into a MultiComponentLayerer instance so that it is possible to specify the behavior of the algorithm if the component layouter is disabled.

To define the desired placement for each label add a PreferredPlacementDescriptor on IEdgeLabelLayout.

This method is a convenience method that assures that the labeling algorithm is of type LabelLayoutTranslator and translateEdgeLabels is set to true.

If this option is enabled, groups are layered recursively, i.e.

• nodes in the same group always occupy adjacent layers
• layer intervals spanned by different group nodes are either disjoint or are nested

If it is disabled, group information is ignored for the layering step.

If the graph is flat, this setting is ignored.

By then, each node will be assigned to a layer. Since the sequencing and drawing phases are skipped, the order of the nodes within a layer matches the initial order of the nodes, edges won't be routed and the nodes won't get coordinates assigned.

The calculated layering information can be retrieved from the IDataProvider registered with the key LAYER_INDEX_DP_KEY.

By then, each node will be assigned to a layer and will have a place in the sequence of nodes in this layer. Since the drawing phase is skipped, edges won't be routed and the nodes won't get coordinates assigned.

The calculated layering and sequencing information can be retrieved from the IDataProviders registered with the keys LAYER_INDEX_DP_KEY and SEQUENCE_INDEX_DP_KEY.

This method is called by applyLayoutCore before the actual layout is calculated. It may be overridden in order to manually reconfigure the core layout algorithm.

This implementation will temporarily set a PortCandidateOptimizer if a IDataProvider is registered with NODE_PORT_CANDIDATE_SET_DP_KEY and no portConstraintOptimizer is assigned.

This method may be overridden to create a new HierarchicLayoutCore object with different configuration settings.

This factory method provides the initial HierarchicLayoutCore instance.

The instance is usually bound to Graph instance graph, i.e., if the input graph for the layerer changes, a new instance must be retrieved. This instance can be used for creating constraints for this graph instance.

You can create an instance without binding it to a graph instance initially by passing a null parameter. In that case, you must bind the returned instance to the graph, see LAYER_CONSTRAINTS_MEMENTO_DP_KEY and memento.

This method is called by applyLayoutCore after the actual layout is calculated. It may be overridden in order to revert a custom configuration made in configureCoreLayout.

This implementation will remove the PortCandidateOptimizer that was created in case a IDataProvider is registered with NODE_PORT_CANDIDATE_SET_DP_KEY and no portConstraintOptimizer was initially assigned.

When running in incremental layout mode, 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.

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

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

The bus substructures are arranged using a style that yields more compact layout results. Edges to the child nodes, the so-called bus nodes, are routed using a shared segment that connects to the common root node. The bus nodes are arranged using several layers above or below the root node such that the whole substructure has a compact area. By default, each bus layer contains equally many bus nodes, bus 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 bus structures.

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

There apply some restrictions for bus structures:

• Bus structures can not be nested/interleaved. More precisely, each node can only be part of a single bus. Note that the root node is considered to be a part of the bus, i.e., if a node is a bus node it can not be a root node of another bus at the same time.
• Only nodes that are in the same partition grid cell or same swimlane as the root node are included in the bus structure.
• The bus nodes must all belong to the same group node. Also, a group node can not be part of a bus structure; neither as bus element nor as root.
• Nodes that are contained in a tabular group node cannot be part of a bus structure.
• 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 bus root node are ignored for bus edges; the grouping induced by the bus structure is considered to be stronger.
• If in incremental layout mode, the bus edges are always treated in an incremental way such that the bus-style routing remains consistent (e.g. if a fixed bus edge contains bends that suggest another route, they are ignored). The reason is that the bus-style layout of the structures has higher priority. 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 (see PLACE_BEFORE_BUS_DP_KEY). This means that it can happen that a fixed bus 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 bus nodes.
• It is not recommended to define buses inside a group node which has an incremental group hint. Fixed bus nodes inside such a group are not necessarily kept fix but are treated like an incrementally inserted node.

Critical edges highlight different edge paths that are relevant for a user. The layouter 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_DP_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.

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.

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.

A subcomponent is arranged by another layout algorithm 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 HierarchicLayoutSubcomponentDescriptor 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 HierarchicLayoutRoutingStyle settings.
• The backloop routing style is not applied for the part of an inter-edge that connects to a subcomponent node.
• The minimum first segment length and the minimum last segment length 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 PreferredPlacementDescriptor 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 incremental mode, 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 GivenLayersLayerer is supported for subcomponents.

The layout algorithm will arrange nodes in swimlanes according to the registered descriptors.

Layout information about the swimlanes is finally written back to the descriptor instances. Instances can be shared among multiple nodes in the same lane.

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 edge-to-edge distance.
• 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 halos, node labels that exceed the size of the associated child node, and port constraints connecting to a side orthogonal to the layout orientation.

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 IDataProvider 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 edge-to-edge distance 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 insets.

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.