In the presence of package y.view (i.e., with the yFiles Viewer distribution), the setup for layout calculation of a Graph2D that has associated a HierarchyManager object is a matter of using the convenience methods of class GroupLayoutConfigurator as shown in Example 5.6, “Layout preparation with classes from package y.view”.

// 'graph' is of type y.view.Graph2D. 

GroupLayoutConfigurator glc = new GroupLayoutConfigurator(graph);
// Prepare all relevant information for a layout algorithm. 
glc.prepareAll();

// Invoke buffered layout. 
invokeBufferedLayout(graph, new HierarchicGroupLayouter(), false);

// Restore all group node specific sizes and insets after a layout algorithm 
// has been run. 
glc.restoreAll();

Example 5.7, “Layout preparation without classes from package y.view” demonstrates how to set up a hierarchically organized graph without the convenience functionality from package y.view. Basically, the data providers that hold the necessary information about the graph's hierarchical composition have to be filled manually, and be registered with the graph using the data provider look-up keys defined in interface GroupingKeys.

// 'graph' is of type y.layout.LayoutGraph. 

// Create the node maps that are to be used as data providers later on. 
NodeMap groupKey = graph.createNodeMap();
NodeMap nodeID = graph.createNodeMap();
NodeMap parentNodeID = graph.createNodeMap();

// Register the node maps as data providers with the graph. 
// Use the "well-known" look-up keys defined in interface GroupingKeys. 
graph.addDataProvider(Grouping.GROUP_DPKEY, groupKey);
graph.addDataProvider(Grouping.NODE_ID_DPKEY, nodeID);
graph.addDataProvider(Grouping.PARENT_NODE_ID_DPKEY, parentNodeID);

// Now, set up the hierarchical organization of the graph, i.e., define some 
// of the nodes to be group nodes and others to be their content. 
setupHierarchicalOrganization(graph, groupKey, nodeID, parentNodeID);

// Invoke buffered layout. 
invokeBufferedLayout(graph, new HierarchicGroupLayouter(), false);

The information for the node IDs and the parent node IDs is of symbolic nature that is used in the process of layout calculation to identify the proper parent for a given child, but also to find all children that belong to the same parent. Hence, it is important for the symbolic IDs to properly match between these two data providers, so that the graph's hierarchical composition is correctly expressed.

Example 5.8, “Encoding a graph's hierarchical composition in data providers” demonstrates possible content for the data providers. Here, the nodes themselves are used to denote symbolic IDs for both "ordinary" nodes and group nodes. Carefully observe the usage of the indirection scheme in this example for setting up the parent-child relation.

// Now, set up the hierarchical organization of the graph, i.e., define some 
// of the nodes to be group nodes and others to be their content. 
for (int i = 0; i < 10; i++) {
  // Nodes 1, 5, and 9 are defined to be group nodes. 
  if (i % 4 == 1) {
    groupKey.setBool(n[i], true);
    // Set a symbolic ID for the group node that is used for look-up purposes. 
    nodeID.set(n[i], n[i]);
    continue;
  }

  // Set a symbolic ID for the node that is used for look-up purposes. 
  nodeID.set(n[i], n[i]);

  // Node 2 is defined child of node 1; 
  // node 6 is defined child of node 5. 
  if (i % 4 == 2) {
    // Establish the relation to the parent. 
    parentNodeID.set(n[i], nodeID.get(n[i - 1]));
    continue;
  }

  // Node 3 is defined child of node 1; 
  // node 7 is defined child of node 5. 
  if (i % 4 == 3) {
    // Establish the relation to the parent. 
    parentNodeID.set(n[i], nodeID.get(n[i - 2]));
  }

  // Nodes 0, 4, and 8 remain "ordinary" nodes... 
}

A group node's size is determined by the bounding box that encloses its children and additional insets that are added to each of the box's side. To specify insets individually, a data provider can be used to hold an Insets object for each group node. This data provider is then registered with the graph using the look-up key GROUP_NODE_INSETS_DPKEY defined in interface GroupingKeys.

Example 5.9, “Defining a group node's insets” shows how to add individual Insets objects for group nodes to a node map, and how the node map is registered as a data provider with the graph.

// 'graph' is of type y.layout.LayoutGraph. 

