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.
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”.
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.
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.
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:
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.
The IFoldedGraph interface offers the following methods for collapsing and expanding group nodes:
Table 3.44. Exapnding and Collapsing Group Nodes
|Collapse||collapses the group node|
|Expand||expands the group node|
Be sure to call these methods on the representative in the folded graph.
The IFoldedGraph interface also offers the following methods for obtaining the corresponding representatives and master elements:
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;
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”.
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”).
Copyright ©2004-2015, yWorks GmbH. All rights reserved.