Visão geral sobre eventos roteados

Este tópico pressupõe que você tenha conhecimento básico sobre o common language runtime (CLR) e programação orientada a objetos, bem como o conceito de como as relações entre elementos WPF podem ser conceitualizados como uma árvore. Para que você siga os exemplos deste tópico, você também deve entender Extensible Application Markup Language (XAML) e saber como escrever aplicações ou páginas WPF básicas. Para obter mais informações, consulte Demonstra Passo a passo: Guia de Introdução do WPF e Visão geral do XAML (WPF).

Você pode pensar sobre eventos roteados quer do ponto de vista funcional ou implementação. Ambas as definições são apresentadas aqui, pois algumas pessoas acham uma das duas definições mais útil que a outra.

Definição funcional: Um evento roteado é um tipo de evento que pode chamar manipuladores em vários ouvintes em uma árvore, em vez de apenas no objeto que disparou o evento.

Definição de implementação: A evento roteado is a CLR qual é feito por uma ocorrência de eventos do RoutedEvent classe e processado pela Windows Presentation Foundation (WPF) sistema de eventos.

Um aplicativo WPF típico contém muitos elementos. Quer eles sejam criados em código ou declarados em XAML, esses elementos tem um relacionamento de árvore entre si. A rota do evento pode se mover em uma das duas direções, dependendo da definição do evento, mas geralmente a rota vai do elemento de origem e sobe como uma "bolha" através da árvore de elementos até que ele atinja o elemento raiz da árvore (geralmente uma página ou uma janela).

Considere a seguinte árvore de elementos simples:

<Border Height="50" Width="300" BorderBrush="Gray" BorderThickness="1">
  <StackPanel Background="LightGray" Orientation="Horizontal" Button.Click="CommonClickHandler">
    <Button Name="YesButton" Width="Auto" >Yes</Button>
    <Button Name="NoButton" Width="Auto" >No</Button>
    <Button Name="CancelButton" Width="Auto" >Cancel</Button>
  </StackPanel>
</Border>

Esta árvore de elementos produz algo parecido com o seguinte:

Nesta árvore de elementos simplificada, a fonte de um evento Click é um dos elementos Button, e seja qual for o Button clicado, este será o primeiro elemento que tem a oportunidade de tratar o evento. Mas se nenhum manipulador anexado ao Button age sobre o evento, em seguida, o evento sobe como uma bolha ao pai do Button na árvore de elementos, que é o StackPanel. Possivelmente, o evento sobe como bolha para Border e além, até a página raiz da árvore de elementos (não mostrada).

Em outras palavras, a rota de eventos para este evento Click é:

Button-->StackPanel-->Border-->...

Cenários de alto nível para eventos roteados

private void CommonClickHandler(object sender, RoutedEventArgs e)
{
  FrameworkElement feSource = e.Source as FrameworkElement;
  switch (feSource.Name)
  {
    case "YesButton":
      // do something here ...
      break;
    case "NoButton":
      // do something ...
      break;
    case "CancelButton":
      // do something ...
      break;
  }
  e.Handled=true;
}

Como eventos roteados são implementados

Public Shared ReadOnly TapEvent As RoutedEvent = EventManager.RegisterRoutedEvent("Tap", RoutingStrategy.Bubble, GetType(RoutedEventHandler), GetType(MyButtonSimple))

' Provide CLR accessors for the event
Public Custom Event Tap As RoutedEventHandler
    AddHandler(ByVal value As RoutedEventHandler)
        Me.AddHandler(TapEvent, value)
    End AddHandler

    RemoveHandler(ByVal value As RoutedEventHandler)
        Me.RemoveHandler(TapEvent, value)
    End RemoveHandler

    RaiseEvent(ByVal sender As Object, ByVal e As RoutedEventArgs)
        Me.RaiseEvent(e)
    End RaiseEvent
End Event

Manipuladores de eventos roteados e XAML

<Button Click="b1SetColor">button</Button>

Eventos roteados usam uma de três estratégias de roteamento:

• Borbulhamento: Manipuladores de eventos na fonte do evento são invocados.

  O evento roteado, em seguida, encaminha para elementos pai sucessivos até chegar a raiz da árvore de elemento.
  A maioria dos eventos roteados usam a estratégia de roteamento bolha.
  Eventos roteados bubbling são geralmente usados para relatar alterações de estado ou entradas de controles distintas ou outros elementos de interface do usuário.

