The hierarchically arranged layers that are typical for this layout style (hence its name) are illustrated in Figure 10.26, “Layers in the hierarchical layout style”. With top-to-bottom main direction, layers stretch horizontally and are ordered from top to bottom. Within each layer, the nodes are placed vertically and are ordered from left to right.

Figure 10.26. Layers in the hierarchical layout style

The node order within a layer is also called their sequence. The layer ordering in a diagram is also referred to as the layering. Generally, the overall orientation of the edges is the same as the main direction of the layout, and is also the direction of the layering. In other words, if the main direction of the layout is right-to-left, for example, then also the layering is from right to left.

The terms layering and sequence directly stem from the technical operation of a hierarchical layout algorithm where the layout is generated in a three-phase process, basically:

The hierarchical layout style is ideal for many application areas where it is crucial that dependency relations between entities are clearly visualized. In particular, if such relations form a chain of dependencies between entities, this layout style nicely exhibits them. Generally, whenever the direction of information flow matters, the hierarchical layout style is an invaluable tool.

Application areas that this layout style is suited for include, for example:

The following figures show sample diagrams from different application areas.

Figure 10.27. Samples of the hierarchical layout style

Entity-Relationship diagram.	Displays pathways of the brain, layered by stages of visual processing.	Decision diagram.

Table 10.22, “Relevant classes for this style” lists the relevant classes for the hierarchical layout style.

Table 10.22. Relevant classes for this style

Phase	Classname	Description
	IncrementalHierarchicLayouter	Main algorithm. See the description below.
	NodeLayoutDescriptor	Provides node-related as well as layer-related layout options. For example, preferred minimum distances between adjacent nodes within a layer. See Related Classes.
	EdgeLayoutDescriptor	Provides edge-related layout options. For example, different edge routing styles for different edge types. See Related Classes.
	IIncrementalHintsFactory	Creates so-called hint objects which are essential for incremental hierarchical layout. See Incremental Layout Mode.
Layering	ILayerer	An implementation of this interface is responsible for assigning the nodes of a graph to layers in a hierarchical layout. In the section called “Layer Assignment Options” available layering strategies for non-incremental layout calculation are presented.
	ILayerConstraintFactory	Enables convenient customization of the layering process where the nodes of a graph are assigned to layers in a hierarchical layout. See Constrained Layer Assignment.
Sequence	DefaultLayerSequencer	Used to determine the order of nodes within a layer.
	ISequenceConstraintFactory	Enables custom node order assignment within layers. See Node Order Options.
Drawing	SimplexNodePlacer	This node placer is responsible for assigning each node within a layer its coordinate with respect to the node sequence. See also the description of SimplexNodePlacer.
	DefaultDrawingDistanceCalculator	Is used by the NodePlacer to determine distances between graph elements within a layer.

The classes that are used in the layering phase provide many predefined so-called layering strategies that enable a variety of different layout results. Instead of letting the algorithm compute the layering, some strategies also support prescribing the layering completely. Additionally, in cases where only some nodes need to fulfill specific layering requirements, the LayerConstraintFactory class can be used.

Similarly, in the sequence phase, the node orders within the layers, which are computed by DefaultLayerSequencer, can be customized via the services provided by the SequenceConstraintFactory class.

Besides IncrementalHierarchicLayouter, the yFiles diagramming library includes two legacy layout algorithms for the hierarchical layout style, namely, classes HierarchicLayouter and HierarchicGroupLayouter. IHL supersedes both these classes and adds additional features like sophisticated swimlane layout support or incremental layout support. See also the section called “Related Layout Algorithms”.

The LayoutMode property determines the general layout mode of IncrementalHierarchicLayouter. It uses one of the following constants from the LayoutMode enumeration:

FromScratch

Incremental

LayoutOrientation LayoutOrientation { get; set; }

IncrementalHierarchicLayouter ihl = new IncrementalHierarchicLayouter();
// Use left-to-right main layout direction.
ihl.LayoutOrientation = LayoutOrientation.LeftToRight;

Figure 10.28, “Layout orientation sample” shows one of the sample layouts for the hierarchical layout style with layout orientation left to right.

