Events

Events in yFiles for HTML consist of a pair of methods that add or remove an event listener. For example, the NodeCreated event is defined by the two methods addNodeCreatedListener and removeNodeCreatedListener.

Event listeners in yFiles for HTML are functions with two arguments: a generic source which is the object that raised the event, and an EventArgsargs object that carries additional information for the event.

// source is the object which dispatched the event
// args is the EventArgs object which carries the information for the event
const listener = function (source, args) {}
// source is the object which dispatched the event
// args is the EventArgs object which carries the information for the event
const listener = function (source: GraphEditorInputMode, args: ItemEventArgs<INode>): void {}

In most cases you’ll be interacting with the EventArgs in an event handler, whereas the source argument can be useful in cases where you use a single event handler for events on different event sources.

Listening for the NodeCreated event shows how to listen for the aforementioned NodeCreated event as an example.

graphEditorInputMode.addNodeCreatedListener((source, args) => {
  /* react to the node creation caused by input events */
})

Note that events may be fired in a certain order, or may even be fired multiple times, dependent on the event. The API documentation of the event defining methods provide all information to help you understand the event flow.

Stopping Event Propagation

Adding a listener to an event means that the listener is added to a list of event listeners. The event is then propagated to each listener in the event list. Some events offer the possibility to stop the event propagation. This is the case when the EventArgs that the event handler function takes as argument defines a Handled property, for example handled. When a listener sets this property to true, event propagation stops.

This is used in situations where it is unclear which listener should handle an event. In this case the list of handlers is iterated until a listener marks the event as handled.

graphEditorInputMode.addItemDoubleClickedListener((source, args) => {
  // only handle double click events on nodes
  if (args.item instanceof INode) {
    console.log('The following node has been double clicked: ' + args.item)
    console.log('Click occurred at ' + args.location)
    args.handled = true
  }
  // don't do anything in other cases (especially not setting "handled" to true),
  // because this listener only reacts to nodes
})

The Handling a double click event example shows an event listener that reacts to double click events on items. It stops the propagation once it recognizes a double clicked item that it can handle. The most visible change of that is that label editing won’t start on double clicked nodes as it would normally. The presumption here is that when the event was handled, all default actions associated with it should be suppressed. Especially in regard to click events this is further detailed in the section Customizing Mouse Clicks.

Another usage of events is to gather additional information for some IInputModes. For example, to add tool tips for certain items in the graph, it is possible to listen to the GraphEditorInputMode.QueryItemToolTip event and set the ToolTipQueryEventArgs.toolTip property. Adding tooltips to items via the QueryItemToolTip event shows an example for this. For more information on how to customize tool tips, have a look at the section Customizing Tooltips.

graphEditorInputMode.addQueryItemToolTipListener((source, args) => {
  args.toolTip = `This is a tooltip for ${args.item}`
  args.handled = true
})