Events

Events in yFiles for HTML are handled by adding or removing event listeners using the corresponding native methods in JavaScript/TypeScript, along with the appropriate event name. For example, the node-created event can be handled using the native methods addEventListener('node-created', handler) and removeEventListener('node-created', handler).

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

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

In most cases, you’ll interact with the EventArgs in an event handler. The source argument is useful when you use a single event handler for events from different event sources.

Listening for the node-created event shows how to listen for the node-created event.

graphEditorInputMode.addEventListener(
  'node-created',
  (evt, inputMode) => {
    /* react to the node creation caused by input events */
  }
)

Note that events may be fired in a specific order or even multiple times, depending on the event. The API documentation of the event-defining methods provides information to help you understand the event flow.

Stopping Event Propagation

Adding a listener to an event means 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 occurs 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.addEventListener('item-double-clicked', (evt) => {
  // only handle double click events on nodes
  if (evt.item instanceof INode) {
    console.log('The following node has been double clicked: ' + evt.item)
    console.log('Click occurred at ' + evt.location)
    evt.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 is that label editing won’t start on double-clicked nodes, as it normally would. The presumption here is that when the event was handled, all default actions associated with it should be suppressed. Especially regarding click events, this is further detailed in the section Pointer Handling.

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

graphEditorInputMode.addEventListener('query-item-tool-tip', (evt) => {
  evt.toolTip = `This is a tooltip for ${evt.item}`
  evt.handled = true
})