Chapter 3. Getting Started

Table of Contents

Working with Graphs
Introduction
Nodes
What is a Node?
Creating Nodes
Default Node Properties
Reading Node Properties
Setting Node Properties
Node Labels and Ports
Removing Nodes
Edges
What is an Edge?
Creating Edges
Default Edge Properties
Reading Edge Properties
Setting Edge Properties
Edge Labels
Edge Bends
Removing Edges
Automatic Port Removal
Labels
What is a Label?
Adding Labels to Graph Elements
Label Layout
Positioning Labels
Default Label Properties
Reading Label Properties
Setting Label Properties
Removing Labels
Ports
What is a Port?
Adding Ports to Nodes
Default Port Properties
Reading Port Properties
Setting Port Properties
Removing Ports
Customizing Styles
What is a Style?
Setting Styles
Setting a Default Style
Setting a Style upon Creation
Setting a Style after Creation
Grouping
What is Grouping?
Enabling Grouping on the Graph
Retrieving the Grouped Graph
Building a Grouped Graph
Default Group Node Properties
Changing the Hierarchy
Re-parenting a Child Node
Removing a Group Node
Folding
What is Folding?
Enabling Folding
Creating the Folding Manager
Creating the Managed View
Displaying the Folded Graph
Working with Folding
Expanding and Collapsing Group Nodes
Mapping Representatives to Master Elements
Accessing the Master Graph
Dummy Elements
Editing Collapsed Nodes
Managing the View
Introduction to the View
Fitting the Bounds
Fitting the Viewport
Fitting Both Bounds and Viewport
Basic Interaction
Introduction to Interaction
Using Pre-defined Input Modes
Enabling Interactive Navigation
Enabling Interactive Editing
Undo and Clipboard
Enabling Undo Support
Enabling Clipboard Support
Customizing Undo and Clipboard Operations
Adding New Operation Types
Automatic Graph Layout
What is Layout?
Hierarchic
Organic
Orthogonal
Circular
Tree
Applying a Layout
Calling a Layout on the Graph
Calling a Layout on the Graph Control
Calling a Layout on the Layouter
Basic Input and Output
Basics of Input and Output
Enabling Input and Output for Interaction
Using Input and Output
Customizing Input and Output

Working with Graphs

Introduction

A graph consists of various elements. The most important ones are nodes and edges. Nodes represent entities and are the only element type that can exist independent of other elements. Connections between those entities are called edges. An edge can't exist without the two nodes it connects. Both nodes and edges can have labels which add textual information. Control points of edges that split an edge into multiple segments are called bends. Finally, nodes can have ports that make it possible for edges to connect to nodes.

Nodes

What is a Node?

A node is a graph element that represents an entity. It consists of bounds, a style, and a tag. The node bounds are interpreted as a rectangle parallel to the coordinate axes.

Figure 3.1. Node Bounds

Node Bounds

Table 3.1. Nodes

Property Description
Layout the location and size of the node in the graph.
Style the definition for presenting the node visually.
Tag the tag stores custom data associated with the node.

Creating Nodes

Nodes are created using the factory pattern. Rather than instantiate a node using the new keyword, you ask the graph to create a node for you, using the following method:

CreateNode

If you prefer not to specify bounds and style during node creation, you can use extension methods instead. If you do not specify arguments, the node will use the graph's node defaults.

Table 3.2. Extension Methods for Node Creation

Method Description
CreateNode(IGraph) Creates a node with the default size and style at (0,0). The node's tag is null.
CreateNode(IGraph, PointD location) Creates a node with the default size and style at the given location. The node's tag is null.
CreateNode(IGraph, PointD location, Object tag) Creates a node with the default size and style at the given location. The node's tag is set to the argument value.
CreateNode(IGraph, RectD bounds) Creates a node with the given bounds and the default style. The node's tag is null.
CreateNode(IGraph, RectD bounds, INodeStyle style) Creates a node with the given bounds and style. The node's tag is null.
CreateNode(IGraph, RectD bounds, Object tag) Creates a node with the given bounds and the default style. The node's tag is set to the argument value.

