Using yFiles Layout Functionality

Layout Infrastructure

All graph layout algorithms in the yFiles FLEX Client Layout Extension library component implement interface Layouter. This interface declares methods for testing if a given input graph of type LayoutGraph can be handled, and also for actually assigning a layout to such a graph.

The calculated new layout information that results from a Layouter invocation supersedes that of the given LayoutGraph object. Figure 5.1, “Layouter dependencies” shows the dependencies for interface Layouter.

Figure 5.1. Layouter dependencies

Layouter dependencies.

IGraph-related Adapter Mechanisms

Internally, the layout algorithms in the yFiles FLEX Client Layout Extension library component are tailored to the LayoutGraph API. By means of the adapter mechanisms presented in Chapter 3, Using yFiles FLEX Client Layout Extension Functionality, however, the layout algorithms can be used with an IGraph-based graph structure without much effort as well.

Invoking a layout algorithm can be as simple as this one-liner:

Example 5.1. Layout invocation for an IGraph-based graph using adapter mechanisms

// 'graph' is of type com.yworks.graph.model.IGraph.

CopiedLayoutIGraph.applyLayout(graph, new IncrementalHierarchicLayouter());

The following detailed example shows the invocation of a layout algorithm with additional setup prior to calling the algorithm. A dedicated data structure (to hold supplemental data for the layout algorithm) is created, filled, and then registered with the graph.

Example 5.2. Creating edge groupings at a common target node

// 'graph' is of type com.yworks.graph.model.IGraph.

// Create a mapper.
var egMap:IMapper = new DictionaryMapper();

// Declare an edge group for the target end of all incoming edges at a specific
// node.
var targetEdgeGroupID:String = "All my grouped edges.";
for each(var e:IEdge in graph.edgesAtPortOwner(specificNode)) {
  if (e.targetPort.owner == specificNode) {
    egMap.mapValue(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.TARGET_GROUPID_KEY, egMap);

// Invoke the layouter.
CopiedLayoutIGraph.applyLayout(graph, new IncrementalHierarchicLayouter());

Nearly all use cases for automatically calculating a layout are conveniently supported using an IGraph-based graph in conjunction with the adapter mechanisms:

  • invoking a layout algorithm
  • layout morphing
  • associating supplemental data to be used by a layout algorithm

Resorting to the layout graph structure should only be necessary for advanced customizations of a layout process, like, e.g., creating a custom layout stage, or (even more advanced) creating a custom Layerer implementation.

Compared to using the LayoutGraph API, the main differences in the setup with an IGraph-based graph and adapter mechanisms are as follows:

  • No need to use DataProvider (NodeMap/EdgeMap): associating supplemental data for graph elements can be conveniently achieved using IMapper instances. IMappers that are in the mapper registry of the IGraph are automatically converted to corresponding DataProviders, which can be accessed by a layout algorithm.
  • Layout invocation: most conveniently, a layout algorithm can be run using CopiedLayoutIGraph's applyLayout method.