• Direto: Apenas o elemento fonte em si é terá a oportunidade para chamar manipuladores de resposta. Isso é análogo ao "roteamento" que o Windows Forms usa para eventos. No entanto, diferentemente de um evento CLR padrão, eventos roteados diretos suportam tratamento por classe (tratamento por classe é explicado em uma seção futura) e podem ser usadoa por EventSetter e EventTrigger.

• Tunelamento: Os manipuladores de evento dos elementos na raiz da árvore de elementos são invocados. O evento roteado, em seguida, passa por uma rota através de sucessivos elementos filhos, em direção ao elemento nó que é a fonte do evento roteado (o elemento que lançou o evento roteado). Eventos roteados por tunelamento são frequentemente usados ou tratados como parte da composição de um controle, de tal modo que eventos de partes da composição possam ser deliberadamente suprimidos ou substituídos por eventos que são específicos ao controle completo. Eventos de entrada fornecidos no WPF geralmente vêm implementados como um par tunelamento/bolha. Eventos por tunelamento são também às vezes chamados de eventos de inspeção prévia ("preview"), por causa de uma convenção de nomeclatura que é usada para os pares.

Onde os eventos roteados tornam-se eficientes é se você usar qualquer um dos cenários sugeridos: Definindo manipuladores comuns em uma raiz comum, composição seu próprio controle ou definir sua própria classe de controle personalizado.

Ouvintes de eventos roteados e fontes de eventos roteados não precisam compartilhar um evento em comum em sua hierarquia. Qualquer UIElement ou ContentElement pode ser ouvinte de eventos para qualquer evento roteado. Portanto, você pode usar o conjunto completo de eventos roteados disponíveis em cada API disponível como uma interface conceitual na qual diferentes elementos do aplicativo podem trocar informações de eventos. Esse conceito de "interface" para eventos roteados é aplicável principalmente para eventos de entrada.

Eventos roteados também podem ser usados para se comunicar através da árvore de elementos, pois os dados do evento são perpetuados em cada elemento da rota. Um elemento poderia modificar algo nos dados do evento, e essa alteração estaria disponível para o próximo elemento da rota.

Além do aspecto de roteamento, existem dois outros motivos pelos quais um dado evento do WPF poderia ser implementado como um evento roteado em vez de um evento padrão do CLR. Se você estiver implementando seus próprios eventos, você também pode considerar esses princípios:

• Determinados recursos de templating e estilo do WPF, como EventSetter e EventTrigger, exigem que o evento referenciado seja um evento roteado. Este é o cenário de identificadores de evento mencionado anteriormente.

• Eventos roteados suportam um mecanismo de tratamento por classe pelo qual a classe pode especificar métodos estáticos que terão a oportunidade de tratar os eventos roteados antes que qualquer manipulador registrado por instância possa acessá-los. Isso é muito útil no projeto de controles, pois sua classe pode impor comportamentos de classe orientados a eventos que não podem ser acidentalmente suprimidos ao tratar um evento em uma instância.

Cada uma das considerações acima é discutida em uma seção separada neste tópico.

Para adicionar um manipulador de eventos em XAML, você simplesmente adiciona o nome do evento a um elemento como atributo e define o valor do atributo como o nome do manipulador de eventos que implementa um delegado apropriado, como no exemplo a seguir.

<Button Click="b1SetColor">button</Button>

b1SetColor é o nome do manipulador implementado que contém o código que manipula o Click evento. b1SetColor deve ter a mesma assinatura que o RoutedEventHandler delegado, que é o delegado manipulador de eventos para o Click evento. O primeiro parâmetro de todos os delegados manipuladores de eventos roteados especifica o elemento ao qual o manipulador de eventos é adicionado, e o segundo parâmetro especifica os dados para o evento.

void b1SetColor(object sender, RoutedEventArgs args)
{
  //logic to handle the Click event


...


}

RoutedEventHandler é o delegado manipulador de eventos roteados básico. Para eventos roteados que são especializados para certos controles ou cenários, os delegados a ser usados para os manipuladores de eventos roteados também podem se tornar mais especializados, de modo que eles possam transmitir dados especializados de eventos. Por exemplo, em um cenário comum de entrada, você pode tratar um evento roteado DragEnter . O manipulador deve implementar o delegado DragEventHandler. Usando o delegado mais específico, você pode processar o DragEventArgs no manipulador e ler a propriedade Data, que contém a carga da área de transferência da operação de arrastar.

Para obter um exemplo completo de como adicionar um manipulador de eventos a um elemento usando XAML, consulte Como: Handle a Routed Event.