Default Node Properties

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

Here are properties that you can set with NodeDefaults:

Table 3.3. Default Node Properties

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

Note that you cannot specify a default location. If no location is passed at node creation, the node is created at (0,0).

Reading Node Properties

Node properties can be read directly from the node instance:

Table 3.4. Readable Node Properties

Property Description
node. Layout. X The position of the node's top-left corner on the x-axis.
node. Layout. Y The position of the node's top-left corner on the y-axis.
node. Layout. Width The node's width.
node. Layout. Height The node's height.
node. Style The node's style.
node. Tag The node's tag.

To set node properties, use the graph instance as explained in the next section.

Setting Node Properties

The layout and style properties cannot be set directly on the node instance. Instead, the IGraph interface provides the following methods for setting node properties:

Table 3.5. Node-Manipulation Methods

Method Description
SetBounds(INode, RectD) Sets the node's location and size.
SetStyle(INode, INodeStyle) Sets the node's style.

The tag property is the only one that can be set directly on the node.

Table 3.6. Writable Node Property

Property Description
Tag Sets the tag of this node.

Node Labels and Ports

A node can be the owner of labels, which add information to graph elements. Nodes can also have ports, which allow edges to connect to them. Labels and ports must be added after node creation. For an overview of labels and ports, see the section called “Labels” and the section called “Ports”.

Table 3.7. Dealing with Labels

Method/Property Description
AddLabel(ILabeledItem, ILabelModelParameter, ILabelStyle, String, SizeD, Object) Adds a label to a node.
Labels Returns all labels of this node.
Remove(ILabel) Removes the label from the graph.

For convenience, there are also extension methods for creating node labels using the graph's label defaults.

Table 3.8. Label Extension Methods

Method Description
AddLabel(IGraph graph, ILabeledItem item, String text) Adds a label with the given text to a node.
AddLabel(IGraph graph, ILabeledItem item, String text, Object tag) Adds a label with the given text and tag to a node.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, String text) Adds a label to a node using the given label model parameter and text.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text) Adds a label to a node using the given label model parameter, style and text.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text, SizeD preferredSize) Adds a label to a node using the given label model parameter, style, text and preferred size.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style , String text, Object tag) Adds a label to a node using the given label model parameter, style, text and tag.

The graph provides the following methods for adding, accessing and removing ports:

Table 3.9. Dealing with Ports

Method/Property Description
AddPort(IPortOwner portOwner, IPortLocationModelParameter locationModelParameter, IPortStyle style, Object tag) Adds a port to a node.
Ports Returns all ports of this node.
Remove(IPort port) Removes the port from the graph.

For convenience, there are also extension methods for creating node labels using the graph's label defaults.

Table 3.10. Port Extension Methods

Method Description
AddPort(IGraph, IPortOwner owner) Adds a port to the node using the port defaults.
AddPort(IGraph, IPortOwner owner, PointD location) Adds a new port to the node using the given location. The location is interpreted as absolute coordinates.
AddPort(IGraph, IPortOwner owner, IPortLocationModelParameter locationModelParameter) Adds a new port to the node at the port owner using the given location parameter.
AddPort(IGraph, IPortOwner owner, PointD location, IPortStyle style) Adds a port to the node using the absolute coordinates and style.
AddPort(IGraph, IPortOwner owner, IPortLocationModelParameter locationModelParameter, IPortStyle style) Adds a port to the node using the given location parameter and style.

Removing Nodes

Removing a node from the graph also removes its labels and ports, as well as any edges connected to that node. IGraph provides the following methods for removing nodes:

Table 3.11. Methods for Removing Nodes

Method Description
Remove(INode) Removes a single node.
Clear(IGraph) Removes all graph elements, including all nodes.

Edges

What is an Edge?

An edge is a graph element that represents a connection between two entities. It consists of a style and a tag. An edge has a source port and a target port which define the start and end points of the edge path.

Figure 3.2. An Edge

An Edge