Figure 10.28. Layout orientation sample

Hierarchical layout with layout orientation left to right.

long MaximalDuration { get; set; }

IncrementalHierarchicLayouter allows to control general drawing options like, e.g., edge routing styles or minimum distances between graph elements.

Options which affect edge routing:

bool OrthogonalRouting { get; set; }

bool BackloopRouting { get; set; }

IncrementalHierarchicLayouter supports three edge routing styles:

The following figure shows the different routing styles side by side. Note that using the above property, only the former two styles can be configured. Octilinear edge routing can be enabled using a corresponding EdgeLayoutDescriptor, see also the section called “Related Classes”.

Figure 10.29. Edge routing styles determined by the EdgeLayoutDescriptor

Polyline edge routing.	Orthogonal edge routing (with rounded bends).	Octilinear edge routing.

// 'ihl' is of type
// yWorks.yFiles.Layout.Hierarchic.IncrementalHierarchicLayouter.

// Switching IHL to orthogonal edge routing.
ihl.OrthogonalRouting = true;

IncrementalHierarchicLayouter places the nodes in a way that reflects the main flow of a diagram, i.e. in a top-to-bottom layout most edges will connect to targets which are placed below their source nodes. However, it is not always possible to achieve this for all edges in a diagram. Edges which connect to targets which are located above their source nodes are referred to as "backloop edges". By default these edges exit their source nodes at the top border and enter their targets at the bottom to keep the paths short. This may reduce the readability of a hierarchical layout as shown in the left diagram of Figure 10.30, “Backloop Routing”.

Setting backloop routing enabled will force backloop edges to exit at the bottom and enter at the top of their source and target, respectively, emphasizing the main direction of the diagram. Backloop routing is enabled in the right diagram of Figure 10.30, “Backloop Routing”.

Figure 10.30. Backloop Routing

Backloop Routing disabled.	Backloop Routing enabled.

Options which affect node placement:

double MinimumLayerDistance { get; set; }

double NodeToNodeDistance { get; set; }

double EdgeToEdgeDistance { get; set; }

double NodeToEdgeDistance { get; set; }

Figure 10.31, “Distance settings in a hierarchical layout” illustrates where the settings for the drawing options take effect in a diagram.

Figure 10.31. Distance settings in a hierarchical layout

Note that the distance settings between edges and also between edges and nodes only take effect on edges that span at least one layer in the diagram. Also, keep in mind that all distances are only minimum distances, i.e., the layout algorithm may use larger distances than specified in order to achieve an aesthetic result.

Further drawing style options can be specified by means of the layout descriptor classes for nodes and edges. One instance of each class is held by IHL to store and retrieve default values for drawing style options, like, e.g., preferred minimum distances between graph elements.

IncrementalHierarchicLayouter provides access to the default NodeLayoutDescriptor and EdgeLayoutDescriptor instances:

NodeLayoutDescriptor NodeLayoutDescriptor { get; set; }

EdgeLayoutDescriptor EdgeLayoutDescriptor { get; set; }

In addition to the instances held directly by IHL, layout descriptors can also be associated with single graph elements in order to specify individual settings for them. Setting individual descriptors for nodes or edges is done through data providers that are bound to the graph. See Related Classes.

IncrementalHierarchicLayouter assigns the nodes of a graph to separate layers using a ILayerer implementation. Layers are ordered and, assuming a top-to-bottom orientation for the main flow, are arranged vertically from top to bottom (see also Figure 10.26, “Layers in the hierarchical layout style”).

The layer order is a 1-based index for the layers that at the same time denotes the so-called rank of all nodes assigned to a layer. Note that the rank of a node is important in conjunction with some of the Layerer implementations.

HierarchicalTopmost

HierarchicalOptimal

HierarchicalTightTree

HierarchicalDownshift

Bfs

FromSketch

UserDefined

In a hierarchical layout, the ordering of the nodes within a layer determines the number of edge crossings in the resulting layout. By default, IHL uses class DefaultLayerSequencer for determining this node order.

The sequencing that DefaultLayerSequencer generates can be conveniently customized using the support for constrained node sequencing.

