Partilhar via

Tratamento de eventos do Visual Basic e WPF (WPF .NET)

  • Artigo

Se você estiver codificando no .NET do Visual Basic, poderá usar a palavra-chave Handles específica do idioma para anexar um manipulador de eventos a um objeto. O objeto pode ser uma instância em code-behind ou um elemento em XAML (Extensible Application Markup Language). Handles pode ser usado para atribuir manipuladores de eventos para eventos do CLR (Common Language Runtime) ou eventos roteados do WPF (Windows Presentation Foundation). No entanto, Handles tem algumas limitações de uso quando usado para anexar manipuladores de eventos para eventos roteados.

Pré-requisitos

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

Sintaxe

A sintaxe de uma declaração Sub que usa a palavra-chave Handles é: Sub <procedure name> Handles <object name>.<event name>. Essa sintaxe designa um procedimento como o manipulador de eventos que será executado quando um evento especificado por <event name> for gerado em um objeto especificado por <object name>. O evento deve ser um membro da classe ou classe base do objeto. O exemplo a seguir mostra como anexar um manipulador de eventos a um elemento XAML usando Handles.

' Click event handler attached to XamlButton using Handles.
Private Sub XamlButton_Click(sender As Object, e As RoutedEventArgs) Handles XamlButton.Click

    ' Handler logic.
    Debug.WriteLine($"Click event handler attached to XamlButton using Handles.")

End Sub

Para usar Handles com um objeto definido em code-behind, normalmente você declara o objeto usando a palavra-chave WithEvents. Para obter mais informações sobre o uso de WithEvents, consulte esses exemplos . O WPF declara automaticamente todos os elementos XAML usando Friend WithEvents. O exemplo a seguir mostra como declarar um objeto definido em code-behind usando WithEvents.

' Declare a new button using WithEvents.
Dim WithEvents CodeButton As New Button With {
    .Content = "New button",
    .Background = Brushes.Yellow
}

' Click event handler attached to CodeButton using Handles.
Private Sub CodeButton_Click(sender As Object, e As RoutedEventArgs) Handles CodeButton.Click

    ' Handler logic.
    Debug.WriteLine($"Click event handler attached to CodeButton using Handles.")

End Sub

Para usar o mesmo manipulador para vários eventos, separe por vírgula os eventos <object name>.<event name>. Por exemplo, Sub Button_Click(sender As Object, e As RoutedEventArgs) Handles Button1.Click, Button2.Click. A ordem dos eventos separados por vírgula é imaterial.

Você pode atribuir manipuladores diferentes para o mesmo evento com várias instruções Handles. A ordem das instruções Handles não determina a ordem na qual os manipuladores são invocados quando o evento ocorre.

Dica

Para remover um manipulador que foi adicionado com Handles, chame RemoveHandler. Por exemplo, RemoveHandler Button1.Click, AddressOf Button1_Click.

Usando 'Handles' em um aplicativo WPF

Para um objeto definido em XAML, a sintaxe <object name>.<event name> do evento Handles requer que o elemento XAML que representa o objeto tenha uma propriedade Name ou x:Name. No entanto, uma propriedade de nome não é necessária para o elemento raiz da página XAML, para o qual você pode usar o nome Me. O exemplo a seguir mostra como anexar um manipulador de eventos a uma raiz de página XAML usando Handles.

' Loaded event handler attached to the XAML page root using Handles.
Private Sub Window_Loaded(sender As Object, e As RoutedEventArgs) Handles Me.Loaded

    ' Handler logic.
    Debug.WriteLine($"Loaded event handler attached to Window using Handles.")

End Sub

Quando uma página XAML é compilada, cada elemento XAML com um parâmetro Name ou x:Name é declarado como Friend WithEvents. Como resultado, você pode usar qualquer elemento XAML com Handles.

Dica

O Visual Studio IntelliSense mostra os objetos que podem ser usados com Handles.

Independentemente de você anexar um manipulador de eventos usando , sintaxe de atributo XAML, a instrução AddHandler ou o método , o comportamento do sistema de eventos é o mesmo.

Nota

Não use atributos XAML e Handles para anexar o mesmo manipulador de eventos ao mesmo evento, caso contrário, o manipulador de eventos será chamado duas vezes para cada evento.

Limitações

A palavra-chave Handles tem estas limitações de uso:

  • Você só pode usar Handles para anexar um manipulador de eventos a um objeto se o evento for um membro da classe ou classe base do objeto. Por exemplo, você pode usar Handles para anexar um manipulador de eventos Click a um botão cuja classe base ButtonBase aciona o evento roteado Click. No entanto, um dos recursos de eventos roteados é que eles atravessam a árvore de elementos, o que possibilita escutar e manipular um evento Click em um nível mais alto do que o elemento que o gerou. Um evento roteado que um elemento pai escuta e manipula é chamado de evento anexado. Handles não pode ser usado para eventos anexados porque sua sintaxe não dá suporte à especificação de um ouvinte diferente na árvore de elementos XAML do que o elemento que gerou o evento. Para atribuir manipuladores de eventos para eventos anexados, você precisará usar a sintaxe do atributo XAML ou o método AddHandler. Para mais informações sobre eventos anexados, consulte Visão Geral de Eventos Anexados e Eventos Anexados no WPF.

  • A sintaxe Handles não suporta chamar o manipulador de eventos para eventos Handled. Para permitir que o manipulador de eventos seja invocado para eventos Handled, anexe o manipulador de eventos usando o método AddHandler(RoutedEvent, Delegate, Boolean) e defina seu parâmetro handledEventsToo como true.

Consulte também