Table 3.12. Readable Edge Properties

Property Description
Style the definition for presenting the edge visually.
Tag the tag stores custom data associated with the edge.
SourcePort the port defining the start point of the edge path.
TargetPort the port defining the end point of the edge path.

Creating Edges

Edges are created using the factory pattern. Rather than instantiate an edge using the new keyword, you ask the graph to create an edge for you, using the following method:

CreateEdge(IPort sourcePort, IPort targetPort, IEdgeStyle style, Object tag)

In this method, all edge properties are provided.

The following extension methods help you create edges using the edge defaults:

Table 3.13. Extension Methods for Edge Creation

Method Description
CreateEdge(IGraph, INode sourceNode, INode targetNode) Creates an edge that connects the two given nodes using the default edge style.
CreateEdge(IGraph, IPort sourcePort, IPort targetPort) Creates an edge that connects the two ports using the default edge style.
CreateEdge(IGraph, INode sourceNode, INode targetNode, IEdgeStyle style) Creates an edge that connects the two given nodes using the provided edge style.
CreateEdge(IGraph, IPort sourcePort, IPort targetPort, IEdgeStyle style) Creates an edge that connects the two ports using the provided edge style.

Default Edge Properties

Using the EdgeDefaults property, you can specify a default style to be used for edges created using extension methods.

Here are properties edge defaults that you can set:

Table 3.14. Default Edge Properties

Property Description
Style The default style for edges.
ShareStyleInstance Whether the same style instance should be shared between all edges that use the default style.

Reading Edge Properties

Edge properties can be read directly from the edge instance:

Table 3.15. Readable Edge Properties

Property Description
edge. Style Returns the edge's style.
edge. Tag Returns the data associated with this edge.
edge. Bends Returns all bends of the edge.
edge. Bends. Count Returns the number of bends that belong to this edge.
edge. SourcePort Returns the source port of this edge.
edge. TargetPort Returns the target port of this edge.
edge. SourcePort. Owner Returns the source node of this edge.
edge. TargetPort. Owner Returns the target node of this edge.

To set edge properties, use the IGraph interface as explained in the next section.

Setting Edge Properties

The style as well as the source and target port properties cannot be set directly on the node instance. Instead, the IGraph interface provides the following methods for setting edge properties:

Table 3.16. Edge-Manipulation Methods

Method Description
SetStyle(IEdge, IEdgeStyle) Sets the edge's style.
SetPorts(IEdge, IPort, IPort) Sets the edge's source and target port.

The tag property is the only one that can be set directly on the edge.

Table 3.17. Writable edge property

Property Description
Tag Sets the tag of this edge.

Edge Labels

Additionally an edge can optionally have one or more labels, which add information. Labels must be added after edge creation. For an overview of labels, see the section called “Labels”.

Table 3.18. Dealing with Labels

Method/Property Description
AddLabel(ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text, SizeD preferredSize, Object tag) Adds a label to an edge.
Labels Returns all labels of this edge.
Remove(ILabel label) Removes the label from the edge.

For convenience, there are also extension methods for creating edge labels using the graph's edge label defaults.

Table 3.19. Label Extension Methods

Method Description
AddLabel(IGraph graph, ILabeledItem item, String text) Adds a label with the given text to an edge.
AddLabel(IGraph graph, ILabeledItem item, String text, Object tag) Adds a label with the given text and tag to an edge.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, String text) Adds a label to an edge using the given label model parameter and text.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text) Adds a label to an edge using the given label model parameter, style and text.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text, SizeD preferredSize) Adds a label to an edge using the given label model parameter, style, text and preferred size.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text, Object tag) Adds a label to an edge using the given label model parameter, style, text and tag.

Edge Bends

Edges can optionally have one or more bends. Bends are points that subdivide edges into segments. An edge's path is the sum of all of its segments.

A bend consists of a location and a tag. Every bend has an index in the edge's list of bends that can be obtained from the edge.

Although bends are graph elements, they so not have an own style. Rather, the edge style determines how bends are visualized.

