The term "grouped graph" denotes a graph structure where, conceptually, nodes can be declared "children" of a common other node, their "parent." This can be exercised recursively, i.e., parents can be declared children of other parents, resulting in a hierarchy of nodes of possibly arbitrary depth.

The visual presentation of such a hierarchy is normally done by placing the children near each other and have their parent enclosing them. The parent is called a "group node," and the children are its content, they are "grouped nodes." Declaring some nodes to be children of another node is called "grouping."

Layout support for grouped graphs primarily means proper handling of grouped nodes and their enclosing group node. The following table lists the layout algorithms that provide support for group nodes and their content:

Table 5.2. Layout support for grouped graphs

Layout Style	Classname	Note
Hierarchical	IncrementalHierarchicLayouter	IncrementalHierarchicLayouter provides direct support for grouped graphs for both incremental as well as non-incremental layout mode. See the description of IncrementalHierarchicLayouter's advanced concepts for more information.
Organic	SmartOrganicLayouter	See the description of SmartOrganicLayouter's support for layout of grouped graphs for more information.
Orthogonal	OrthogonalGroupLayouter	See the description of orthogonal group layout for more information.

Table 5.3, “Routing support for grouped graphs” lists the routing algorithms that provide support for grouped graphs.

Table 5.3. Routing support for grouped graphs

Routing Style	Classname	Note
Orthogonal	OrthogonalEdgeRouter, ChannelEdgeRouter	OrthogonalEdgeRouter's support for routing with group nodes is partly handled by prepended layout stages. See the description of the orthogonal edge router for more information. ChannelEdgeRouter provides inherent support for routing with group nodes.

Further support for grouped graphs also includes minimum size constraints for group nodes. These are supported by the following layout algorithms: SmartOrganicLayouter and IncrementalHierarchicLayouter.

The two ends of an edge path are also called source port and target port, respectively. A port constraint serves to pinpoint an edge's end at its source node or target node. There are two kinds of port constraints available:

Both kinds of port constraints can easily be combined to express, for example, that an edge's source port should connect to the middle of the source node's upper border.

Table 5.4, “Layout support for port constraints” lists the layout algorithms that provide support for port constraints.

Table 5.4. Layout support for port constraints

Layout Style	Classname	Note
Hierarchical	IncrementalHierarchicLayouter	IncrementalHierarchicLayouter by default obeys weak and strong port constraints as soon as they are set. See the description of the hierarchical layout style for more information.
Tree	GenericTreeLayouter	Nearly all of the predefined node placer implementations that can be used with the generic tree layout algorithm by default obey strong and weak port constraints as soon as they are set. See the description of generic tree layout for more information.

Table 5.5, “Routing support for port constraints” lists the routing algorithms that provide support for port constraints.

Table 5.5. Routing support for port constraints

Routing Style	Classname	Note
Orthogonal	OrthogonalEdgeRouter, ChannelEdgeRouter	Both OrthogonalEdgeRouter and ChannelEdgeRouter by default obey weak and strong port constraints as soon as they are set. See the descriptions of OrthogonalEdgeRouter and ChannelEdgeRouter for more information.

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

// Create a mapper.
IMapper<IEdge, PortConstraint> pcMap =
    new DictionaryMapper<IEdge, PortConstraint>();

// Set the coordinates for the edge's source port. (Actually, this could also
// be done anywhere prior to invoking the layout algorithm.)
graph.SetRelativeLocation(edge3.SourcePort, new PointD(-10, 20));

// Create PortConstraint objects:
// 1) Port constraint that allows an edge end to connect to any side of its
//    respective node.
PortConstraint pc1 = PortConstraint.Create(PortSide.Any);
// 2) Port constraint that determines an edge end to connect *anywhere* to the
//    upper (North) side of its respective node.
PortConstraint pc2 = PortConstraint.Create(PortSide.North);
// 3) Strong port constraint that determines an edge end to connect to the
//    lower (South) side of its respective node. The actual end point is at a
//    fixed coordinate.
PortConstraint pc3 = PortConstraint.Create(PortSide.South, true);

// Establish a mapping from edges to port constraints.
pcMap[edge1] = pc1;
pcMap[edge2] = pc2;
pcMap[edge3] = pc3;

// Add the mapper to the mapper registry of the graph.
// Use the "well-known" look-up key defined in class PortConstraintKeys.
// Note that the above defined port constraints are set so that they apply to
// the source ends of their respective edges only.
graph.MapperRegistry.AddMapper(PortConstraintKeys.SourcePortConstraintDpKey,
                               pcMap);