Adicionar um manipulador para um evento roteado em um aplicativo criado em código é simples. Os manipuladores de eventos roteados sempre podem ser adicionados por meio de um método auxiliar AddHandler (que é o mesmo método que o suporte existente chama para add). No entanto, eventos roteados do WPF existentes geralmente têm implementações de suporte da lógica de add e remove que permitem que os manipuladores de eventos roteados sejam adicionados por uma sintaxe de eventos específica da linguagem, o que é uma sintaxe mais intuitiva que o método auxiliar. Este é um exemplo de uso do método auxiliar:

void MakeButton()
 {
     Button b2 = new Button();
     b2.AddHandler(Button.ClickEvent, new RoutedEventHandler(Onb2Click));
 }
 void Onb2Click(object sender, RoutedEventArgs e)
 {
     //logic to handle the Click event     
 }

O exemplo a seguir mostra a sintaxe de operadores de C# (Visual Basic tem uma sintaxe de operadores ligeiramente diferente devido a seu tratamento de referências):

void MakeButton2()
{
  Button b2 = new Button();
  b2.Click += new RoutedEventHandler(Onb2Click2);
}
void Onb2Click2(object sender, RoutedEventArgs e)
{
  //logic to handle the Click event     
}

Para obter um exemplo de como adicionar um manipulador de eventos em código, consulte Como: Adicionar um manipulador de eventos usando código.

Se você estiver usando Visual Basic, você também pode usar a palavra-chave Handles para adicionar manipuladores como parte das declarações do manipulador. Para obter mais informações, consulte Visual Basic and WPF Event Handling.

O conceito de "tratado"

Se você estiver definindo uma classe que deriva de alguma forma de DependencyObject, você também pode definir e anexar um manipulador por classe para um evento roteado que seja um membro declarado ou herdado da sua classe. Manipuladores por classe são chamados antes de quaisquer manipuladores ouvintes de instância que estejam anexados a uma instância da classe, sempre que um evento roteado atinge uma instância de um elemento em sua rota.

Alguns controles WPF têm tratamento inerente à classe para certos eventos roteados. Isso pode dar a impressão de que o evento roteado nunca é gerado, mas na verdade ele está sendo tratado pela classe, e o evento roteado potencialmente ainda pode ser tratado por seus manipuladores de instância se você usar determinadas técnicas. Além disso, muitas classes base e controles expõem métodos virtuais que podem ser usados para sobrecrever o comportamento de tratamento por classe. Para obter mais informações tanto sobre como contornar tratamento por classe indesejado quanto sobre como definir seu próprio tratamento por classe em uma classe personalizada, consulte Marcando Eventos Roteados como Manipulados e Manipulação de Classes.

A linguagem XAML também define um tipo especial de evento chamado de evento anexado. Um evento anexado permite que você adicione um manipulador para um determinado evento em um elemento arbitrário. O elemento tratando o evento não precisa definir ou herdar o evento anexado, e nem o objeto que potencialmente lança o evento nem a instância destino de tratamento devem definir ou "ser donos" desse evento como um membro da classe.

O sistema de entrada do WPF usa eventos anexados amplamente. No entanto, quase todos esses eventos anexados são encaminhados através de elementos base. Os eventos de entrada aparecem como eventos roteados não conectados equivalentes que são membros da classe base de um elemento. Por exemplo, o evento anexado Mouse.MouseDown subjacente pode mais facilmente ser tratado em qualquer UIElement usando-se MouseDown no UIElement ao invés de lidar com a sintaxe de evento anexado em XAML ou em código.

Para obter mais informações sobre eventos anexados no WPF, consulte Visão geral sobre eventos anexados.

Outro uso de sintaxe que se assemelha a sintaxe de evento anexado NomeDoTipo.NomeDoEvento mas não é, estritamente falando, um uso de evento anexado se dá quando você anexa manipuladores para eventos roteados que são criados por elementos filho. Você anexa os manipuladores a um pai comum, para tirar proveito do roteamento de eventos, mesmo que o pai comum talvez não tenha o evento roteado relevante como membro. Considere esse exemplo novamente:

<Border Height="50" Width="300" BorderBrush="Gray" BorderThickness="1">
  <StackPanel Background="LightGray" Orientation="Horizontal" Button.Click="CommonClickHandler">
    <Button Name="YesButton" Width="Auto" >Yes</Button>
    <Button Name="NoButton" Width="Auto" >No</Button>
    <Button Name="CancelButton" Width="Auto" >Cancel</Button>
  </StackPanel>
</Border>