Figure 3.3. An Edge with Bends

An Edge with Bends

Bends must be added after edge creation. There are various methods to modify the bends of an edge.

Table 3.20. Dealing with Bends

Method/Property Description
AddBend(IEdge edge, Int32 index, PointD location) Adds a bend to the edge at the given index and location
AppendBend(IGraph graph, IEdge edge, PointD location) Appends a bend to the list of bends of the edge.
edge. Bends Returns a list containing all bends of the edge.
edge. Bends. Count Returns the number of bends of the edge.
SetLocation(IBend bend, PointD location) Sets the location of the bend to the given location.
Remove(IBend bend) Removes the given bend from its edge.
ClearBends(IGraph graph, IEdge edge) Removes all bends of the given edge.

Removing Edges

Removing an edge from the graph also removes its labels. Removing edges does not otherwise affect connected nodes. On the other hand, if one of the ports of the edge or its respective owner is removed from the graph, the edge is also removed implicitly.

IGraph provides the following methods for removing edges:

Table 3.21. Methods for Removing Edges

Method Description
Remove(IEdge) removes a single edge.
Clear(IGraph) removes all graph elements, including all edges.

Automatic Port Removal

If the property AutoCleanup is set to true in the port defaults, a port is automatically removed when the last edge connected to it is removed. That means that ports can implicitly get removed when removing an edge.

Labels

What is a Label?

A label is a graph element that adds information to a node or an edge. It consists of a label model parameter, which determines the layout, a style, a text, a preferred size and a tag.

Figure 3.4. Labels

Labels

Table 3.22. Label Properties

Property Description
LabelModelParameter a label model parameter that determines the layout of the label.
Layout the location, size, and rotation of the label as determined by the LabelModel
Style the definition for presenting the label visually.
Text The label's text
PreferredSize The preferred size of the label
Tag Custom data associated with the label

Adding Labels to Graph Elements

Labels are created using the factory pattern. Rather than instantiate a label using the new keyword, you ask the graph to add a label to a specific graph element, using the following method:

AddLabel(ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text, SizeD preferredSize, Object tag)

Labels can also be added using the following convenience extension methods. These methods use the label defaults for any optional arguments not provided:

Table 3.23. Extension Methods for Adding Labels

Method Description
AddLabel(IGraph graph, ILabeledItem item, String text) Adds a label with the given text to the node or edge.
AddLabel(IGraph graph, ILabeledItem item, String text, Object tag) Adds a label with the given text and tag to the node or edge.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, String text) Adds a label with the given text to the node or edge using the provided label model parameter.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text) Adds a label with the given text to the node or edge using the provided label model parameter and style.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text, Object tag) Adds a label with the given text and tag to the node or edge using the provided label model parameter and style.
AddLabel(IGraph graph, ILabeledItem item, ILabelModelParameter parameter, ILabelStyle style, String text, SizeD preferredSize) Adds a label with the given text to the node or edge using the provided label model parameter, style and preferred size.

Label Layout

In contrast to nodes, a label's layout does not have to be paraxial. Thus, it must include information about rotation.

A label's layout consists of an anchor point which defines the bottom left corner of the label, an up vector that determines the rotation, and a size.

Figure 3.5. Label layout

Label layout

Table 3.24. Properties of the Label Layout

Property Description
label. Layout Provides access to the layout of a label. The return value is of type IOrientedRectangle
label. Layout. AnchorX Returns the position of the label's bottom left corner on the x-axis.
label. Layout. AnchorY Returns the position of the label's bottom left corner on the y-axis.
label. Layout. UpX Returns the x value of the up vector.
label. Layout. UpY Returns the y value of the up vector.
label. Layout. Width Returns the label's width.
label. Layout. Height Returns the label's height.

Positioning Labels

The layout of a label is not specified with geometric coordinates. Instead, we use label models to dynamically calculate the label's location, size, and rotation, for example relative to the bounds of its owner node or to the ports of its owner edge. The actual position of a label is specified by a label model parameters. Such a parameter encapsulates a certain state which can be interpreted by the label model to calculate the label's layout.

