Compartilhar via

Visão geral de eventos anexados

XAML (Extensible Application Markup Language) define um componente de linguagem e um tipo de evento chamado um evento anexado. Eventos anexados podem ser usados para definir um novo evento roteado em uma classe não-elemento e gerar esse evento em qualquer elemento em sua árvore. Para fazer isso, você deve registrar o evento anexado como um evento roteado e fornecer um código de backup específico que dê suporte à funcionalidade de evento anexado. Como os eventos anexados são registrados como eventos roteados, quando gerados em um elemento, eles se propagam pela árvore de elementos.

Pré-requisitos

O artigo pressupõe um conhecimento básico dos eventos roteados do Windows Presentation Foundation (WPF) e que você leu visão geral de eventos roteados e XAML no WPF. Para seguir os exemplos neste artigo, ele ajuda se você estiver familiarizado com XAML e saber como escrever aplicativos WPF.

Sintaxe de evento anexada

Na sintaxe XAML, um evento anexado é especificado pelo nome do evento e seu tipo de proprietário, na forma de <owner type>.<event name>. Como o nome do evento é qualificado com o nome de seu tipo de proprietário, a sintaxe permite que o evento seja anexado a qualquer elemento que possa ser instanciado. Essa sintaxe também é aplicável aos manipuladores de eventos roteados regulares que são anexados a um elemento arbitrário ao longo da rota do evento.

A seguinte sintaxe de atributo XAML anexa o manipulador AquariumFilter_Clean ao evento anexado AquariumFilter.Clean no elemento aquarium1.

<aqua:Aquarium x:Name="aquarium1" Height="300" Width="400" aqua:AquariumFilter.Clean="AquariumFilter_Clean"/>

Neste exemplo, o prefixo aqua: é necessário porque as classes AquariumFilter e Aquarium existem em um namespace e assembly CLR (Common Language Runtime) diferente.

Você também pode anexar manipuladores para eventos anexados no code behind. Para fazer isso, chame o método AddHandler no objeto ao qual o manipulador deve ser anexado, passando o identificador de evento e o manipulador como parâmetros para o método.

Como o WPF implementa eventos anexados

Os eventos anexados do WPF são implementados como eventos roteados apoiados por um RoutedEvent campo. Como resultado, os eventos anexados se propagam pela árvore de elementos após serem levantados. Geralmente, o objeto que gera o evento anexado, conhecido como a origem do evento, é uma fonte de serviço ou sistema. As fontes de sistema ou serviço não são uma parte direta da árvore de elementos. Para outros eventos anexados, a origem do evento pode ser um elemento na árvore, como um componente dentro de um controle composto.

Cenários de eventos anexados

No WPF, os eventos anexados são usados em determinadas áreas de recursos em que há uma abstração no nível do serviço. Por exemplo, o WPF usa eventos anexados habilitados pelas classes ou Mouse estáticasValidation. Classes que interagem com ou usam um serviço podem interagir com um evento usando a sintaxe de evento anexada ou exibir o evento anexado como um evento roteado. A última opção faz parte de como uma classe pode integrar os recursos do serviço.

O sistema de entrada do WPF usa eventos anexados extensivamente. No entanto, quase todos esses eventos anexados são exibidos como eventos roteados não anexados equivalentes por meio de elementos base. Cada evento de entrada roteado é um membro da classe de elemento base e é suportado por um evento CLR "wrapper". Você raramente usará ou manipulará eventos anexados diretamente. Por exemplo, é mais fácil lidar com o evento anexado subjacente em um Mouse.MouseDown evento roteado UIElement equivalente UIElement.MouseDown do que usando a sintaxe de evento anexada em XAML ou code-behind.

Os eventos anexados servem a uma finalidade de arquitetura habilitando a expansão futura de dispositivos de entrada. Por exemplo, um novo dispositivo de entrada só precisaria ser gerado Mouse.MouseDown para simular a entrada do mouse e ele não precisaria derivar para Mouse fazer isso. Esse cenário envolve o tratamento de código do evento, uma vez que o tratamento XAML do evento anexado não seria relevante.

Manipular um evento anexado

O processo de codificação e manipulação de um evento anexado é basicamente o mesmo de um evento roteado não anexado.

Conforme observado anteriormente, os eventos anexados do WPF existentes normalmente não se destinam a serem tratados diretamente no WPF. Com mais frequência, a finalidade de um evento anexado é habilitar um elemento dentro de um controle composto para relatar seu estado a um elemento pai dentro do controle. Nesse cenário, o evento é gerado em código e depende do manejo da classe na respectiva classe pai. Por exemplo, espera-se que os itens dentro de um Selector acionem o evento anexado Selected, que é então tratado pela classe Selector. A Selector classe tem o potencial de converter o Selected evento no SelectionChanged evento roteado. Para obter mais informações sobre eventos roteado e manipulação de classe, consulte Marcando eventos roteado como manipulados e manipulação de classe.

Definir um evento anexado personalizado

