Événements de déclenchement

Votre visualisation peut déclencher des événements qu'une page hôte peut enregistrer pour recevoir. Les événements peuvent être déclenchés par des actions de l'utilisateur (par exemple, un utilisateur qui clique sur un graphique) ou internes (par exemple, se déclencher toutes les 10 secondes). Vous pouvez enregistrer une méthode JavaScript à appeler chaque fois que certains événements sont déclenchés, éventuellement avec des données spécifiques à cet événement.

Chaque visualisation définit ses propres événements. La documentation de chaque visualisation doit décrire le déclenchement de chaque événement, sa signification et les informations qu'il envoie à votre gestionnaire d'événements (voir la visualisation de l'organigramme, par exemple). Cette page décrit comment un créateur de visualisation peut déclencher des événements. Pour savoir comment les clients peuvent s'inscrire pour recevoir des événements, consultez la page Gérer les événements.

Une visualisation sélectionnable doit déclencher un événement: l'événement "select". Cependant, le comportement et la signification de cet événement sont définis par chaque visualisation.

Si une visualisation n'est pas prête à interagir immédiatement après que la méthode draw a renvoyé le contrôle à l'utilisateur, la visualisation doit se déclencher: l'événement "Prêt". Le comportement exact et la signification de cet événement sont définis dans la section Événement prêt.

Il est important de noter que les événements de l'API de visualisation sont distincts des événements DOM standards.

Contenus

  1. Déclencher un événement
  2. L'événement "Select"
  3. Événement prêt
  4. En savoir plus

Déclencher un événement

Pour déclencher un événement à partir de votre visualisation, appelez la fonction google.visualization.events.trigger(). La fonction attend les paramètres suivants :

  1. Visualisation source (généralement la valeur this).
  2. Nom de l'événement (chaîne).
  3. Détails de l'événement (objet). Carte facultative (nom/valeur) des détails de l'événement.

L'exemple suivant montre comment une visualisation génère l'événement "select" : 

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

Les pages d'hébergement peuvent s'inscrire pour recevoir vos événements en appelant google.visualization.events.addListener() ou google.visualization.events.addOneTimeListener(). Veillez à enregistrer minutieusement tous les événements que vous déclenchez.

Sélectionner l'événement

L'événement "select" est un événement standard généré par de nombreuses visualisations en réponse à un clic de la souris de l'utilisateur. Si vous choisissez de déclencher un événement en réponse à des clics de souris, vous devez implémenter l'événement "select" selon la procédure standard décrite ici:

  1. Déclencher un événement nommé "select" lorsque l'utilisateur sélectionne des données dans la visualisation. L'événement n'envoie aucun argument aux fonctions d'écoute.
  2. Exposez la méthode getSelection() comme décrit dans la section "Document associé". Cette méthode doit renvoyer les index des éléments data que l'utilisateur a sélectionnés.
  3. Exposez une méthode setSelection() comme décrit dans la section de référence. Consultez également la page Événements de gestion pour savoir comment gérer les événements.

Événement prêt

Toute visualisation doit déclencher un événement "prêt" qui fonctionne de manière standard afin d'indiquer au développeur quand la visualisation est prête à traiter les méthodes appelées "méthodes". (Toutefois, il n'y a aucune exigence absolue quant au comportement d'une visualisation ; consultez la documentation de votre visualisation.

En général, les visualisations qui exposent l'événement "prêt" sont conçues selon les spécifications suivantes:

  • L'événement "ready" ne transmet aucune propriété au gestionnaire (votre gestionnaire de fonctions ne doit pas s'attendre à ce qu'aucun paramètre lui soit transmis).
  • La visualisation devrait déclencher l'événement prêt lorsque la visualisation est prête à interagir. Si le dessin de la visualisation est asynchrone, il est important que l'événement se déclenche lorsque des méthodes d'interaction peuvent être appelées, et pas seulement à la fin de la méthode draw.
  • Vous devez ajouter un écouteur à cet événement avant d'appeler la méthode draw, sinon il risque de se déclencher avant que l'écouteur ne soit configuré et vous ne l'interceptez pas.
  • En appelant des méthodes d'interaction avant le déclenchement de l'événement prêt, vous prenez le risque que ces méthodes ne fonctionnent pas correctement.

La convention est que les visualisations qui ne déclenchent pas d'événement "prêt" sont prêtes à interagir immédiatement après la fin de la méthode draw et renvoient le contrôle à l'utilisateur.

Plus d'infos