// Invoke the layouter.
graph.ApplyLayout(new IncrementalHierarchicLayouter());

The concept of port candidates is an extension to that of classic port constraints as described above. Unlike port constraints, port candidates can be used in conjunction with both nodes and edges. When used in conjunction with nodes, port candidates provide a means to:

A typical example for the use of port candidates is a flow diagram as shown in Figure 5.4, “Using port candidates to control connection points”: The diamond shape, which is the visualization of a switch, should have its incoming edge connecting at the top. The first outgoing edge should connect at the bottom (left image), the second at the right, the third at the left (middle image). If there are more outgoing edges, these edges should connect at the bottom as well as more than one incoming edge should connect at the top (right image).

Figure 5.4. 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.

Class PortCandidate enables definition of port candidates that conceptually correspond to either weak port constraints, i.e., effectively describe side constraints, or strong port constraints, which encode specific anchor locations at a node. Note that port candidates that correspond to strong port constraints directly include the coordinates for the actual anchor locations.

PortCandidate additionally allows to associate costs with a given port candidate, which can be used to establish an order of precedence among multiple port candidates. When a given edge port is being assigned to any of the available port candidates at a node, those with low costs are favored compared to other port candidates with higher costs associated.

To define the set of side constraints and anchor locations at a node, multiple port candidates can easily be combined using the services of class PortCandidateSet. When a PortCandidate object is added to an instance of PortCandidateSet, the capacity of the port candidate can optionally be configured. The capacity of a given port candidate (sometimes also referred to as "cardinality") specifies the allowed number of connecting edges at that side or anchor location.

// define a PortCandidateSet
PortCandidateSet pcs = new PortCandidateSet();

// the node has the size (30, 30) with the point (0, 0) at the center
// so the coordinates for the top corner are (0, -15)

// create a candidate at the top corner with direction North and cost 0
PortCandidate candidate =
    PortCandidate.CreateCandidate(0, -15, PortDirection.North, 0);
// add it to the set and allow only one edge to connect to it
candidateSet.Add(candidate, 1);
// do the same for the other three corners
candidateSet.Add(
    PortCandidate.CreateCandidate(0, 15, PortDirection.South, 0), 1);
candidateSet.Add(
    PortCandidate.CreateCandidate(15, 0, PortDirection.East, 0), 1);
candidateSet.Add(
    PortCandidate.CreateCandidate(-15, 0, PortDirection.West, 0), 1);

// to allow more edges to connect at the top and bottom
// create extra candidates and allow Integer.MAX_VALUE edges to connect

// to avoid that these candidates are occupied before the others
// associate a cost of 1 with them
candidateSet.Add(
    PortCandidate.CreateCandidate(0, -15, PortDirection.North, 1),
    int.MaxValue);
candidateSet.Add(
    PortCandidate.CreateCandidate(0, 15, PortDirection.South, 1),
    int.MaxValue);

Table 5.6, “Layout support for port candidates” lists the layout algorithms that provide support for port candidates.

Table 5.6. Layout support for port candidates

Layout Style	Classname	Note
Hierarchical	IncrementalHierarchicLayouter	IncrementalHierarchicalLayouter supports port candidates as soon as they are set. See the description of incremental hierarchical layout for more information.

// 'candidateSet' is of type yWorks.yFiles.Layout.PortCandidateSet
// 'node' is of type yWorks.yFiles.UI.Model.INode and is the node which should
// be associated with the candidate set
// 'graph' is of type yWorks.yFiles.UI.Model.IGraph.

// Create a mapper to associate the candidates with the node.
IMapper<INode, PortCandidateSet> pcMap =
    new DictionaryMapper<INode, PortCandidateSet>();
// Associate the candidate set with the node.
pcMap[node] = candidateSet;

// Add the mapper to the mapper registry of the graph.
graph.MapperRegistry.AddMapper(PortCandidateSet.NodeDpKey, pcMap);

Modeling Enhanced Port Constraints Using Port Candidates

The same scheme of combining PortCandidate objects using Collection objects as used for the matching functionality also enables creating enhanced port constraint definitions for edges. The layouters which support this feature are listed in Table 5.7, “Layout support for enhanced port candidates”.

Table 5.7. Layout support for enhanced port candidates

Layout Style	Classname	Note
Hierarchical	IncrementalHierarchicLayouter	IncrementalHierarchicalLayouter supports port candidates as soon as they are set. See the description of incremental hierarchical layout for more information.

In particular, this scheme is supported by yFiles routing algorithms, and it allows to conveniently specify side constraints comprising two or three sides, for example. Table 5.8, “Routing support for port candidates” lists the routing algorithms that provide support for port candidates modeling enhanced port constraints.