Most label models determine the label position based on the layout or path of the label owner. For example, you can specify whether a node's label should be placed inside or outside of the node bounds.

There are various pre-defined label models available for different scenarios. Typically, a model provides one or more factory methods for creating label model parameters. Some of the models support only a fixed set of parameters. In these cases, the parameters can be accessed using pre-defined constants, for example, North.

Table 3.25. Common Pre-Defined Node Label Models

Label Model Description
InteriorLabelModel Provides nine specific positions inside the node's bounds.
ExteriorLabelModel Provides eight specific positions outside the node's bounds.
InteriorStretchLabelModel Places the label inside the node's bounds and makes the label fit either the node's width or height.
FreeNodeLabelModel The label can be placed at any position and that position can be either a fixed location anywhere in the graph or a location relative to the node's bounds. Optionally, proper interactive positioning is eased by a sophisticated snapping to special positions.

Table 3.26. Common Pre-Defined Edge Label Models

Label Model Description
NinePositionsEdgeLabelModel Provides nine specific label positions near the source, center, and target of the edge.
SmartEdgeLabelModel The most versatile edge label model. The label can be placed at any location and is anchored relative to the edge's segment. Optionally, proper interactive positioning is eased by a sophisticated snapping to special positions.
RotatedSliderEdgeLabelModel Allows placement of labels directly on the edge path or on one side of the edge at a given distance. By default, a set of position candidates along the edge are shown to the user during interactive movements but the model itself supports continuous positions.
RotatedSideSliderEdgeLabelModel Allows placement of labels on both side of the edge at a given distance. By default, a set of position candidates along the edge are shown to the user during interactive movements but the model itself supports continuous positions.
FreeEdgeLabelModel The label can be placed at any location and is anchored relative to the edge's port location. Optionally, proper interactive positioning is eased by a sophisticated snapping to special positions.

Default Label Properties

You can specify property defaults to be used for label creation, if not explicitly specified. Defaults for node labels and edge labels are set separately using the respective defaults property. Defaults for node labels are set using NodeDefaults. Labels; defaults for edge labels are set using EdgeDefaults. Labels.

Example 3.1. Setting Label Defaults

// setting node label defaults
graph.NodeDefaults.Labels.LabelModelParameter = InteriorLabelModel.Center;

// setting edge label defaults
graph.EdgeDefaults.Labels.LabelModelParameter = 
    NinePositionsEdgeLabelModel.SourceAbove;

Table 3.27. Default Label Properties

Property Description
AutoAdjustPreferredSize Gets or sets a property that determines whether to automatically adjust the preferred size of a label.
LabelModelParameter Gets or sets the default label model parameter to use for labels.
ShareLabelModelParameterInstance Gets or sets a value indicating whether the LabelModelParameter instance should be shared referentially or cloned.
ShareStyleInstance Gets or sets a value indicating whether the style instance should be shared referentially or cloned.
Style Gets or sets the default style to use for labels.

Reading Label Properties

Label properties can be read directly from the label instance.

Table 3.28. Readable Label Properties

Property Description
label. LabelModelParameter Returns the label model parameter used to calculate the layout of this label.
label. Layout Provides access to the layout of a label.
label. Layout. AnchorX Returns the position of the label's bottom left corner on the x-axis.
label. Layout. AnchorY Returns the position of the label's bottom left corner on the y-axis.
label. Layout. UpX Returns the x value of the up vector.
label. Layout. UpY Returns the y value of the up vector.
label. Layout. Width Returns the label's width.
label. Layout. Height Returns the label's height.
label. Owner Returns node or edge this label belongs to.
label. PreferredSize Gets the preferred size of the label with respect to its current contents and the implementation of the visualization.
label. Style Returns the label's style.
label. Tag Gets or sets the tag associated with this instance.
label. Text Gets the text string associated with this label.

To set label properties, use the IGraph interface as explained in the next section.

Setting Label Properties

Some properties cannot be set directly on the label instance. Instead, the IGraph interface provides the following methods for setting label properties:

