Firing Events

Your visualization can fire events that a host page can register to receive. Events can be fired by user actions: for example a user clicks on a chart, or can be internal: for example, firing an event every 10 seconds. You can register a Javascript method to be called whenever certain events are fired, possibly with data specific to that event.

Every visualization defines its own events, and the documentation for that visualization should describe when each event is fired, what it means, and what information it sends to your event handler (for example, see the orgchart visualization). This page describes how a visualization creator can fire events. To learn how clients can register to receive events, see the Handling Events page.

There is one event that any selectable visualization should fire: the select event. However, the behavior and meaning of this event is defined by each visualization.

If a visualization is not ready for interaction immediately after the draw method returns control to the user, the visualization should fire: the ready event. The exact behavior and meaning of this event is defined in The Ready Event section.

It is important to note that the Visualization API events are separate and distinct from the standard DOM events.

Contents

  1. Firing an Event
  2. The Select Event
  3. The Ready Event
  4. More Information

Firing an Event

To fire an event from your visualization, call the google.visualization.events.trigger() function. The function expects the following parameters:

  1. Source visualization (typically this is the this value).
  2. Event name (string).
  3. Event details (Object). An optional map (name/value) of specific event details.

The following example shows how a visualization throws the select event: 

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Fire a select event.
  google.visualization.events.trigger(this, 'select', {});
};

Hosting pages can register to receive your events by calling google.visualization.events.addListener() or google.visualization.events.addOneTimeListener(). Be sure to document thoroughly any events that you fire.

The Select Event

The "select" event is a standard event thrown by many visualizations in response to a user mouse click. If you choose to fire an event in response to mouse clicks, you should implement the "select" event in the standard way described here:

  1. Fire an event with the name 'select' when the user selects some data within the visualization. The event does not send any arguments to the listening functions.
  2. Expose the getSelection() method as described in the linked document section. This method should return the indexes of data elements that the user selected.
  3. Expose a setSelection() method as described in the reference section. Also see the handling events page to learn how to handle events.

The Ready Event

Any visualization should fire a "ready" event that works in a standard way to let the developer know when the visualization is ready to process called methods. (However, there is no absolute requirement that a visualization behave this way; check the documentation for your visualization).

In general, visualizations that expose the "ready" event are designed with the following specifications:

  • The ready event does not pass any properties to the handler (your function handler should not expect any parameters to be passed to it).
  • The visualization should fire the ready event after the visualization is ready for interaction. If the drawing of the visualization is asynchronous, it is important that the event is fired when interaction methods can actually be called, and not just when the draw method ends.
  • Adding a listener to this event should be done before calling the draw method, because otherwise the event might be fired before the listener is set up and you will not catch it.
  • By calling interaction methods before the ready event is fired, you take a risk that these methods will not work properly.

The convention is that visualizations which do not fire a "ready" event are ready for interaction immediately after the draw method ends and returns control to the user.

More Information