Docs
`/`

# API elements

No matching results

# Sections and content

No matching results

- `Enter` to go to the highlighted result.
- `↑` and `↓` to change highlight.
- `Tab` to switch between result lists.
- `Esc` to hide the results.

# 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.

previous article
Managing properties
next article
Setting new points