Incremental layout has two major use cases, which both involve "layout from sketch:"

Both these use cases are illustrated below.

Figure 10.32, “Sequence of incremental layouts” shows a sequence of incremental layouts generated by class IncrementalHierarchicLayouter. Starting with a given graph, new graph elements are inserted optimally into the existing drawing from the step before (which defines the sketch). Note the emphasis for newly added elements.

Figure 10.32. Sequence of incremental layouts

The second major use case for incremental layout, the optimization of distinct parts from an existing hierarchical layout is shown in Figure 10.33, “Incremental layout used for optimization”. There, an entire subgraph is calculated anew and optimally placed into the given drawing that defines the sketch.

Figure 10.33. Incremental layout used for optimization

Both use cases are handled by annotating the "new" graph elements by means of so-called hint objects which are used by the algorithm during layout calculation in incremental mode. The hint object for a graph element that shall be processed using incremental semantics is specified through a data provider that is bound to the graph. The data provider is expected to be registered with the graph using key IncrementalHintsDpKey.

Calculation of incremental hierarchical layouts heavily relies on the services of a so-called "hint factory." A hint factory is responsible for creating hint objects for both nodes and edges. These objects are then used by the incremental layout algorithm to optimally:

When inserting nodes or routing edges according to their hint, nodes and edges from the graph that have no hint object associated retain their original relative order both within layers as well as from layer to layer.

Class IncrementalHierarchicLayouter has a getter method that returns a hint factory object of type IIncrementalHintsFactory. Code that shows the usage of a hint factory is presented in the following example:

// 'graph' is of type yWorks.yFiles.UI.Model.IGraph.

IncrementalHierarchicLayouter ihl = new IncrementalHierarchicLayouter();

// Create an IMapper to store the hints for the incremental layout mechanism.
IMapper<INode, object> hintMap = new DictionaryMapper<INode, object>();

// Get the hint factory from the incremental layout algorithm.
IIncrementalHintsFactory hintsFactory = ihl.CreateIncrementalHintsFactory();

// Get a collection of those nodes that should be processed using incremental
// layout semantics.
ICollection<INode> incrementalNodes = MyGetIncrementalNodes();

// Associate the incremental nodes with hints from the hint factory.
foreach (INode n in incrementalNodes) {
  hintMap[n] = hintsFactory.CreateLayerIncrementallyHint(n);
}

IMapperRegistry mapperRegistry = graph.MapperRegistry;
mapperRegistry.AddMapper(IncrementalHierarchicLayouter.IncrementalHintsDpKey,
                         hintMap);

// Now, set incremental mode and invoke layout calculation.
ihl.LayoutMode = LayoutMode.Incremental;
graph.ApplyLayout(ihl);

The following table lists the data provider look-up keys that are recognized by IHL in conjunction with incremental layout.

Table 10.23. Data provider look-up keys

Key	Element Type	Value Type	Description
IncrementalHintsDpKey	node, edge	object	For each node or edge that shall be added incrementally a hint object that marks the respective graph element to be inserted into the existing hierarchical layout in an optimal manner. The hint object is created by a hint factory, for example the one that is returned by method CreateIncrementalHintsFactory.

Integrated labeling is one of the two scenarios for placing the labels of a graph. It means the support provided by IHL for finding optimal placements for edge labels such that there are no overlaps of edge labels with each other or with graph elements.

Integrated labeling can be enabled or disabled using the following property:

bool IntegratedEdgeLabeling { get; set; }

The before/after pair in Figure 10.37, “Integrated edge labeling” shows the result of a hierarchical layout with integrated edge labeling enabled.

Figure 10.37. Integrated edge labeling

Original graph with edge labels.	Resulting hierarchical layout where the edge labels have been placed optimally.

IncrementalHierarchicLayouter provides support for node label-aware hierarchical layout. Node labels do not need to be placed, but instead their size needs to be considered for the placement, respectively the routing, of adjacent graph elements. Taking node labels into consideration during layout calculation guarantees that they will not overlap nodes in the diagram.

bool ConsiderNodeLabels { get; set; }

See also the description of the NodeLayoutDescriptor class in Related Classes which provides the support for node label handling.

