In addition to the functionality presented in the section called “Creating Graphs and Graph Elements”, which covers simple graph element creation, class Graph also provides methods that offer more control in specific situations.

For example, in addition to the most frequently used simple edge creation, it is also possible to specify the exact place where a newly created edge should be inserted into both the sequence of outgoing edges at its source node and the sequence of incoming edges at its target node. Furthermore, an already existing edge can be completely remodeled, i.e., both its end nodes as well as the insertion places at either end node can be changed. Reversing an edge, as another variant of changing an edge, is also supported.

Example 7.1, “Exact edge insertion” shows the respective line of code for specifying the exact place of edge insertion.

// 'graph' is of type com.yworks.yfiles.base.Graph.
// 'source' and 'target' are of type com.yworks.yfiles.base.Node.

// Create a new edge at the second position of all incoming edges at the target
// node.
graph.createEdgeAt(source, source.firstOutEdge(), target, target.firstInEdge(),
                   Graph.AFTER, Graph.AFTER);

Figure 7.2, “Exact edge insertion” shows the resulting graph. The newly created edge is inserted after the first incoming edge at the target node. Observe how the sequence of incoming edges (indicated by the numbers near the arrowheads) changes with the insertion.

Figure 7.2. Exact edge insertion

(a) Graph before...	(b) ... and after edge insertion.

The analogous operation to graph element creation is their removal. Class Graph offers methods to remove all graph elements at once, or to remove only a single node or a single edge. When removing either an instance of type Node or an instance of type Edge their reference to the containing graph is cleared.

// 'graph' is of type com.yworks.yfiles.base.Graph.

// Remove single graph elements from the graph.
// Note that all edges adjacent to the given node are removed prior to the node
// itself.
graph.removeNode(graph.firstNode());
graph.removeEdge(graph.lastEdge());

// Remove all graph elements from the graph at once.
graph.clear();

An alternative to removing graph elements is to hide them. Hiding is a technique to only temporarily remove graph elements, i.e., taking them away from the graph structure to perform some task on the remaining graph, and thereafter putting them back into again, unhiding them. Note that both removing and hiding a graph element only takes them away from the graph, the objects themselves still exist.

// 'graph' is of type com.yworks.yfiles.base.Graph.

// Hide single graph elements from the graph.
// Note that all edges adjacent to 'exampleNode' are hidden prior to the node
// itself.
var exampleNode:Node = graph.firstNode();
graph.hide(exampleNode);

// Unhide single graph elements from the graph.
// Note that *only* 'exampleNode' is unhidden, while its formerly adjacent edges
// are not.
graph.unhide(exampleNode);

In order to be able to unhide previously hidden graph elements, it is necessary to retain them, for example, in a data structure. Hiding of graph elements can also be performed utilizing specialized classes which automatically keep track of all hidden elements. These classes are described in the section called “Advanced Topics”.

In addition to the number of nodes and the number of edges an instance of type Graph also knows whether a single graph element belongs to it or if there is an edge connecting two nodes. The latter feature is especially useful if there is no reference of an edge at hand, for instance.

If a graph element has been hidden it does not belong to any graph until it is unhidden again.

// 'graph' is of type com.yworks.yfiles.base.Graph

// Get the number of nodes in the graph.
// (Both methods are equivalent.)
var nodeCount:int = graph.nodeCount();
var N:int = graph.N();

// Get the number of edges in the graph.
// (Both methods are equivalent.)
var edgeCount:int = graph.edgeCount();
var E:int = graph.E();

// Check if the graph is empty.
var isEmpty:Boolean = graph.empty;

// Check if the first node belongs to the graph.
var containsNode:Boolean = graph.containsNode(graph.firstNode());

// Check if there is an edge between first and last node of the graph.
var containsEdge:Boolean = graph.containsEdgeBetweenNodes(graph.firstNode(),
                                                          graph.lastNode());

Class Graph offers access to its graph elements in several different ways. It returns either cursors to iterate over the respective sets of graph elements, or creates arrays containing references to all nodes or all edges from the graph. As an additional convenience, there are methods to get the first, respectively last element of any of the two sets. While the returned cursors by definition have read-only behavior on the underlying container, the returned arrays actually are copies of the respective sets of elements from the graph at a certain point in time. In effect, this means that, for example, a returned node array can be modified in any way, i.e., nodes might be removed from the array or the sequence of nodes might be changed, without affecting the node set from the graph.

To change the sequence of any of the graph element sets class Graph has methods to move an element to the first or last position, respectively.

// 'graph' is of type com.yworks.yfiles.base.Graph.