Aqui, o ouvinte do elemento pai onde o manipulador é adicionado é um StackPanel. No entanto, ele está adicionando um manipulador para um evento roteado que foi declarado e será gerado pela classe Button (ButtonBase na verdade, mas disponível para Button por meio de herança). O Button é "dono" do evento, mas o sistema de eventos roteados permite que manipuladores para qualquer evento roteado sejam anexados a quaisquer ouvintes de instância de UIElement ou ContentElement que poderiam, de outro modo, anexar ouvintes para um evento do common language runtime (CLR). O espaço de nomes xmlns padrão para esses nomes qualificados de atributos de eventos é normalmente o espaço de nomes xmlns padrão do WPF, mas você também pode especificar espaços de nomes prefixados para eventos roteados personalizados. Para obter mais informações sobre xmlns, consulte Espaços de nomes XAML e mapeamentos de espaços de nomes.

Uma aplicação freqüente de eventos roteados dentro da plataforma WPF é para eventos de entrada. Em WPF, eventos roteados de tunelamento são prefixados com a palavra "Preview" por convenção. Eventos de entrada geralmente vêm em pares, com um sendo um evento bolha e o outro sendo um evento por tunelamento. Por exemplo, o evento KeyDown e o evento PreviewKeyDown têm a mesma assinatura, com o primeiro sendo o evento de entrada bolha e o segundo sendo o evento de entrada por tunelamento. Ocasionalmente, eventos de entrada só tem uma versão bolha, ou talvez somente uma versão roteada direta. Na documentação, os tópicos sobre evento roteados fazem referências cruzadas a eventos roteados similares com estratégias alternativas de roteamento se tais eventos roteados existirem, e seções nas páginas sobre referências gerenciadas esclarecem a estratégia de roteamento de cada evento roteado.

Os eventos de entrada do WPF que vêm em pares são implementados de modo que uma única ação de entrada do usuário, como um pressionamento de botão do mouse, irá lançar os dois eventos roteados do par em sequência. Primeiro, o evento por tunelamento é gerado e viaja por sua rota. Em seguida, o evento bolha é gerado e viaja por sua rota. Os dois eventos literalmente compartilham a mesma instância dos dados do evento, pois a chamada de método RaiseEvent na implementação da classe que gera o evento bolha espera pelos dados de evento do evento por tunelamento e reutiliza-os no novo evento lançado. Ouvintes com manipuladores para o evento por tunelamento terão primeiro a oportunidade de marcar o evento roteado como tratado (manipuladores por classe em primeiro lugar, em seguida, manipuladores de instâncias). Se um elemento na rota de tunelamento marcou o evento roteado como tratado, os dados do evento já tratado são enviados para o evento bolha, e os manipuladores típicos anexados para o evento de entrada bolha equivalente não serão chamados. A impressão externa será como se o evento bolha tratado nem foi lançado. Esse comportamento de tratamento é útil para composição de um controle, onde você pode querer que todos os eventos de entrada baseados em teste de colisão ou baseados em foco sejam relatados para seu controle final, ao invés das partes da composição. O elemento controle final é o mais próximo da raiz na composição e, portanto, tem a oportunidade de tratar por classe o evento de tunelamento em primeiro lugar; e, talvez, "substituir" o evento roteado por um evento mais específico do controle, como parte do código que dá suporte a classe do controle.

De modo a ilustrar como o processamento de eventos de entrada funciona, considere o seguinte exemplo de evento de entrada. Na árvore mostrada a seguir, leaf element #2 é a origem de um evento PreviewMouseDown e, em seguida, de um evento MouseDown.

A ordem de processamento de eventos é a seguinte:

1. PreviewMouseDown (tunelamento) no elemento raiz.

2. PreviewMouseDown (tunelamento) no elemento intermediário nº 1.

3. PreviewMouseDown (tunelamento) no elemento origem nº 2.

4. MouseDown (bolha) no elemento origem nº 2.

5. MouseDown (bolha) no elemento intermediário nº 1.

6. MouseDown (bolha) no elemento raiz.

Um representante manipulador de eventos roteados fornece referências para dois objetos: o objeto que disparou o evento e o objeto onde o manipulador foi chamado. O objeto onde o manipulador foi invocado é o objeto relatado pelo parâmetro sender. O objeto onde o evento foi gerado pela primeira vez é reportado pela propriedade Source nos dados do evento. Um evento roteado pode ainda ser gerado e tratado pelo mesmo objeto. Nesse caso o sender e a Source serão idênticos (esse é o caso das etapas 3 e 4 no exemplo de processamento de eventos).

Devido ao tunelamento e ao comportamento de bolha, os elementos pai recebem eventos de entrada onde a Source é um de seus elementos filho. Quando for importante saber qual é o elemento de origem, você pode identificar o elemento de origem acessando a propriedade Source.