Se você estiver derivando de classes base comuns do WPF, poderá implementar seu evento anexado personalizado incluindo dois métodos acessadores em sua classe. Esses métodos são:

  • Um método Add<event name>Handler , com um primeiro parâmetro que é o elemento no qual o manipulador de eventos está anexado e um segundo parâmetro que é o manipulador de eventos a ser adicionado. O método deve ser public e static, sem valor retornado. O método chama o AddHandler método de classe base, passando o evento roteado e o manipulador como argumentos. Esse método dá suporte à sintaxe do atributo XAML para anexar um manipulador de eventos a um elemento. Esse método também habilita o acesso de código ao repositório de manipuladores de eventos para o evento anexado.

  • Um método Remove<event name>Handler , com um primeiro parâmetro que é o elemento no qual o manipulador de eventos está anexado e um segundo parâmetro que é o manipulador de eventos a ser removido. O método deve ser public e static, sem valor retornado. O método chama o RemoveHandler método de classe base, passando o evento roteado e o manipulador como argumentos. Esse método permite o acesso de código ao repositório do manipulador de eventos para o evento anexado.

O WPF implementa eventos anexados como eventos roteados porque o identificador de um RoutedEvent é definido pelo sistema de eventos do WPF. Além disso, o roteamento de um evento é uma extensão natural do conceito em nível de linguagem XAML de um evento anexado. Essa estratégia de implementação limita o tratamento de eventos anexados apenas a classes derivadas de UIElement ou ContentElement, pois somente essas classes possuem implementações de AddHandler.

Por exemplo, o código a seguir define o Clean evento anexado na AquariumFilter classe de proprietário, que não é uma classe de elemento. O código define o evento anexado como um evento roteado e implementa os métodos de acessador necessários.

public class AquariumFilter
{
    // Register a custom routed event using the bubble routing strategy.
    public static readonly RoutedEvent CleanEvent = EventManager.RegisterRoutedEvent(
        "Clean", RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(AquariumFilter));

    // Provide an add handler accessor method for the Clean event.
    public static void AddCleanHandler(DependencyObject dependencyObject, RoutedEventHandler handler)
    {
        if (dependencyObject is not UIElement uiElement)
            return;

        uiElement.AddHandler(CleanEvent, handler);
    }

    // Provide a remove handler accessor method for the Clean event.
    public static void RemoveCleanHandler(DependencyObject dependencyObject, RoutedEventHandler handler)
    {
        if (dependencyObject is not UIElement uiElement)
            return;

        uiElement.RemoveHandler(CleanEvent, handler);
    }
}

Public Class AquariumFilter

    ' Register a custom routed event using the bubble routing strategy.
    Public Shared ReadOnly CleanEvent As RoutedEvent = EventManager.RegisterRoutedEvent(
        "Clean", RoutingStrategy.Bubble, GetType(RoutedEventHandler), GetType(AquariumFilter))

    ' Provide an add handler accessor method for the Clean event.
    Public Shared Sub AddCleanHandler(dependencyObject As DependencyObject, handler As RoutedEventHandler)
        Dim uiElement As UIElement = TryCast(dependencyObject, UIElement)

        If uiElement IsNot Nothing Then
            uiElement.[AddHandler](CleanEvent, handler)
        End If
    End Sub

    ' Provide a remove handler accessor method for the Clean event.
    Public Shared Sub RemoveCleanHandler(dependencyObject As DependencyObject, handler As RoutedEventHandler)
        Dim uiElement As UIElement = TryCast(dependencyObject, UIElement)

        If uiElement IsNot Nothing Then
            uiElement.[RemoveHandler](CleanEvent, handler)
        End If
    End Sub

End Class

O RegisterRoutedEvent método que retorna o identificador de evento anexado é o mesmo método usado para registrar eventos roteados não anexados. Eventos roteáveis anexados e não anexados são registrados em um repositório centralizado interno. Essa implementação do repositório de eventos permite o conceito de "eventos como uma interface" discutido na visão geral de eventos roteados.

Ao contrário do evento CLR "wrapper" usado para retornar eventos roteados não anexados, os métodos do acessador de eventos anexados podem ser implementados em classes que não derivam de UIElement ou ContentElement. Isso é possível porque o código de apoio de evento anexado chama os métodos UIElement.AddHandler e UIElement.RemoveHandler em uma instância UIElement passada. Por outro lado, o wrapper CLR para eventos roteados não anexados chama esses métodos diretamente na classe proprietária, de modo que a classe deve derivar de UIElement.

Gerar um evento anexado do WPF

O processo para gerar um evento anexado é essencialmente o mesmo que para um evento roteado não anexado.

Normalmente, seu código não precisará gerar eventos anexados definidos pelo WPF existentes, pois esses eventos seguem o modelo conceitual geral de "serviço". Nesse modelo, classes de serviço, como InputManager, são responsáveis por gerar eventos anexados definidos pelo WPF.

Ao definir um evento anexado personalizado usando o modelo WPF de basear eventos anexados em eventos roteados, use o UIElement.RaiseEvent método para gerar um evento anexado em qualquer UIElement ou ContentElement. Ao gerar um evento roteado, seja ele anexado ou não, você precisará designar um elemento na árvore de elementos como a origem do evento. Essa origem é então informada como o RaiseEvent chamador. Por exemplo, para gerar o AquariumFilter.Clean evento roteado anexado em aquarium1:

aquarium1.RaiseEvent(new RoutedEventArgs(AquariumFilter.CleanEvent));

aquarium1.[RaiseEvent](New RoutedEventArgs(AquariumFilter.CleanEvent))

No exemplo anterior, aquarium1 está a origem do evento.

Consulte também

  • Last updated on