Chapter 13. Underlying Graph Model of the yFiles Layout Algorithms

Table of Contents

Layout Architecture
Graph Structure Enhancements
Positional and Dimensional Information
Advanced Topics
Copying a LayoutGraph
Invoking a Layout Algorithm Using Buffered Layout
Class BufferedLayouter
Working with the Layout Graph Structure
Grouped Graph Setup for Layout

This chapter presents the layout graph structure, i.e., the underlying graph model that the layout algorithms are tailored to. This graph structure implementation is an enhancement of the basic algorithms graph structure, and is also referred to as the "LayoutGraph API" in Chapter 10, Automatic Graph Layout.

Important

This chapter can be easily skipped when using the IGraph API, the graph structure implementation of yFiles for Silverlight Viewer. See also the section called “Using yFiles Layout Functionality” and Chapter 8, Using yFiles for Silverlight Algorithms Functionality.

Layout Architecture

To enable automatic graph layout, the basic graph structure is enriched with information for two-dimensional placement of its elements. Furthermore, the basis for layout algorithms to access this information is laid, too.

Graph Structure Enhancements

The graph implementation in namespace yWorks.yFiles.Layout is provided by abstract class LayoutGraph. It enhances the graph structure with support for positional and dimensional information for all graph elements.

In particular, this means width and height for a node and also coordinates for its upper left corner. For edges, more precisely edge paths, positional information means coordinates for both starting point and end point, as well as the control points in-between these two.

Both positional and dimensional information are indispensible for calculating the layout for a graph. Accordingly, these two are also called the "layout information" for a graph and its elements. Figure 13.1, “Graph structure classes” depicts the hierarchy of the yFiles graph structure classes as present in the yWorks.yFiles.Layout namespace.

Figure 13.1. Graph structure classes

Graph structure classes.

Positional and Dimensional Information

Abstract class LayoutGraph implements interface IGraphLayout, which defines the basis for layout information on graph elements. Class DefaultLayoutGraph, the default implementation for LayoutGraph, presents the main graph class in the yWorks.yFiles.Layout namespace that can be used for all graph layout tasks.

Figure 13.2, “Class hierarchy for class DefaultLayoutGraph” shows the class hierarchy for class DefaultLayoutGraph.

Figure 13.2. Class hierarchy for class DefaultLayoutGraph

Class hierarchy for class DefaultLayoutGraph.

The following method from abstract class LayoutGraph returns graph-level layout information:

Rectangle GetBoundingBox()
Description Getter method for the graph's dimension.

Interface INodeLayout and its default implementation, class DefaultNodeLayout, are used to add the layout information to a node. This information consists of the coordinates for the upper left corner of the node, and its width and height. Figure 13.3, “INodeLayout” shows the class hierarchy for interface NodeLayout.

Figure 13.3. INodeLayout

INodeLayout.

The following convenience methods defined by abstract class LayoutGraph can be used to control the layout information for nodes:

Interface IEdgeLayout and its default implementation, class DefaultEdgeLayout, are used to add the layout information to an edge. This information consists of the coordinates for both starting point and end point of the edge path, as well as the coordinates for the control points in-between these two. Figure 13.4, “IEdgeLayout” shows the class hierarchy for interface IEdgeLayout.

Important

The coordinates for the edge's end points are relative to the center coordinates of the edge's source node and target node, respectively. The coordinates for the control points, in contrast, are absolute.

Figure 13.4. IEdgeLayout

IEdgeLayout.

The following convenience methods defined by abstract class LayoutGraph can be used to control the layout information for edges. Note that the path list for an edge includes its source port, all control points, and also its target port. The point list, though, holds only the edge's control points.

Note

Control points are also known as "bends."

Advanced Topics

Copying a LayoutGraph

The generic mechanism for copying a graph structure as described in the section called “Copying a Graph” can also be used to copy implementations of abstract class LayoutGraph. Instead of a GraphCopyFactory instance, however, other copy factory implementations, which are capable of copying the information associated with the elements of a LayoutGraph, need to be used. Specifically, this means that node layout and edge layout data as well as node labels and edge labels need to be handled properly by such implementations.

Classes LayoutGraphCopyFactory and HierarchicGraphCopyFactory are predefined copy factories that handle both layout data as well as labels. The latter class is returned when calling the GetGraphCopyFactory method on a DefaultLayoutGraph, the default LayoutGraph implementation. It is a hierarchy-aware graph copy factory that wraps a LayoutGraphCopyFactory instance and in addition to the services provided by its delegate also automatically copies the contents of all GroupingKeys data providers registered with the LayoutGraph.

Example 13.1, “Creating a GraphCopier for a "flat" LayoutGraph” shows how to create a GraphCopier that uses the graph copy factory for "flat" graphs instead of the default hierarchy-aware one.

Example 13.1. Creating a GraphCopier for a "flat" LayoutGraph

// 'graph' is of type yWorks.yFiles.Layout.DefaultLayoutGraph.

// Create a new GraphCopier that uses a graph copy factory for "flat" graphs.
GraphCopier gc = new GraphCopier(new LayoutGraphCopyFactory());