// Get the first and last node of the node set from the graph.
var firstNode:Node = graph.firstNode();
var lastNode:Node = graph.lastNode();

// Exchange first and last node of the node set.
graph.moveNodeToLast(firstNode);
graph.moveNodeToFirst(lastNode);

// Get the first and last edge of the edge set from the graph.
var firstEdge:Edge = graph.firstEdge();
var lastEdge:Edge = graph.lastEdge();

// Exchange first and last edge of the edge set.
graph.moveEdgeToLast(firstEdge);
graph.moveEdgeToFirst(lastEdge);

// Get a cursor of all nodes from the graph.
var nc:NodeCursor = graph.nodes();

// Get a cursor of all edges from the graph.
var ec:EdgeCursor = graph.edges();

// Get an array of all nodes from the graph.
var nodes:Vector.<Object> = graph.getNodeArray();

// Get an array of all edges from the graph.
var edges:Vector.<Object> = graph.getEdgeArray();

Every instance of a graph element, i.e., every instance of type Node and type Edge holds a reference to the instance of type Graph it belongs to. This reference is cleared when the graph element has been removed or hidden from its graph.

// 'node' is of type com.yworks.yfiles.Node.

// Get the graph the node belongs to.
var graph:Graph = node.graph;

Furthermore, every graph element knows the position it has in the respective set of elements within its graph. More precisely, when an instance of type Graph is asked for an array of its nodes, for example, this array reflects the node iteration sequence exactly, i.e., a node at position 6 in the array will return the value 6 when asked for its position.

// 'graph' is of type com.yworks.yfiles.Graph.
// 'node' is of type com.yworks.yfiles.Node.

// Get the node's position.
var index:int = node.index();

// Get an array of all nodes from the graph.
var nodes:Vector.<Object> = graph.getNodeArray();
// Check the positions of all nodes.
for (var i:int = 0; i < graph.N(); i++) {
  if (Node(nodes[i]).index() != i) {
    throw new Error("Mismatch at position " + i + ".");
  }
  else {
    trace("All is well at position " + i + ".");
  }
}

// 'node' is of type com.yworks.yfiles.Node.

// Get the number of edges at a node.
var degree:int = node.degree();

// Get the number of incoming edges at a node.
var inDegree:int = node.inDegree();

// Get the number of outgoing edges at a node.
var outDegree:int = node.outDegree();

// 'graph' is of type com.yworks.yfiles.Graph.

var firstNode:Node = graph.firstNode();
var lastNode:Node = graph.lastNode();

// Check whether there is an edge between first and last node of the graph.
// First check if there is a connecting edge outgoing to 'lastNode'.
var e:Edge = firstNode.getEdgeTo(lastNode);
// If not, then check if there is a connecting edge incoming from 'lastNode'.
if (e == null) {
  e = firstNode.getEdgeFrom(lastNode);
}

// 'node' is of type com.yworks.yfiles.base.Node.

// Get a cursor to iterate over all edges at a node.
var edges:EdgeCursor = node.edges();

// Get a cursor to iterate over all incoming edges at a node.
var inEdges:EdgeCursor = node.inEdges();

// Get a cursor to iterate over all outgoing edges at a node.
var outEdges:EdgeCursor = node.outEdges();

// 'node' is of type com.yworks.yfiles.base.Node.

// Get a cursor to iterate over all neighbor nodes.
var neighbors:NodeCursor = node.neighbors();

// Get a cursor to iterate over the source nodes of all incoming edges.
// These nodes are called predecessors.
var predecessors:NodeCursor = node.predecessors();

// Get a cursor to iterate over the target nodes of all outgoing edges.
// These nodes are called successors.
var successors:NodeCursor = node.successors();

// 'edge' is of type com.yworks.yfiles.base.Edge.

// Get the two end nodes of an edge.
var source:Node = edge.source();
var target:Node = edge.target();

// Getting the opposite when holding one of either source or target node.
var opposite:Node = edge.opposite(source);

// 'edge' is of type com.yworks.yfiles.base.Edge.

// Ask the edge whether it is a self-loop.
var isSelfLoop:Boolean = edge.selfLoop;

Table 7.1, “Time complexities in package com.yworks.yfiles.base” shows time complexities for several of the most frequent tasks when working with the yFiles graph structure implementation.

Creation of graph elements takes constant time as does the removal of an edge. Removing a node, though, implies the removal of all its connecting edges first, so this task takes linear time, i.e., time proportional to the number of connecting edges. Also, all iteration is done in linear time. Checking whether a given node or edge belong to a graph is done in constant time, while testing if there is an edge connecting two nodes takes linear time.