Geralmente, uma vez que o evento de entrada seja marcado como Handled, outros manipuladores não serão chamados. Normalmente, você deve marcar eventos de entrada como tratados, assim que um manipulador invocado atende sua lógica de tratamento específica do aplicativo com relação ao significado do evento de entrada.

A exceção a essa instrução geral sobre o estado Handled é que manipuladores de eventos de entrada que são registrados para ignorar deliberadamente o estado Handled dos dados do evento ainda poderiam ser chamados ao longo de qualquer uma das rotas. Para obter mais informações, consulte Visualização de Eventos ou Marcando Eventos Roteados como Manipulados e Manipulação de Classes.

O modelo de dados de evento compartilhado entre eventos tunelamento/bolha e o lançamento sequencial primeiro de eventos por tunelamento e, em seguida, de eventos bolha, não é um conceito geralmente verdadeiro para todos os eventos roteados. Esse comportamento é especificamente implementado por como dispositivos de entrada WPF escolhem lançar e conectar-se aos pares de evento de entrada. Implementar seus próprios eventos de entrada é um cenário avançado, mas você também pode escolher seguir esse modelo para seus próprios eventos de entrada.

Determinadas classes escolhem manipular por classe certos eventos de entrada, geralmente com a intenção de redefinir o que significa um determinado evento de entrada causado pelo usuário dentro desse controle específico e gerar um novo evento. Para obter mais informações, consulte Marcando Eventos Roteados como Manipulados e Manipulação de Classes.

Para obter mais informações sobre entrada e como entrada e eventos interagem em cenários típicos de aplicativos, consulte Input Overview.

Em estilos, você pode incluir alguma sintaxe XAML pré-delcarada de tratamento de eventos na marcação usando um EventSetter. Quando o estilo é aplicado, o manipulador referenciado é adicionado à instância estilizada. Você pode declarar um EventSetter somente para um evento roteado. The following is an example. Observe que o método b1SetColor referenciado aqui está em um arquivo de código por trás da marcação.

<StackPanel
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  x:Class="SDKSample.EventOvw2"
  Name="dpanel2"
  Initialized="PrimeHandledToo"
>
  <StackPanel.Resources>
    <Style TargetType="{x:Type Button}">
      <EventSetter Event="Click" Handler="b1SetColor"/>
    </Style>
  </StackPanel.Resources>
  <Button>Click me</Button>
  <Button Name="ThisButton" Click="HandleThis">
    Raise event, handle it, use handled=true handler to get it anyway.
  </Button>
</StackPanel>

A vantagem ganha aqui é que o estilo provavelmente contêm uma grande quantidade de outras informações que podem aplicar-se a qualquer botão em seu aplicativo, e ter o EventSetter fazendo parte desse estilo promove a reutilização de código mesmo no nível de marcação. Além disso, um EventSetter abstrai os nomes dos método para os manipuladores criando um nível a mais de distância do aplicativo e da página em linguagem de marcação.

Outra sintaxe especializada que combina os recursos do WPF de eventos roteados e de animação é um EventTrigger. sistema autônomo ocorre com EventSetter, eventos roteados só podem ser usados para um EventTrigger. Normalmente, um EventTrigger é declarada sistema autônomo parte de um estilo, mas um EventTrigger também pode ser declarada em elementos de nível de página sistema autônomo parte do Triggers coleção, ou em um ControlTemplate. Um EventTrigger permite que você especifique um Storyboard que é executado sempre que um evento roteado atinge um elemento na respectiva rota declara um EventTrigger para esse evento. A vantagem de um EventTrigger sobre a manipulação simples de um evento e fazendo com que ele inicie um storyboard existente é que um EventTrigger fornece maior controle sobre o storyboard e seu comportamento de execução. Para obter mais informações, consulte Como: Usar acionadores de eventos para controlar um Storyboard após seu início.

Este tópico aborda principalmente eventos roteados a partir da perspectiva de descrever os conceitos básicos e oferecer orientação sobre como e quando responder a eventos roteados que já estão presentes nos vários elementos base e controles. No entanto, você pode criar seu próprio evento roteado em sua classe personalizada juntamente com todo o suporte necessário, tal como classes especializadas de dados de eventos e delegados. Qualquer classe pode ser proprietária de um evento roteado, mas eventos roteados devem ser gerados e tratados por uma classe derivada de UIElement ou de ContentElementpara ser útil. Para obter mais informações sobre eventos personalizados, consulte Como: Criar um evento roteado personalizado.

Conceitos

Referência