Grouping

What is Grouping?

Grouping adds hierarchical structure to a graph by allowing you to put together related nodes.

Before grouping can be used, it must be enabled on the graph. After it has been enabled, a grouped graph which handles the graph hierarchy can be obtained from the graph. The hierarchy has a root, which parents all nodes that are not contained in group nodes. This root is not a visible graph element, but a structural element of the hierarchy.

When a set of nodes is being grouped, a new node is created to contain the collected nodes. This group node can then be used to deal with that set of nodes as a unit. For example, moving a group node moves all of its children. Additionally, the minimum size of a group node is constrained to the union of the bounds of its children.

Nodes can be added as children to an arbitrary node, which becomes a group node if it is not already one. Nodes can also be removed from their parent, thus moving up in the hierarchy. Deleting a group node removes the group node but not its children. Instead, the children move one level up in the hierarchy.

Figure 3.10. Grouping

Grouping
Grouping
Ungrouped Nodes Grouped Nodes

The group graph can be configured to have a special style that is applied to newly-created group nodes.

Grouping is a prerequisite for the section called “Folding”

Enabling Grouping on the Graph

The IGraph interface does not provide support for enabling grouping. Instead it can be enabled on DefaultGraph, which you can retrieve using the lookup mechanism, to set its GroupingSupported property to true.

The lookup mechanism is explained in detail in Chapter 7, API Concepts.

Example 3.3. Enabling Grouping on the Graph

IGraph graph = GetMyGraph();
graph.SafeGet<DefaultGraph>().GroupingSupported = true;

Retrieving the Grouped Graph

To create a grouped graph, you have to retrieve the implementation of IGroupedGraph from the graph. This is done using the lookup mechanism:

Example 3.4. Retrieving the Grouped Graph

IGraph graph = GetMyGraph();
graph.Get<IGroupedGraph>();

You can also get the grouped graph using the GetFoldedGraph(IGraph graph) extension method:

Example 3.5. Retrieving the Grouped Graph using the Extension Method

IGraph graph = GetMyGraph();
graph.GetGroupedGraph();

Building a Grouped Graph

Once you have retrieved the grouped graph, you can use its CreateNode method to create nodes as children of other nodes. The parent does not need to be a group node yet.

Table 3.40. Creating Nodes with the Grouped Graph

Method Description
CreateNode(INode parent, RectD bounds, INodeStyle style, Object tag) Creates a new ordinary node as a direct descendant of parent using the given bounds and style.
CreateGroupNode(INode parent, RectD bounds, INodeStyle style, Object tag) Creates a new group node using the provided style and bounds as a child of parent.

You can alternately use the following extension methods:

Table 3.41. Extension Methods for Creating Nodes with the Grouped Graph

Method Description
CreateGroupNode(IGroupedGraph) Creates a new group node using the GroupNodeDefaults.
CreateGroupNode(IGroupedGraph, INode) Creates a new group node using the GroupNodeDefaults as a child of parent.
CreateGroupNode(IGroupedGraph, INode, RectD, INodeStyle) Creates a new group node using the given bounds and style as a child of parent.
CreateNode(IGroupedGraph, INode) Creates a new ordinary node as a direct descendant of parent.
CreateNode(IGroupedGraph, INode, RectD) Creates a new ordinary node using the given bounds as a direct descendant of parent.
CreateNode(IGroupedGraph, INode, RectD, INodeStyle) Creates a new ordinary node using the given bounds and style as a direct descendant of parent.
GroupNodes(IGroupedGraph, INode>) Groups the nodes in children into a newly created group node.
GroupNodes(IGroupedGraph, INode[]) Groups the nodes into a newly created group node.
GroupNodes(IGroupedGraph, INode, INode>) Groups the nodes as children of the provided group node.

Default Group Node Properties

Using the GroupNodeDefaults property, you can specify a default size or style to be used for group node creation, if not explicitly specified.

Here are properties that you can set with GroupNodeDefaults:

Table 3.42. Default Group Node Properties

Property Description
groupedGraph. GroupNodeDefaults. Size The default size for nodes.
groupedGraph. GroupNodeDefaults. Style The default style for nodes.
groupedGraph. GroupNodeDefaults. ShareStyleInstance Whether the same style instance should be shared between all nodes that use the default style.

Changing the Hierarchy

In addition to adding groups, a graph's hierarchy can be changed at any time by re-parenting nodes or removing group nodes.

Re-parenting a Child Node

Using SetParent, a node can be re-parented from one node to another. The children of the re-parented node remain its children.

Table 3.43. Reparenting Nodes

Method Description
SetParent(INode node, INode parent) Sets the parent node for a given node.

Removing a Group Node

A group node can be removed from the graph like any other node (see the section called “Removing Nodes”). Its child nodes are not removed, but move one level up in the hierarchy.