Eventos de disparo

Sua visualização pode disparar eventos que uma página de host pode registrar para receber. Os eventos podem ser acionados por ações do usuário, como clicar em um gráfico, ou interno, por exemplo, disparar um evento a cada 10 segundos. É possível registrar um método JavaScript para ser chamado sempre que determinados eventos são disparados, possivelmente com dados específicos a eles.

Cada visualização define os próprios eventos, e a documentação dessa visualização precisa descrever quando cada evento é disparado, o que ele significa e quais informações ele envia ao manipulador de eventos (por exemplo, consulte a visualização de gráfico). Nesta página, descrevemos como um criador de visualizações pode disparar eventos. Para saber como os clientes podem se registrar para receber eventos, consulte a página Como processar eventos.

Há um evento que qualquer visualização selecionável precisa disparar: o evento selecionado. No entanto, o comportamento e o significado desse evento são definidos em cada visualização.

Se uma visualização não estiver pronta para interação imediatamente após o método draw retornar o controle ao usuário, a visualização será disparada: o evento "ready". O comportamento e significado exatos desse evento é definido na seção O evento pronto.

É importante observar que os eventos da API Preview são separados e distintos dos eventos padrão do DOM.

Índice

  1. Como disparar um evento
  2. O evento "Selecionar"
  3. O evento pronto
  4. Mais informações

Acionar um evento

Para disparar um evento da sua visualização, chame a função google.visualization.events.trigger(). A função espera receber os parâmetros abaixo:

  1. Visualização de origem (normalmente, o valor de this).
  2. Nome do evento (string).
  3. Detalhes do evento (objeto). Um mapa opcional (nome/valor) de detalhes específicos do evento.

O exemplo a seguir mostra como uma visualização gera o evento de seleção: 

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

As páginas de hospedagem podem se registrar para receber seus eventos chamando google.visualization.events.addListener() ou google.visualization.events.addOneTimeListener(). Não esqueça de documentar todos os eventos que você disparar.

Selecionar evento

O evento "select" é padrão e gerado por muitas visualizações em resposta a um clique do usuário. Se você optar por disparar um evento em resposta a cliques do mouse, implemente o evento "select" da maneira padrão descrita aqui:

  1. Dispara um evento com o nome "select" quando o usuário seleciona alguns dados na visualização. O evento não envia argumentos às funções de detecção.
  2. Exponha o método getSelection() conforme descrito na seção do documento vinculado. Esse método retorna os índices de elementos data selecionados pelo usuário.
  3. Exponha um método setSelection(), conforme descrito na seção de referência. Consulte também a página sobre como gerenciar eventos.

O evento pronto

Qualquer visualização precisa disparar um evento "ready" que funciona de maneira padrão para informar ao desenvolvedor quando a visualização está pronta para ser processada. No entanto, não há requisito absoluto para que uma visualização se comporte dessa maneira. Verifique a documentação da sua visualização.

Em geral, as visualizações que expõem o evento "pronto" são projetadas com as seguintes especificações:

  • O evento "ready" não transmite nenhuma propriedade ao gerenciador. Seu gerenciador de funções não pode esperar nenhum parâmetro ser transmitido a ele.
  • A visualização precisa disparar o evento pronto depois que ela estiver pronta para interação. Se o desenho da visualização for assíncrono, é importante que o evento seja acionado quando os métodos de interação puderem ser chamados e não apenas quando o método draw terminar.
  • É necessário adicionar um listener a esse evento antes de chamar o método draw, porque, caso contrário, o evento será acionado antes da configuração do listener e você não o capturará.
  • Ao chamar métodos de interação antes que o evento pronto seja acionado, você assume o risco de que esses métodos não funcionem corretamente.

A convenção é que as visualizações que não disparam um evento "pronto" ficam prontas para interação imediatamente após o término do método draw e retornam o controle ao usuário.

Mais informações