IHL supports both weak port constraints as well as strong port constraints that are specified for the edges of a graph (more precisely, the edge ends). The setup of port constraints is presented in the section called “Port Constraints”.

Using weak port constraints for the ends of an edge, it is possible to specify at which side of the source node or target node, respectively, an edge path must connect. Figure 10.38, “Constraint on which side edges should connect to nodes” shows the resulting hierarchical layout of a graph where some edges are set up having weak port constraints.

Figure 10.38. Constraint on which side edges should connect to nodes

Usual hierarchical layout (i.e. without taking port constraints into account).	Resulting hierarchical layout with weak port constraints.

Using strong port constraints, it is possible to specify the side of the node at which an edge must connect, and additionally also the exact position of the port. Figure 10.39, “Constraint at which exact points edges should connect to nodes” shows the resulting hierarchical layout of a graph where some edges are set up having strong port constraints.

Figure 10.39. Constraint at which exact points edges should connect to nodes

Usual hierarchical layout (i.e. without taking port constraints into account).	Resulting hierarchical layout with strong port constraints.

Carefully observe how the nodes A and B change their position in the resulting hierarchical layout from the figure above. This is due to the strong port constraints specified for the edge ends at the common target node, which would result in an edge crossing with the original node order.

Both weak port constraints and strong port constraints can be mixed easily in the drawing.

The following table lists the data provider look-up keys that are recognized by IHL in conjunction with port constraints.

Table 10.25. Data provider look-up keys

Key	Element Type	Value Type	Description
SourcePortConstraintDpKey	edge	PortConstraint	For each edge a PortConstraint object encoding its source end's port constraint.
TargetPortConstraintDpKey	edge	PortConstraint	For each edge a PortConstraint object encoding its target end's port constraint.

In addition to the support provided for port constraints, IHL also supports the concept of port candidates. Both aspects, i.e., matching port candidates as well as modeling enhanced port constraints are supported.

For the matching of port candidates, the set of allowed anchor locations for edge ends at the nodes of a graph are retrieved from a data provider that is bound to the graph using the look-up key NodeDpKey. The subset of desired anchor locations where the source ports and target ports of edges like to connect to are retrieved from data providers that are bound to the graph using the look-up keys SourcePcListDpKey and TargetPcListDpKey, respectively.

The example in Figure 10.40, “Using port candidates to control connection points” demonstrates the use of port candidates to distribute edges at defined connection points: one port candidate at each corner of the diamond node allows one edge to connect. Additional candidates at the top and bottom allow edges to connect at these points when all other candidates are already occupied. These additional candidates are associated with a higher cost to make sure they will be only used after all other candidates are occupied.

See the section called “Port Candidates” for a detailed description of the port candidates concept.

Figure 10.40. Using port candidates to control connection points

Incoming edges connect at the top, the first outgoing edge at the bottom...	... more outgoing edges occupy the right and left corners...	... when all corners are occupied, the additional edges connect at the bottom.

For modeling enhanced port constraints, the set of possible port candidates for the edges of a graph are retrieved from data providers that are bound to the graph using the look-up keys SourcePcListDpKey and TargetPcListDpKey, respectively.

The following table lists the data provider look-up keys that are recognized by IHL in conjunction with port candidates.

Table 10.26. Data provider look-up keys

Key	Element Type	Value Type	Description
NodeDpKey	node	PortCandidateSet	For each node a PortCandidateSet object encoding the set of allowed anchor locations for edges.
SourcePcListDpKey	edge	ICollection	For each edge an ICollection of PortCandidate objects that encode the subset of desired anchor locations where the source port likes to connect to.
TargetPcListDpKey	edge	ICollection	For each edge an ICollection of PortCandidate objects that encode the subset of desired anchor locations where the target port likes to connect to.

Incremental hierarchical layout supports the notion of grouping together multiple edge ends to be anchored at the same location. This can be specified for both source ends and target ends. The general setup for edge groups is described in the section called “Edge/Port Grouping (Bus-Style Edge Routing)”.