// Create the node map that is to be used as a data provider later on. 
NodeMap groupNodeInsets = graph.createNodeMap();

// Predefine some Insets objects. 
Insets in[] = new Insets[3];
in[0] = new Insets(10, 20, 30, 40);
in[1] = new Insets(20, 20, 20, 20);
in[2] = new Insets(40, 30, 20, 10);

NodeList gnl = getListOfAllGroupNodes(graph);
for (NodeCursor nc = gnl.nodes(); nc.ok(); nc.next()) {
  Node n = nc.node();
  groupNodeInsets.set(n, in[getGroupType(n)]);
}

// Register the node map as a data provider with the graph. 
// Use the "well-known" look-up keys defined in interface GroupingKeys. 
graph.addDataProvider(GroupingKeys.GROUP_NODE_INSETS_DPKEY, groupNodeInsets);

// Invoke buffered layout. 
invokeBufferedLayout(graph, new HierarchicGroupLayouter(), false);

Furthermore, a group node's size can be controlled by registering a custom GroupBoundsCalculator implementation replacing the default InsetsGroupBoundsCalculator instance. To this end, the method from API Excerpt 5.5, “Method to set another GroupBoundsCalculator implementation” is available with classes HierarchicGroupLayouter and OrganicLayouter.

// Getter and setter for custom GroupBoundsCalculator implementation. 
GroupBoundsCalculator getGroupBoundsCalculator()

void setGroupBoundsCalculator(GroupBoundsCalculator groupBoundsCalculator)

Class FixedGroupLayoutStage adds support for the fixed group node policy to both hierarchical layout and orthogonal layout. Example 5.10, “Setup for fixed group node content” shows how the fixed group node policy is realized as a layout stage that is prepended to the actual layout algorithm's invocation.

void invokeBufferedLayout(LayoutGraph graph, Layouter layouter, 
                          boolean orthogonal)
{
  // Create a specialized layout stage that fixes the contents of the group 
  // nodes. 
  FixedGroupLayoutStage fixedGroupLayoutStage = new FixedGroupLayoutStage();
  if (orthogonal)
    fixedGroupLayoutStage.setInterEdgeRoutingStyle(
      FixedGroupLayoutStage.ROUTING_STYLE_ORTHOGONAL);

  // Prepend the stage to the given layout algorithm. 
  layouter.prependStage(fixedGroupLayoutStage);
  
  // Invoke buffered layout for the given layout algorithm. 
  new BufferedLayouter(layouter).doLayout(graph);
  
  // Remove the prepended layout stage. 
  layouter.removeStage(fixedGroupLayoutStage);
}

The tutorial demo application GroupingLayoutWithoutAView.java gives a detailed demonstration on how to set up a hierarchically organized graph without the functionality present in package y.view. Also, the modules that are used to set up the layout algorithms in an application context give deep insights in an algorithm's configuration:

Example 5.11, “Adding source port constraints to some edges” demonstrates the creation of PortConstraint objects, and how they are stored in an edge map. The edge map is then registered as a data provider with the graph using the look-up key SOURCE_PORT_CONSTRAINT_KEY. During layout calculation, an algorithm first retrieves the data provider using the look-up key, and afterwards retrieves the contained information.

The actual coordinates of an edge end point that has a strong port constraint associated are determined at the time a layout algorithm (or a routing algorithm) processes the edge. In other words, the strong characteristic of a strong port constraint is determined by its "normal" coordinates at the time of processing. Note that the specified coordinates of such edge end points are always interpreted relative to the respective node's center.

// 'graph' is of type y.layout.LayoutGraph. 

// Create edge map that is used as a data provider later on. 
EdgeMap pcMap = graph.createEdgeMap();

