documentationfor yFiles for HTML 3.0.0.2

IGraph

Show usages

Central interface that models a graph which can be displayed in a canvas or GraphComponent.

Inheritance Hierarchy
IGraph
Graph
Implemented Interfaces
ILookup
ITagOwner

Remarks

This interface can be used to query structural information, it also offers methods that change the structure of the graph and its attributes. Furthermore, a number of events will be triggered if the structure of the graph changes.

The graph is made up of collections of nodes and edges. Each node and edge can be associated with a number of labels and possibly ports to which edges connect. An edge connects to two ports and may consist of zero or more bends. The graph is treated as a directed graph, i.e. edges have a sourcePort and a targetPort. It is up to the algorithms and the visualization to possibly treat them as undirected.

This interface also provides support for hierarchically organized, i.e. grouped graphs. This means that nodes together with their connecting edges can be put into other nodes. The containing node is referred to as a "group node." To create and edit group nodes interactively use the GraphEditorInputMode as input mode and enable the grouping operations.

The edgesAt and edgesAt methods can be used to query adjacency information from the graph's structure.

Each element in the graph can be associated with a style that is used for the visualization of the element. Styles can be shared between multiple instances.

To associate data with the elements in the graph, code can make use of the tag property that all IModelItems provide. In order to associate more than one data element with the graph items, compound data objects can be used. Alternatively additional dictionaries can be used to associate arbitrary data sets with the items in this graph.

This interface provides a number of events that can be used to get notified for changes in the graph structure. These events are raised whenever the corresponding state change occurs, e.g. also when loading the graph from a file. If you are only interested in changes that are triggered interactively, you should subscribe to the corresponding events on the IInputMode implementations that implement the user interaction. Especially, you may not modify the graph structure in handlers for these event, e.g. try to prevent or undo the change that has raised the event.

Examples

New elements can be created either using defaults or with explicitly provided styles:

Creating graph elements
const graph = graphComponent.graph

// set defaults for newly created elements

// appearance of nodes
graph.nodeDefaults.style = new ShapeNodeStyle({
  shape: ShapeNodeShape.RECTANGLE,
  fill: Color.ORANGE,
})
// placement and appearance of node labels
graph.nodeDefaults.labels.layoutParameter = InteriorNodeLabelModel.CENTER
graph.nodeDefaults.labels.style = new LabelStyle({
  backgroundStroke: Stroke.BLACK,
  backgroundFill: Color.WHITE,
})

// create some nodes and edges
const node1 = graph.createNode()
const node2 = graph.createNode(
  new Rect(100, 0, 60, 40),
  new GroupNodeStyle(),
  'some tag',
)
const edge1 = graph.createEdge(
  node1,
  node2,
  new PolylineEdgeStyle({ targetArrow: new Arrow(ArrowType.STEALTH) }),
)

Existing elements can be changed using methods provided by IGraph:

Changing the graph
let index = 0
for (const node of graph.nodes) {
  if (node.labels.size === 0) {
    // if the node has no label, yet, add one
    graph.addLabel(node, `New label for node ${index}`)
  } else {
    // otherwise change the first label's text
    graph.setLabelText(
      node.labels.get(0),
      `Change text for node ${index}`,
    )
  }
  // set another style for the node
  graph.setStyle(
    node,
    new ShapeNodeStyle({
      shape: ShapeNodeShape.RECTANGLE,
      fill: Color.GREEN,
    }),
  )
  index++
}

The graph can be traversed along the edges with the help of a number of methods which provide adjacency information from the graph's structure.

Analyzing the graph structure
for (const node of graph.nodes) {
  const nodeName = node.labels.get(0).text
  // no predecessors: the node is a root
  if (!graph.predecessors(node).some()) {
    console.log(`Node ${nodeName} is a root.`)
  }
  // no successor: the node is a leaf
  if (!graph.successors(node).some()) {
    console.log(`Node ${nodeName} is a leaf.`)
  }
  // list all nodes which are linked to the current node
  for (const edge of graph.edgesAt(node)) {
    const otherNode = edge.opposite(node) as INode
    console.log(
      `Node ${nodeName} is linked to ${otherNode.labels.get(0).text}.`,
    )
  }
}

Finally, graph items can also be removed.

Removing graph elements and clearing the graph
// IMPORTANT: graph.nodes will throw exception if it is changed during iteration
// therefore we have to iterate over a copy of the node collection
// while we remove the nodes
const nodesToRemove = graph.nodes.toList()
for (const node of nodesToRemove) {
  graph.remove(node)
}

// clear the existing graph
graph.clear()

IGraph also provides support for hierarchically organized, i.e. grouped graphs. This means that nodes together with their connecting edges can be put into other nodes.

Grouping features overview
const graph = graphComponent.graph

// set the defaults for a newly created group node
graph.groupNodeDefaults.style = new ShapeNodeStyle({
  shape: ShapeNodeShape.ROUND_RECTANGLE,
  stroke: Stroke.AQUAMARINE,
  fill: null,
})
// create a group node
const groupNode = graph.createGroupNode()
// add existing nodes as children

graph.groupNodes(groupNode, [node1, node2, node3])

// whether the node is a group node
console.log(graph.isGroupNode(groupNode)) // true
console.log(graph.isGroupNode(node1)) // false

// get the parent of a node
console.log(graph.getParent(node1)) // groupNode
console.log(graph.getParent(groupNode)) // null

// get the children of a group node
const children = graph.getChildren(groupNode) // node1, node2, node3
console.log(children.size) // 3

Related Reading in the Developer's Guide

The graph model with all relevant types and their relationships is presented in detail in the section The Graph Model.

More information on visual styles can be found in the section Visualization of Graph Elements.

Type Details

yFiles module
view

See Also

Graph, INode, IEdge, IPort, ILabel, IBend, Creating Graph Elements, Automatic Graph Layout, The Graph Model, IGraph, Ports, Finding Adjacent Nodes and Edges, Automatic Layouts, Applying an Automatic Layout, Generic Labeling, Creating And Updating Graphs, Undo and Redo, Customizing Automatic Layout, Examples for Lookup Decoration, WebGL Styles, Migrating WebGL2 Styles, Changes to the Layout Graph Model, Accessing Graph Elements, Copying the Graph, Labels in Custom Layouts

Properties

Methods

Events