Folding

What is Folding?

Folding is the ability to collapse and expand group nodes. Collapsing a group node hides all of its children, while expanding the group node makes them visible again.

Figure 3.11. Folding

Folding
Folding
An Expanded Group Node A Collapsed Group Node

Until now, we've only worked with a single graph. Since we want to be able to change the visual appearance of the graph by collapsing and expanding sections, we need to make a copy of the graph that we can manipulate. We call the single original graph the master graph and we refer to the copy as the folded graph. The copy is a managed view of the master graph.

A folded graph's view state determines whether a node is displayed as collapsed or expanded. It can be manipulated without affecting the master graph. The copy can also be modified, and any structural changes are synchronized with the master graph. Similarly, structural changes to the master graph are synchronized to all of its managed views. Note that a single master graph can have many managed views.

The copies of nodes and other graph items in managed views are called representatives. When working with a graph item instance, it is important to distinguish between a master and its representatives. For example, if you want to remove a node from a managed view, you must use the Remove method with the representative on the corresponding folded graph. Alternatively you could remove the respective master node instance from the master graph. Mapping a master node to its representative and vice versa is explained in the section called “Mapping Representatives to Master Elements”.

Enabling Folding

There are three simple steps for enabling folding: creating the folding manager, creating the managed view, and displaying the folded graph.

Creating the Folding Manager

First, you have to create a folding manager, which handles creating the managed views. An existing graph can be passed into the FoldingManager constructor; if none is passed then a new, empty graph is created.

Example 3.6. Creating the Folding Manager

IGraph graph = GetMyGraph();
FoldingManager foldingManager = new FoldingManager(graph);

Creating the Managed View

Next we need to tell the folding manager to create the managed view using CreateManagedView.

Example 3.7. Creating the Managed View

FoldingManager foldingManager = GetMyFoldingManager();
IFoldedGraph foldedGraph = foldingManager.CreateManagedView();

The IFoldedGraph interface offers a property for accessing the folded graph, as well as methods for collapsing and expanding nodes.

Displaying the Folded Graph

The folded graph's Graph property can be used to display the graph. Simply assign it to your graph control's Graph property:

Example 3.8. Displaying the Folded Graph

IFoldedGraph foldedGraph = GetMyFoldedGraph();

// Obtain the graph for display.
IGraph graph = foldedGraph.Graph;

GraphControl graphControl = GetMyGraphControl();
// Show the folding-enabled graph in a GraphControl.
graphControl.Graph = graph;

Note that the reference to the folded graph does not need to be held but can always be re-obtained from the graph instance via the GetFoldedGraph(IGraph graph) lookup:

Example 3.9. Getting the Folded Graph from the Basic Graph

// Obtain the folded graph via lookup using an extension method on IGraph.
IFoldedGraph foldedGraph = graph.GetFoldedGraph();

Working with Folding

Once folding is enabled, the most common task you will want to perform is to expand and collapse group nodes. Additionally, the following section shows how to map representatives to master elements and how to access the master graph through the folding manager. It also explains the concept of dummy elements and how they affect editing in the collapsed state.

Expanding and Collapsing Group Nodes

The IFoldedGraph interface offers the following methods for collapsing and expanding group nodes:

Table 3.44. Exapnding and Collapsing Group Nodes

Method Description
Collapse collapses the group node
Expand expands the group node

Be sure to call these methods on the representative in the folded graph.

Mapping Representatives to Master Elements

The IFoldedGraph interface also offers the following methods for obtaining the corresponding representatives and master elements:

Table 3.45. Mapping Representatives to Master Elements

Method Description
GetRepresentative<T> Gets the representative for an element of the master graph in the folded graph.
GetMaster<T> Gets the master item for an element of the folded graph.

Accessing the Master Graph

Since we set the GraphControl's graph to show the folded graph, we can't access the master graph through the graph control. Instead, we retrieve the master graph from the folding manager:

Example 3.10. Accessing the Master Graph

IGraph graph = GetMyGraph();

// obtain the folded graph via lookup using an extension method on IGraph.
IFoldedGraph foldedGraph = graph.GetFoldedGraph();
// get the folding manager
FoldingManager foldingManager = foldedGraph.Manager;
// retrieve the master graph from the folding manager
IGraph masterGraph = foldingManager.MasterGraph;

Table 3.46. Accessing the Master Graph

Property Description
MasterGraph the master IGraph instance
MasterGroupedGraph the master IGroupedGraph instance
MasterHierarchy the master IHierarchy(T) instance

Dummy Elements

If you collapse a group node, the collapsed representation is called a dummy node. Additionally, if any edges from outside connect to children of the group node, these edges are replaced by dummy edge representations.

It is possible for dummy elements to be styled differently. By default, their appearance is copied from the original element, but they may have different properties, labels, and ports than the corresponding master elements.

Working with dummy elements is an advanced topic, not covered here. For more information about working with dummy elements, see the section called “Class FoldingManager”.

Editing Collapsed Nodes

If you edit a collapsed node's position, labels, or edges, the changes will only be present on the dummy node in the collapsed state. If the node is expanded again, the state of the corresponding master is reapplied. The same behavior exists for dummy edges. This is so that a collapsed node and its adjacent edges can be visualized differently, e.g. a collapsed node doesn't need the same amount of space in the drawing as in expanded state. The default behavior can be changed through advanced customization (see the section called “Class FoldingManager”).