Table 3.29. Label-Manipulation Methods

Method Description
SetLabelModelParameter(ILabel, ILabelModelParameter) Sets the label model parameter for the given label.
SetLabelText(ILabel, String) Sets the label text of the given label.
SetPreferredSize(ILabel, SizeD) Sets the preferred size of the label.
SetStyle(ILabel, ILabelStyle) Sets the style of the label.

The tag property is the only one that can be set directly on the label.

Table 3.30. Writable Label Properties

Property Description
Tag Sets the tag of this label.

Removing Labels

IGraph provides the following methods for removing labels:

Table 3.31. Methods for Removing Label

Method Description
Remove(ILabel) removes a single label
Clear(IGraph) removes all graph elements, including all labels

Ports

What is a Port?

A port is a graph element to which edges can connect. In the current implementation, only nodes host ports. A port consists of a location, a location model parameter, an owner, a style and a tag.

Figure 3.6. Edge with Source and Target Port

Edge with Source and Target Port

Table 3.32. Port Properties

Property Description
Location a point in absolute coordinates
LocationModelParameter used to determine the location.
Owner the graph element that owns the port.
Style the definition for presenting the port visually.
Tag stores custom data associated with the port.

Adding Ports to Nodes

Ports are created using the factory pattern. Rather than instantiate a port using the new keyword, you ask the graph to add a port to a node using the following method:

Table 3.33. Methods for Adding Ports

Method Description
AddPort Adds a port to a node.

Ports can also be added using the following convenience extension methods. These methods use the port defaults for any optional arguments not provided:

Table 3.34. Port Extension Methods

Method Description
AddPort(IGraph, IPortOwner) Adds a port to the node using the default values.
AddPort(IGraph, IPortOwner, PointD) Adds a port to the node using the given location.
AddPort(IGraph, IPortOwner, IPortLocationModelParameter) Adds a port to the node using the given location model parameter.
AddPort(IGraph, IPortOwner, PointD, IPortStyle) Adds a port to the node using the given location and style.
AddPort(IGraph, IPortOwner, IPortLocationModelParameter, IPortStyle) Adds a port to the node using the given location model parameter and style.

Default Port Properties

You can specify default properties to be used for port creation, if not explicitly specified. Defaults for node ports are set using the default node property NodeDefaults. Ports.

Table 3.35. Default Port Properties

Property Description
AutoCleanup If set to true, a port is automatically removed if no edges connect to it.
LocationModelParameter The location model parameter used for calculating the location.
ShareLocationModelParameterInstance Determines whether the same location model parameter instance is shared between ports.
ShareStyleInstance Determines whether the same style instance is shared between ports
Style Gets or sets the default port style.

Reading Port Properties

Port properties can be read directly from the label instance.

Table 3.36. Readable Port Properties

Property Description
port. Location The port's location in absolute coordinates.
port. Location. X The port's location on the x-axis.
port. Location. Y The port's location on the y-axis.
port. LocationModelParameter The port's location model parameter.
port. Owner The port's owner node.
port. Style The port's style.
port. Tag The business data associated with the port.

To set port properties, use the IGraph interface as explained in the next section.

Setting Port Properties

Most properties cannot be set directly on the port instance. Instead, the IGraph interface provides the following methods for setting port properties:

Table 3.37. Port-Manipulation Methods

Method Description
SetLocation(IGraph graph, IPort port, PointD location) Set's the port's location.
SetLocationModelParameter(IPort port, IPortLocationModelParameter parameter) Set's the port's location model parameter.
SetStyle(IPort port, IPortStyle) Set's the port's style.

The tag property is the only one that can be set directly on the port.

Table 3.38. Writable Port Properties

Property Description
Tag Sets the tag of this port.

Removing Ports

Removing a port also removes all edges connected to the port. IGraph provides the following methods for removing ports:

Table 3.39. Methods for Port Removal

Method Description
Remove(IPort) removes a single port
Clear(IGraph) removes all graph elements, including all ports