Canvas

The Canvas API provides a set of methods and properties for managing graph visualization.

Canvas uses a fluent interface, allowing methods to be chained for concise configuration. For example:

    
const element = document.getElementById('canvas');

const canvas = new CanvasBuilder(element).build();

canvas
  .addNode({ x: 100, y: 100, element: document.createElement('div') })
  .addNode({ x: 200, y: 200, element: document.createElement('div') })
  .addNode({ x: 300, y: 300, element: document.createElement('div') })
  .patchViewportMatrix({ x: -100, y: -100 });

  

Below is a list of all available methods

Add Node

Adds a node to the canvas with customizable properties.

    
canvas.addNode({
  id: "node-1",
  x: 100,
  y: 100,
  element: document.createElement('div'),
});

  

For convenience, static ports can be defined directly during node creation.

    
const node = document.createElement('div');
const port = document.createElement('div');
node.appendChild(port);

canvas.addNode({
  id: "node-1",
  element: node,
  x: 100,
  y: 100,
  ports: [
    {
      id: "port-1",
      element: port,
    },
  ],
});

  

All available parameters are demonstrated in the following example:

    
const node = document.createElement('div');
const port = document.createElement('div');
node.appendChild(port);

canvas.addNode({
  id: "node-1",
  element: node,
  x: 100,
  y: 100,
  ports: [
    {
      id: "port-1",
      element: port,
      direction: 0,
    },
  ],
  centerFn: (w, h) => ({ x: w / 2, y: h / 2 }),
  priority: 1,
});

  

Parameters

Update Node

Updates specified properties of a node.

    
canvas.updateNode("node-1", {
  x: 100,
  y: 100,
});

  

All available parameters are demonstrated in the following example:

    
canvas.updateNode("node-1", {
  x: 100,
  y: 100,
  priority: 10,
  centerFn: () => ({ x: 0, y: 0 }),
});

  

When called without parameters, the coordinates of all edges connected to the node will be updated.

    
canvas.updateNode("node-1");

  

Parameters for updateNode:

Remove Node

Removes a specified node from the canvas. All associated ports will be unmarked, and any edges connected to the node will also be removed.

    
canvas.removeNode("node-1");

  

Parameters for removeNode:

Mark Port

Marks an element as a port for a specific node.

    
const portElement = document.createElement('div');

nodeElement.appendChild(portElement);

canvas.markPort({
  nodeId: "node-1",
  element: portElement,
});

  

All available parameters are demonstrated in the following example:

    
canvas.markPort({
  id: "port-1",
  nodeId: "node-1",
  element: portElement,
  direction: -Math.PI,
});

  

Parameters for markPort:

Static ports can also be defined directly within the addNode method.

Update Port

Updates specified properties of a port.

    
canvas.updatePort("port-1", {
  direction: -Math.PI,
});

  

When called without parameters, the coordinates of all edges connected to the port will be updated.

    
canvas.updatePort("port-1");

  

Parameters for updatePort:

Unmark Port

Unmarks a specified port, removing relation to the node. All edges connected to the port will also be removed.

    
canvas.unmarkPort("port-1");

  

Parameters for unmarkPort:

Add Edge

Adds an edge between two ports on the canvas.

    
canvas.addEdge({
  id: "edge-1",
  from: "port-1",
  to: "port-2",
});

  

All available parameters are demonstrated in the following example:

    
import { BezierEdgeShape } from "@html-graph/html-graph";

canvas.addEdge({
  id: "edge-1",
  from: "port-1",
  to: "port-2",
  shape: new BezierEdgeShape(),
  priority: 5,
});

  

Parameters:

Update Edge

Updates specified properties of an edge.

    
canvas.updateEdge("edge-1", {
  from: "port-3",
  to: "port-4",
});

  

All available parameters are demonstrated in the following example:

    
canvas.updateEdge("edge-1", {
  from: "port-3",
  to: "port-4",
  shape: new HorizontalEdgeShape(),
  priority: 10,
});

  

When called without parameters, the edge’s coordinates will be recalculated.

    
canvas.updateEdge("edge-1");

  

Parameters for updateEdge:

Remove Edge

Removes a specified edge from the canvas.

    
canvas.removeEdge("edge-1");

  

Parameters for removeEdge:

Clear

Removes all nodes and edges from the canvas, allowing it to be reused.

    
canvas.clear();

  

Destroy

Destroys the canvas. The provided HTML element gets rolled back to its initial state. Once this method is called, the canvas cannot be reused.

    
canvas.destroy();

  

Patch Viewport Matrix

The viewport transformation matrix consists of three values: scale, x, and y.

• Scale: Represents the current scaling factor of the viewport. A larger scale zooms out, making the content appear smaller, while a smaller scale zooms in, making the content appear larger.
• X: The horizontal distance from the absolute zero point to the top-left corner of the viewport.
• Y: The vertical distance from the absolute zero point to the top-left corner of the viewport.

To better understand how these values work, experiment with the demo below.

To update the viewport matrix values, use the patchViewportMatrix method. All parameters are optional.

    
canvas.patchViewportMatrix({
  scale: 0.5,
  x: -50,
  y: -50,
});

  

This matrix is the inverse of the content matrix.

Patch Content Matrix

The content transformation matrix consists of three values: scale, x, and y.

• Scale: Represents the current scaling factor of the content. A larger scale makes the content appear bigger, while a smaller scale zooms out, making the content appear smaller.
• X: The horizontal distance from the top-left corner of the viewport to the absolute zero point.
• Y: The vertical distance from the top-left corner of the viewport to the absolute zero point.

To better understand how these values work, experiment with the demo below.

To update the content matrix values, use the patchContentMatrix method. All parameters are optional.

    
canvas.patchContentMatrix({
  scale: 2,
  x: 100,
  y: 100,
});

  

This matrix is the inverse of the viewport matrix.