Event Listeners

• Overview
• Listener Methods
  • listen()
  • listenOnce()
  • removeAllListeners()
  • unlisten()
  • unlistenByKey()
• Event types
  • Mouse-Related
  • Point-Related
• Manage Single Point

Overview

In AnyChart html5 charting library when user interacts with a chart different events are generated by JavaScript. Events are distributed to chart elements (title, legend, axis, etc.), and to make those elements respond to events, you should attach event listeners to them.

Event Listeners are JavaScript functions once applied to an object wait for the defined action over this object to be performed.

It's possible to attach more than one listener to an object.

There are 5 main listener methods:

• listen(),
• listenOnce(),
• removeAllListeners(),
• unlisten()
• and unlistenByKey())

And there are a lot of event types, described in this article.

Listener Methods

There are five listener methods in Anychart, each type for a special case. Read the following information to find out how to use listeners.

listen()

The listen() method adds an event listener to an object.

chart.listen("click", function() {
	dataSet.append({
		// x value
		x: "P" + indexSetter,

		// random value from 1 to 500
		value : Math.floor((Math.random() * 500)+ 1)
	});
	indexSetter++;
});

listenOnce()

The listenOnce() method adds an event listener that should react only once. It means that when the defined event happens for the first time, this listener reacts and then disables itself, so there will be no reaction when the event happens again.

// adding a listener 
// click twice on any range bar to see the result

range.listenOnce("dblClick",
  function() {
    range.fill("red");
  });

removeAllListeners()

The removeAllListeners() method removes all event listeners from the object.

// remove all listeners
chart.listen("dblClick", function() {
  chart.removeAllListeners();
});

Note that when you intend to stop listen to an only event or all of them, you should add an unlisten() method from inside of the listen() one.

unlisten()

The unlisten() method disables the particular listener added using the listen() or listenOnce() methods.

// create a function for what to listen and then unlisten
var func_listen = function() {
  dataSet.append({
    // x value
    x: "P" + indexSetter,

    // random value from 1 to 500
    value : Math.floor((Math.random() * 500)+ 1)
  });
  indexSetter++;
};

// add a listener
chart.listen("mouseMove", func_listen);

chart.listenOnce("click",function() {
  // adding an unlistener 
  chart.unlisten("mouseMove", func_listen);
});

unlistenByKey()

The unlistenByKey() method removes an event listener which was added with listen() by the key returned by listen() or listenOnce(). The only parameter of this method is the key to be listened to.

It's necessary to define the key of the listener that you want to disable.

// add a listener
var key = chart.listen("mouseMove", func_listen);

// unlisten this
// click twice on the chart to see the result
chart.listen("dblclick",
  function() {
    chart.unlistenByKey(key);
  }
);

Event types

There are a lot of event types which are broken to two categories: mouse-oriented and point-oriented. Point-oriented events contain information about the point, while the mouse-oriented events are simply events with no point parameters.

Mouse-Related

Mouse-Related events provide no information about the point.

//add a listener
chart.listen("mouseDown", function() {
  // this will open a new page in a new tab
  window.open("https://google.com","_blank");
});

Look through the next paragraph to understand the difference between the mouse-related and point-related events.

Point-Related

Opposite to mouse-related methods, these point-related events can provide information about the point.

In the next sample two listeners are added. One of them tracks clicks and changes the fill of the point, the second one handles double-click on the point and uses point's "url" value as the query for the google search and opens a new page with a google search. When a point is clicked on once, it changes the color.

// add a listener
chart.listen("pointClick", function(e){
  var index = e.iterator.getIndex();
  var row = dataSet.row(index);
  if (row.fillOld){
    row.fill = row.fillOld; delete row.fillOld;
  }else{
    row.fillOld = row.fill; row.fill = "green";
  }
  dataSet.row(index, row);
});

// add a listener
chart.listen("pointDblClick", function(e){ 
  var new_value = e.iterator.get("url");
  window.open(new_value,"_blank"); 
});

Manage Single Point

To make your chart more flexible, AnyChart js charting framework provides several ways of managing states of a single point. Event's parameter contains a number of properties that can ease interactivity managing.

For instance, point property can be used to get the point that triggered the event. This property provides pretty much the same options as getPoint() method does. All methods of a series point can be invoked upon this property.

As an example, let's use pointsHover event to find out the index of the hovered point and set hovered state for adjacent points.

// create chart
var chart = anychart.column();
// set series data
chart.column(data);

// create an event listener for the pointsHover event
chart.listen("pointsHover", function(event){
  // get hovered point
  var point = event.point;
  // get index of hovered point
  var index = point.getIndex();
  // get series of hovered point
  var series = point.getSeries();
  // unhover the series on point unhovering
  if (!point.hovered())return;
  // create array for further hovering
  var arrayToHover = [index];
  // checking existence of a point before hovered one
  if (series.getPoint(index-1).exists())
    // push the point for further hovering
    arrayToHover.push(index-1);
  // checking existence of a point after hovered one
  if (series.getPoint(index+1).exists())
    // push this point for further hovering
    arrayToHover.push(index+1);
  // hover points from the array
  series.hover(arrayToHover);
});

Even though this code works fine, there isn't much sense in hovering three random points. Instead, we can hover points, that are somehow related. Let's create a chart, display the income through the year and hover all the points of a quarter, the hovered point belongs to:

// create an event listener for the pointsHover event
chart.listen("pointsHover", function(event){
  // getter for hovered point
  var point = event.point;
  // index of hovered point
  var index = point.getIndex();
  // getter for hovered point's series
  var currentSeries = point.getSeries();
  /* if this event is triggered when the point
  is not in the hover state, nothing will happen */
  if (!event.currentPoint.hovered) return;
  // get an array of months, hovered point belong to and hover it.
  currentSeries.hover(getQuarterMonths(index));
});
// find out an array a month belong to
function getQuarterMonths(month) {
  var quarterStartMonth = 3 * Math.floor(month / 3);
  return [quarterStartMonth, quarterStartMonth + 1, quarterStartMonth + 2];
}

And here is a sample with these settings: