Eventos de activación

Tu visualización puede activar eventos que una página de host puede registrar para recibir. Las acciones del usuario pueden activar los eventos (por ejemplo, cuando hace clic en un gráfico). También pueden ser internos (por ejemplo, activar un evento cada 10 segundos). Puedes registrar un método de JavaScript para que se llame cada vez que se activen ciertos eventos, posiblemente con datos específicos de ese evento.

Cada visualización define sus propios eventos, y la documentación de esa visualización debe describir cuándo se activa cada evento, qué significa y qué información envía a tu controlador de eventos (por ejemplo, consulta la visualización de organigrama). En esta página, se describe cómo un creador de visualizaciones puede activar eventos. Si deseas obtener información sobre cómo los clientes pueden registrarse para recibir eventos, consulta la página Cómo controlar eventos.

Hay un evento que cualquier visualización seleccionable debe activar: el evento de selección. Sin embargo, cada visualización define el comportamiento y el significado de este evento.

Si una visualización no está lista para interactuar inmediatamente después de que el método draw le devuelve el control al usuario, se debe activar la visualización: el evento “ready”. El comportamiento y el significado exactos de este evento se definen en la sección The Ready Event.

Es importante tener en cuenta que los eventos de la API de visualización son independientes y distintos de los eventos estándares del DOM.

Contenido

  1. Cómo activar un evento
  2. El evento Selecto
  3. El evento de Ready Image Ads
  4. Más información

Cómo activar un evento

Para activar un evento desde tu visualización, llama a la función google.visualization.events.trigger(). La función espera los siguientes parámetros:

  1. Visualización de fuente (por lo general, es el valor this).
  2. Nombre del evento (cadena).
  3. Detalles del evento (objeto). Un mapa opcional (nombre/valor) de detalles de eventos específicos.

En el siguiente ejemplo, se muestra cómo una visualización arroja el evento de selección: 

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', {});
};

Las páginas de hosting se pueden registrar para recibir tus eventos llamando a google.visualization.events.addListener() o google.visualization.events.addOneTimeListener(). Asegúrate de documentar minuciosamente cualquier evento que actives.

El evento Selecto

El evento "select" es un evento estándar que arrojan muchas visualizaciones en respuesta al clic del mouse del usuario. Si decides activar un evento en respuesta a los clics del mouse, debes implementar el evento "select" de la manera estándar que se describe a continuación:

  1. Activa un evento con el nombre "select" cuando el usuario seleccione algunos datos en la visualización. El evento no envía ningún argumento a las funciones de escucha.
  2. Expón el método getSelection() como se describe en la sección del documento vinculado. Este método debe mostrar los índices de los elementos data que el usuario seleccionó.
  3. Expón un método setSelection() como se describe en la sección referencia. Consulta también la página sobre cómo controlar eventos para obtener información sobre cómo hacerlo.

El evento Ready

Cualquier visualización debe activar un evento "listo" que funcione de manera estándar para informar al desarrollador cuándo la visualización está lista para procesarse (métodos). (Sin embargo, no hay un requisito absoluto para que una visualización se comporte de esta manera; consulta la documentación de tu visualización).

En general, las visualizaciones que exponen el evento "listo" se diseñaron con las siguientes especificaciones:

  • El evento ready no pasa ninguna propiedad al controlador (el controlador de tu función no debe esperar que se le pase ningún parámetro).
  • La visualización debe activar el evento ready una vez que esté lista para la interacción. Si el dibujo de la visualización es asíncrono, es importante que el evento se active cuando se pueda llamar a los métodos de interacción, y no solo cuando finalice el método draw.
  • Debes agregar un objeto de escucha a este evento antes de llamar al método draw. De lo contrario, el evento podría activarse antes de que se configure el objeto de escucha y no lo podrás capturar.
  • Si llamas a los métodos de interacción antes de que se active el evento de estado listo, te arriesgas a que no funcionen correctamente.

La convención es que las visualizaciones que no activan un evento "listo" están listas para la interacción inmediatamente después de que finaliza el método draw y le devuelve el control al usuario.

Más información