Events

Visualization Events Overview

JavaScript within the browser is event driven, meaning that JavaScript responds to interactions by generating events, and expects a program to listen to interesting events. For example, within browsers, user mouse and keyboard interactions create events that propagate within the DOM. Programs interested in certain events will register JavaScript event listeners for those events and execute code when those events are received.

The Google Visualization API event model follows the same model as that of browsers, and adds to this event model by defining custom events for Visualization API objects. It is important to note that the Visualization API events are separate and distinct from the standard DOM events.

Triggering an Event

To trigger an event from your own 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;

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

Event Listeners

To register for notification of visualization events, use the method google.visualization.events.addListener(). This method takes an object, an event to listen for, and a function to call when the specified event occurs. For example, this code snippet shows an alert every time the user clicks on a table row:

var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler() {
  alert('A table row was selected');
}

The Select Event

Some events that are triggered by visualizations are specific to a single visualization, but there are events that are common to many visualizations. The select event is a generic event, and every visualization that supports selection should handle the select event in a common way.

Visualizations that support selection should do the following:

1. Trigger an event with the name 'select' when the user selects some data within the visualization. The event has no required properties.
2. Provide a method getSelection(). This method returns indexes of data elements that the user selected. The returned value of this method is an array, in which each element is an object with properties row and column. row and column are indexes of rows and columns in the DataTable.
   If both row and column and specified, the selected element is a cell. If only row is specified, the selected element is a row. If only column is specified, the selected element is a column.
3. Provide a method setSelection(selection). This method returns an array, in which each element is an object with properties row and column, where row is the index of the selected row in the DataTable, and column is the index of the selected column in the DataTable. When this method is called, the visualization should visually indicate what the new selection is. The implementation of setSelection() should not trigger a select event.
   If both row and column are specified, the selected element is a cell. If only row is specified, the selected element is a row. If only column is specified, the selected element is a column.
   Visualizations may ignore part of the selection. For example a table that can show only selected rows may ignore cell or column elements in its setSelection implementation, or it can select the entire row.