Event API ​

The event API can be accessed by registering a callback function with the on() method of the ForceSimulation instance. It takes the event identifier string as first argument and the callback function as second argument.

simulation.on("", (...args) => {
	// do something
});

Using the Event enum from the graphly-d3 package you can easily register to the available default events.

enum Event {
	NodeClick = "node:click",
	NodeDoubleClick = "node:doubleclick",
	NodeContextMenu = "node:contextmenu",
	NodeDragStart = "node:dragstart",
	NodeDragMove = "node:dragmove",
	NodeDragEnd = "node:dragend",

	LinkClick = "link:click",
	LinkDoubleClick = "link:doubleclick",
	LinkContextMenu = "link:contextmenu",
	LinkDragStart = "link:dragstart",
	LinkDragMove = "link:dragmove",
	LinkDragEnd = "link:dragend",

	EnvironmentClick = "environment:click",
	EnvironmentDoubleClick = "environment:doubleclick",
	EnvironmentContextMenu = "environment:contextmenu",
	EnvironmentMove = "environment:move",

	SimulationTick = "simulation:tick",
	SimulationTickEnd = "simulation:tickend",

	ThemeChange = "theme:change", // available since v1.4.0
}

Node Click ​

The "node:click" event is triggered when a node shape is clicked by the user. It provides arguments about the event and the node object that was clicked.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.NodeClick, (event, node) => {
	// do something
});

Node Double Click ​

The "node:doubleclick" event is triggered when a node shape is double clicked by the user. It provides arguments about the event and the node object that was double clicked.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.NodeDoubleClick, (event, node) => {
	// do something
});

Node Context Menu ​

The "node:contextmenu" event is triggered when a node shape is right clicked by the user. It provides arguments about the event and the node object that was right clicked.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.NodeContextMenu, (event, node) => {
	// do something
});

Node Drag Start ​

The "node:dragstart" event is triggered when a node shape is started to be dragged by the user. It provides arguments about the event, the node object and the position the node was dragged from. position contains x and y coordinates.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.NodeDragStart, (event, node, position) => {
	// do something
});

If you return the string "newlink" within the callback, the "link:dragstart" event will be triggered and the node dragging process will be interrupted.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.NodeDragStart, (event, node, position) => {
	if (event.sourceEvent.altKey) {
		return "newlink";
	}
	// else do something
});

Node Drag Move ​

The "node:dragmove" event is triggered when a node shape is dragged by the user. It provides arguments about the event, the node object and the position the node was dragged to. position contains x and y coordinates.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.NodeDragMove, (event, node, position) => {
	// do something
});

Node Drag End ​

The "node:dragend" event is triggered when a node shape is dragged by the user and released. It provides arguments about the event, the node object and the position the node was dragged to. position contains x and y coordinates.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.NodeDragEnd, (event, node, position) => {
	// do something
});

Link Click ​

The "link:click" event is triggered when a link between two nodes is clicked by the user. It provides arguments about the event and the link object that was clicked.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.LinkClick, (event, link) => {
	// do something
});

Link Double Click ​

The "link:doubleclick" event is triggered when a link between two nodes is double clicked by the user. It provides arguments about the event and the link object that was double clicked.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.LinkDoubleClick, (event, link) => {
	// do something
});

Link Context Menu ​

The "link:contextmenu" event is triggered when a link between two nodes is right clicked by the user. It provides arguments about the event and the link object that was right clicked.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.LinkContextMenu, (event, link) => {
	// do something
});

Link Drag Start ​

The "link:dragstart" event is triggered when a link is started to be dragged from one node (source). It provides arguments about the event, the source node object and the position the link was dragged from. position contains x and y coordinates.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.LinkDragStart, (event, sourceNode, position) => {
	// do something
});

Link Drag Move ​

The "link:dragmove" event is triggered when a link is being dragged. It provides arguments about the event, the source node object and the position the link was dragged to. position contains x and y coordinates.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.LinkDragMove, (event, sourceNode, position) => {
	// do something
});

Link Drag End ​

The "link:dragend" event is triggered when a link is dragged and released. It provides arguments about the event, the source node object, the target node object and the position the link was dragged to. position contains x and y coordinates.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.LinkDragEnd, (event, sourceNode, targetNode, position) => {
	// do something
});

The targetNode is only set if the link is released over another node then the source node.

simulation.on(Event.LinkDragEnd, (event, sourceNode, targetNode, pos) => {
	if (targetNode) {
		const link = {
			source: sourceNode.id,
			target: targetNode.id,
		};
		graph.links.push(link);
		simulation.render(graph);
	}
});

Environment Click ​

The "environment:click" event is triggered when the user clicks on the svg element. It provides arguments about the event and the position of the click within the svg world. position contains x and y coordinates.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.EnvironmentClick, (event, position) => {
	// do something
});

Environment Double Click ​

The "environment:doubleclick" event is triggered when the user double clicks on the svg element. It provides arguments about the event and the position of the click within the svg world. position contains x and y coordinates.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.EnvironmentDoubleClick, (event, position) => {
	// do something
});

Environment Context Menu ​

The "environment:contextmenu" event is triggered when the user right clicks on the svg element. It provides arguments about the event and the position of the click within the svg world. position contains x and y coordinates.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.EnvironmentContextMenu, (event, position) => {
	// do something
});

Environment Move ​

The "environment:move" event is triggered when the user moves the svg world by dragging the background. It provides the argument about the current transform of the svg world. transform contains x and y coordinates and the k scale factor.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.EnvironmentMove, (transform) => {
	// do something
});

Simulation Tick ​

The "simulation:tick" event is triggered on each step of the simulation.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.SimulationTick, () => {
	// do something
});

Simulation Tick End ​

The "simulation:tickend" event is triggered when the simulation is finished and the node movement is finished.

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.SimulationTickEnd, () => {
	// do something
});

Theme Change ​

The "theme:change" event is triggered when the theme of the simulation is changed. It provides the argument about the current theme of the simulation. (either "light" or "dark")

import { Event } from "@livereader/graphly-d3";
simulation.on(Event.ThemeChange, (theme) => {
	// do something
});

Custom Template Events ​

The template events are special events that can be triggered by shape templates. More detailed information about how to fire these events can be found in the EmitEvent section of the Template API.

You can also listen to these events by using the on method and using a special event name pattern: "template:<template-name>:<event-name>".

It always provides the arguments about the 'node' data object and the event object. Any further arguments are specified by the EventEmitter of the template.

simulation.on("template:myShape:myCustomEvent", (node, event, ...args) => {
	// do something
});

simulation.on("template:myShape:myCustomEvent", (node, event) => {
	event.stopPropagation();
});