Table 5.8. Routing support for port candidates

Routing Style	Classname	Note
Orthogonal	OrthogonalEdgeRouter, ChannelEdgeRouter	Both OrthogonalEdgeRouter and ChannelEdgeRouter by default support port candidates as soon as they are set. See the descriptions of OrthogonalEdgeRouter and ChannelEdgeRouter for more information.

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

// Define a collection of port candidates for the source ports of all edges.
ICollection<PortCandidate> pcc = new List<PortCandidate>();
// Create port candidates that conceptually correspond to classic side
// constraints (weak constraints) and add them to the collection.
// East side.
pcc.Add(PortCandidate.CreateCandidate(PortDirection.East));
// South side.
pcc.Add(PortCandidate.CreateCandidate(PortDirection.South));

// Create a data provider (adapter) that returns the collection of port
// candidates for each edge.
// Use the "well-known" look-up key defined in class PortCandidate.
graph.MapperRegistry.AddMapper(PortCandidate.SourcePcListDpKey,
                               delegate(IEdge e) { return pcc; });

// Invoke an edge routing algorithm.
graph.ApplyLayout(new OrthogonalEdgeRouter());

Edge grouping means bundling of a set of edges to be treated in a common manner regarding some aspects of edge path generation. Specifically, if edges at a common source node, for example, are declared an edge group at their source ends, then their source ports will be anchored at the same location.

Additionally, all grouped edges will also be routed in bus-style, i.e., their paths will share a common edge segment. If edges at different source (target) nodes are declared an edge group at their source (target) ends, then they will be routed in bus-style only.

Figure 5.5. Edge groups

Hierarchical layout without any edge groups, ...	... with an edge group at the source ends of outgoing edges at node A. The source ports are anchored at the same location. Also, the edges are routed in bus-style, i.e., their paths share a common edge segment.	... with an edge group at the source ends of outgoing edges at node a, b, and c. The edges are routed in bus-style, i.e., their paths share a common edge segment.

Declaring an edge group at either source or target ends of a set of edges is done by associating a common object with the edges via a data provider. Depending on which end the edge group is declared for, an IMapper is added to the mapper registry of the IGraph-based graph using either the SourceGroupIdDpKey or TargetGroupIdDpKey look-up key as the mapper's tag.

Table 5.9, “Layout support for edge groups” lists the layout algorithms that provide support for edge groups.

Table 5.9. Layout support for edge groups

Layout Style	Classname	Note
Hierarchical	IncrementalHierarchicLayouter	IncrementalHierarchicLayouter by default generates edge/port groups as soon as they are declared. See the description of the hierarchical layout style for more information.
Orthogonal	DirectedOrthogonalLayouter	The directed orthogonal layout algorithm by default generates edge/port groups as soon as they are declared. See the description of directed orthogonal layout for more information.

Table 5.10, “Routing support for edge groups” lists the routing algorithms that provide support for edge groups.

Table 5.10. Routing support for edge groups

Routing Style	Classname	Note
Orthogonal	OrthogonalEdgeRouter	Support for edge/port groups is partly handled by prepended layout stages. See the description of the orthogonal edge router for more information.

Setup for Layout

Example 5.9, “Creating an edge group at a common target node (IGraph API)” demonstrates how edge groups are declared, and how an IMapper is added to the mapper registry of the IGraph-based graph using the look-up key TargetGroupIdDpKey as the mapper's tag. During layout calculation, an algorithm first retrieves the data provider using the look-up key, and afterwards retrieves the contained information.

Figure 5.6. Edge group at a common target node

Hierarchical layout without any edge groups...	... and with an edge group at the target ends of the edges. All target ports are anchored at the same location at the common node. Also, the edges are routed in bus-style, i.e., their paths share a common edge segment.

Example 5.9. Creating an edge group at a common target node (IGraph API)

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

// Create a mapper.
IMapper<IEdge, object> egMap = new DictionaryMapper<IEdge, object>();

// Declare an edge group for the target end of all incoming edges at a specific
// node.
string targetEdgeGroupID = "All my grouped edges.";
foreach (IEdge e in graph.InEdgesAt(specificNode)) {
  egMap[e] = targetEdgeGroupID;
}

// Add the mapper to the mapper registry of the graph.
// Use the "well-known" look-up key defined in class PortConstraintKeys as tag.
graph.MapperRegistry.AddMapper(PortConstraintKeys.TargetGroupIdDpKey, egMap);

// Invoke the layouter.
graph.ApplyLayout(new IncrementalHierarchicLayouter());