Edges that belong to the same group at a specific end will additionally be routed in bus-style, i.e., if multiple edges start or end at nodes in the same layer and belong to the same group, even if they do not share the same node at their ends, they will be merged together in a bus structure in that layer.

IncrementalHierarchicLayouter supports both automatic and custom edge grouping.

Automatic Edge Grouping

Automatic edge grouping is disabled by default. It can be enabled using the following property:

bool AutomaticEdgeGrouping { get; set; }
Description	Enables/Disables automatic edge grouping

Automatic edge grouping tries to group as many edges as possible, without changing the semantic of the graph. Edges are grouped either at a common source node or at a common target node. They won't be grouped, if grouping would lead to ambiguous paths. The effect of automatic edge grouping is shown in Figure 10.41, “Automatic Edge Grouping”. Note that edges with a common source are grouped as well as edges with a common target. Also note that the outgoing edges at node B are not grouped, because grouping at this node would mock a connection between A and D.

Figure 10.41. Automatic Edge Grouping

Automatic edge grouping disabled.	Automatic edge grouping enabled.

Edges are only grouped at their source (target) node if they do not have a port constraint/port candidates at this node. Furthermore, edges cannot be grouped at a node with specified port candidates. If automatic edge grouping is enabled, user specified edge groups are ignored.

Custom Edge Grouping

If more flexibility is needed, edges can be grouped by specifying edge groups using data providers as described in the section called “Edge/Port Grouping (Bus-Style Edge Routing)”.

The general rule describing how bus structures are created can be summarized as follows: edge paths are merged from both sides, source and target, beginning as close to the respective edge ends as possible. From this rule, the following consequences arise:

• edges that start at a common node and belong to the same source group are merged together such that they are anchored at the same location; the same holds similarly for edges ending at a common node that belong to the same target group
• edges that start at nodes in different layers, but belong to the same source group are merged together in a cascading manner; the same holds similarly for edges ending at nodes in different layers, but belong to the same target group

From this rule it is also clear that edges being grouped at both ends will result in edge routings where the paths are merged to the maximum extent possible.

Table 10.27, “Edge group configurations and resulting bus-style edge routings” presents some edge routing results (in the figures to the left) and describes their actual source and target group setup. Note that the figures to the right depict the edge routing that results when both the edges are reversed and the source and target groups are exchanged.

Table 10.27. Edge group configurations and resulting bus-style edge routings

Figure	Description	Figure
	Edges starting at "A" nodes are grouped at their source side using a common "A" ID (for example). Likewise, edges starting at "B" nodes are grouped at their source side using a common "B" ID. Additionally, at their target side the edges are grouped such that all "A" edges share a common ID and all "B" edges share a common ID.
	Edges starting at the upper nodes are grouped at their target side using a common "A" ID (for example). Likewise, edges starting at the middle nodes are grouped at their target side using a common "B" ID.
	All edges are grouped at their target side using a common ID.
	All edges are grouped at their source side using a common ID. Additionally, at their target side the edges are also grouped such that they share a common ID.
	Edges are grouped at their source side using a common ID.

The following table lists the data provider look-up keys that are recognized by IHL in conjunction with edge/port grouping (bus-style edge routing).

Table 10.28. Data provider look-up keys

Key	Element Type	Value Type	Description
SourceGroupIdDpKey	edge	object	For each edge an arbitrary object indicating the group its source end is affiliated with.
TargetGroupIdDpKey	edge	object	For each edge an arbitrary Object indicating the group its target end is affiliated with.

IncrementalHierarchicLayouter by default supports node halos as soon as they are declared. During layout calculation, it takes any specified additional paddings around nodes into consideration and keeps the areas clear of other graph elements. The labels of a node and its adjacent edge segments are not affected and can still be placed inside or cross the node's halo.

The following table lists the data provider look-up keys that are recognized by IncrementalHierarchicLayouter in conjunction with node halo support.

Table 10.29. Data provider look-up keys

Key	Element Type	Value Type	Description
NodeHaloDpKey	node	NodeHalo	A NodeHalo object that specifies the halo sizes at each side of a node.

IncrementalHierarchicLayouter supports different layer assignment policies for graphs with grouped nodes. The layering for both incremental as well as non-incremental layout can be determined in either of two ways:

Figure 10.42, “Flat vs. recursive layer assignment” compares the layer assignment policies. When layer assignment is done flat, the group nodes of a graph and their adjacent edges are ignored. In particular, this means that the layering of grouped nodes can be influenced by nodes outside of the group node. In constrast, when using recursive layer assignment, grouped nodes are processed without interference from nodes outside of their group node.

Figure 10.42. Flat vs. recursive layer assignment

Flat layer assignment policy where group nodes and their adjacent edges are ignored.	Recursive layer assignment policy.	Recursive layer assignment policy with compaction enabled.

Recursive processing of the grouped nodes is the default behavior. Example 10.25, “Setting up flat layer assignment” shows how to set up flat layer assignment with IncrementalHierarchicLayouter.

// Set up IHL for grouped graphs.
IncrementalHierarchicLayouter ihl = new IncrementalHierarchicLayouter();
ihl.RecursiveGroupLayering = false;

Recursive layer assignment optionally uses a compaction step where empty layers next to group nodes are filled with nodes from layers below these group nodes. When compaction is disabled, an alignment policy is used to specify where "ordinary" nodes that are in a layer with group nodes are placed relative to these group nodes. These options can be configured using the following properties:

bool CompactGroups { get; set; }

GroupAlignmentPolicy GroupAlignmentPolicy { get; set; }

When calculating a layout for a grouped graph, IncrementalHierarchicLayouter also supports minimum size constraints for group nodes. A minimum size constraint can be conveniently used in order for the group node to accommodate for the size of its label. If a data provider is registered with the graph using the look-up key MinimumNodeSizeDpKey, any minimum size constraints for group nodes held by this data provider are respected by default.

IncrementalHierarchicLayouter's support for grouped graphs currently does not include the following features for edge ends that directly connect to group nodes: strong port constraints, strong (fixed) port candidates, and edge/port grouping (bus-style edge routing).

IncrementalHierarchicLayouter's support for incrementally calculating layouts of grouped graphs enables smooth transitions when realizing collapsing and expanding of group nodes. Figure 10.43, “Incremental hierarchical layout when group nodes are collapsed and expanded” presents the results of both these operations. The resulting folder node and group node, respectively, is incrementally inserted into the existing layout.

Figure 10.43. Incremental hierarchical layout when group nodes are collapsed and expanded

Original hierarchical layout with group nodes.	Collapsed group node incrementally inserted into the layout.	Previously collapsed group node expanded and incrementally inserted.

The following table lists the data provider look-up keys that are recognized by IHL in conjunction with grouped graphs.

Table 10.30. Data provider look-up keys

Key	Element Type	Value Type	Description
GroupDpKey	node	bool	For each node a boolean value indicating whether it is a group node or not.
NodeIdDpKey	node	object	For each node an object that serves as a unique ID.
ParentNodeIdDpKey	node	object	For each node an object indicating the group node it belongs to. The object matches the unique ID of a group node that is in the same graph.
MinimumNodeSizeDpKey	node	YDimension	For each group node a YDimension object that specifies the group node's minimum size constraint.

Setup of a grouped graph's hierarchy of nodes (using GroupDpKey, NodeIdDpKey, and ParentNodeIdDpKey) is done transparently by the IGraph-related adapter mechanisms. See also the section called “Setup for Layout” and Chapter 8, Using yFiles for Silverlight Algorithms Functionality.

Class SimplexNodePlacer is the default NodePlacer implementation that is used by IHL during the drawing phase. It can be retrieved via the NodePlacer property.

Most notably, SimplexNodePlacer provides support for symmetric placement of nodes where possible.

bool BaryCenterMode { get; set; }

SimplexNodePlacer also provides an optional post-processing step that tries to remove bends from edges in order to straighten their paths.

bool StraightenEdges { get; set; }

Additionally, it makes available drawing phase options that can be used in conjunction with grouped graphs.

GroupCompactionPolicy GroupCompactionStrategy { get; set; }

The following property can be used to place adjacent edge labels in a compact, stacked style:

bool LabelCompaction { get; set; }