/

Listening to events

You can attach listeners to react to various events, such as mouse movement or some points being hovered over.

Event listeners are functions invoked by dotAtlas when certain conditions or triggers are met. Some listeners are invoked only for user-triggered actions, such as onMouseMove, others may be a result of internal state changes like onRedraw.

You can listen to global dotAtlas events, such as onRedraw, but also to layer-specific events, such as onMaxElevationChanged. Events related to user's interactions with specific data points, such as onPointClick, are available on the layer level.

You can manage event listeners by setting the relevant properties or by calling the event management methods.

Using event properties

One way to manage event listeners is by getting or setting the related properties, or, most commonly, by providing the listeners during initial embedding and layer creation: 

const dotatlas = DotAtlas.embed({
  "element": document.getElementById("dotatlas"),
  "layers": [
    {
      "type": "points",
      "points": [ ],
      "onPointClick": e => { console.log("point clicked", e); }
    }
  ],
  "onClick": e => { console.log("clicked", e); },
  "onMouseWheel": [
    e => { console.log("scrolled 1", e); },
    e => { console.log("scrolled 2", e); }
  ]
});

For each event property you can provide an individual function or an array of functions. However, when you get the option value, always an array of functions will be returned, even if there is only one function registered for a specific event.

Heads up!

Setting a new function for a specific event will remove all previously registered functions for that event. This may remove event listeners registered by plugins and prevent them from functioning. Therefore, if you use plugins, the safest way to register listeners for core dotAtlas events is by calling event management methods.

Using event methods

Another way to manage dotAtlas events is to use the on(), once() and off() methods on the dotAtlas or layer instance. 

const dotatlas = DotAtlas.embed({
  "element": document.getElementById("dotatlas"),
  "layers": [
    {
      "type": "points",
      "points": []
    }
  ]
});

dotatlas.on("click", e => {
  console.log("clicked", e);
});
dotatlas.on("mouseWheel", e => {
  console.log("scrolled 1", e);
});
dotatlas.on("mouseWheel", e => {
  console.log("scrolled 2", e);
});

const points = dotatlas.get("layers")[0];
points.on("pointClick", e => {
  console.log("point clicked", e);
});

Notes:

  • To get the event name to use with the on(), once(), off() method, take the event property name, remove the leading "on" and lower-case the first letter, for example:

    Property name for set() Event name for on(), once() and off()
    onClick click
    onPointClick pointClick
    onMaxElevationChanged maxElevationChanged

  • Use the once() method to register one-off listeners. There is no equivalent mechanism in the property-based listener management.

  • Using event management method does not affect other listeners registered for the specific event.

  • When calling the off() method, make sure you supply the same function instance you provided for the on() method: 

    const handler = e => console.log("clicked", e);
dotatlas.on("click", handler);
dotatlas.off("click", handler);

Low- vs high-level events

TODO: explain the difference between dotAtlas.onClick and layer.onPointClick.