// Set the coordinates for the edge's source port. (Actually, this could also 
// be done anywhere prior to invoking the layout algorithm.) 
graph.setSourcePointRel(edge3, new YPoint(-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(PortConstraint.ANY_SIDE);
// 2) Port constraint that determines an edge end to connect *anywhere* to the 
//    upper (NORTH) side of its respective node. 
PortConstraint pc2 = PortConstraint.create(PortConstraint.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(PortConstraint.SOUTH, true);

// Establish a mapping from edges to port constraints. 
pcMap.set(edge1, pc1);
pcMap.set(edge2, pc2);
pcMap.set(edge3, pc3);

// Register the edge map as a data provider with the graph. 
// Use the "well-known" look-up key defined in interface PortConstraintKeys. 
// Note that the above defined port constraints are set so that they apply to 
// the source ends of their respective edges only. 
graph.addDataProvider(PortConstraint.SOURCE_PORT_CONSTRAINT_KEY, pcMap);

// Invoke buffered layout. 
invokeBufferedLayout(graph, new HierarchicLayouter());

The tutorial demo application LayoutWithoutAView.java demonstrates how to set up port constraints (both weak and strong) for edge end points without the functionality present in package y.view.

Matching port candidates means the process of distributing a node's edges to the available port candidates. All edges connecting to a node that has a set of port candidates associated with it via a PortCandidateSet object are distributed among the available port candidates with respect to:

For example, when the limit of allowed edges for a given port candidate with costs k is reached, i.e., the given port candidate is said to be "saturated," then the next least expensive port candidate among the remaining ones is chosen to connect edges to.

To influence the matching process, a subset of the PortCandidate objects used for a node can additionally be associated with the respective ports of its connecting edges. The subset then defines a restricted set of desired port candidates an edge prefers to connect to. The PortCandidate objects can be combined using java.util.Collection objects which are stored by means of data providers. The data providers are registered with the graph using the look-up keys SOURCE_PCLIST_DPKEY and TARGET_PCLIST_DPKEY.

Example 5.12, “Creating port candidate sets for nodes” demonstrates how a port candidate set is declared, and how a data provider (adapter) is registered with the graph using the look-up key NODE_DP_KEY. During layout calculation, an algorithm first retrieves the data provider using the look-up key, and afterwards retrieves the contained information.

// 'graph' is of type y.layout.LayoutGraph. 

// Define a port candidate set that is used for all nodes. 
final PortCandidateSet pcs = new PortCandidateSet();
// Create port candidates that conceptually correspond to classic side 
// constraints (weak constraints) and add them to the set. 
// North side: no costs associated; allows two edges to connect. 
pcs.add(PortCandidate.createCandidate(PortConstraint.NORTH), 2);
// East side: costs of 1.0; allows four edges to connect. 
pcs.add(PortCandidate.createCandidate(PortConstraint.EAST, 1.0), 4);
// West side: costs of 2.0, but allows an unlimited number of edges to connect. 
pcs.add(PortCandidate.createCandidate(PortConstraint.WEST, 2.0), 
        Integer.MAX_VALUE);

// Create a data provider (adapter) that returns the port candidate set for 
// each node. 
DataProvider dp = new DataProviderAdapter() {
  public Object get(Object dataHolder) {
    return ((dataHolder instanceof Node) ? pcs : null);
  }
};
// Register the data provider (adapter) with the graph. 
// Use the "well-known" look-up key defined in class PortCandidateSet. 
graph.addDataProvider(PortCandidateSet.NODE_DP_KEY, dp);

// Invoke buffered layout. 
invokeBufferedLayout(graph, new IncrementalHierarchicLayouter());

Example 5.13, “Creating an edge group at a common target node” demonstrates how edge groups are declared, and how an edge map is registered as a data provider with the graph using the look-up key TARGET_GROUPID_KEY. During layout calculation, an algorithm first retrieves the data provider using the look-up key, and afterwards retrieves the contained information.

// 'graph' is of type y.layout.LayoutGraph. 

// Create an edge map that is used as a data provider later on. 
EdgeMap egMap = graph.createEdgeMap();

// Declare an edge group for the target end of all incoming edges at a specific 
// node. 
String targetEdgeGroupID = "All my grouped edges.";
for (EdgeCursor ec = specificNode.inEdges(); ec.ok(); ec.next()) {
  egMap.set(ec.edge(), targetEdgeGroupID);
}

// Register the edge map as a data provider with the graph. 
// Use the "well-known" look-up key defined in interface PortConstraintKeys. 
graph.addDataProvider(PortConstraintKeys.TARGET_GROUPID_KEY, egMap);

// Invoke buffered layout. 
invokeBufferedLayout(graph, new HierarchicLayouter());