Eventos (Visual Basic)

Embora você possa visualizar um projeto do Visual Studio como uma série de procedimentos que são executados em uma sequência, na realidade, a maioria dos programas é controlada por eventos, o que significa que o fluxo de execução é determinado por ocorrências externas chamadas de eventos.

Um evento é um sinal que informa a um aplicativo que algo importante ocorreu. Por exemplo, quando um usuário clica em um controle em um formulário, o formulário pode gerar um Click evento e chamar um procedimento que manipula o evento. Os eventos também permitem que tarefas separadas se comuniquem. Digamos, por exemplo, que seu aplicativo executa uma tarefa de classificação separadamente do aplicativo principal. Se um usuário cancelar a classificação, seu aplicativo poderá enviar um evento de cancelamento instruindo o processo de classificação a ser interrompido.

Termos e conceitos do evento

Esta seção descreve os termos e conceitos usados com eventos no Visual Basic.

Declarando eventos

Você declara eventos dentro de classes, estruturas, módulos e interfaces usando a Event palavra-chave, como no exemplo a seguir:

Event AnEvent(ByVal EventNumber As Integer)

Acionar eventos

Um evento é como uma mensagem anunciando que algo importante ocorreu. O ato de transmitir a mensagem é chamado para acionar o evento. No Visual Basic, você gera eventos com a instrução RaiseEvent , como no exemplo a seguir:

RaiseEvent AnEvent(EventNumber)

Os eventos devem ser gerados dentro do escopo da classe, módulo ou estrutura em que são declarados. Por exemplo, uma classe derivada não pode gerar eventos herdados de uma classe base.

Remetentes do evento

Qualquer objeto capaz de gerar um evento é um remetente de evento, também conhecido como uma fonte de evento. Formulários, controles e objetos definidos pelo usuário são exemplos de remetentes de eventos.

Manipuladores de Eventos

Manipuladores de eventos são procedimentos que são chamados quando ocorre um evento correspondente. Você pode usar qualquer sub-rotina válida com uma assinatura correspondente como um manipulador de eventos. No entanto, não é possível usar uma função como manipulador de eventos, pois ela não pode retornar um valor para a origem do evento.

O Visual Basic usa uma convenção de nomenclatura padrão para manipuladores de eventos que combina o nome do remetente do evento, um sublinhado e o nome do evento. Por exemplo, o Click evento de um botão nomeado button1 seria nomeado Sub button1_Click.

Observação

Recomendamos que você use essa convenção de nomenclatura ao definir manipuladores de eventos para seus próprios eventos, mas isso não é necessário; você pode usar qualquer nome de sub-rotina válido.

Associar eventos a manipuladores de eventos

Antes que um manipulador de eventos se torne utilizável, primeiro você deve associá-lo a um evento usando a instrução Handles ou a instrução AddHandler.

WithEvents e a cláusula Handles

A declaração WithEvents e a cláusula Handles fornecem uma maneira declarativa de especificar manipuladores de eventos. Um evento gerado por um objeto declarado com a WithEvents palavra-chave pode ser tratado por qualquer procedimento com uma Handles instrução para esse evento, conforme mostrado no exemplo a seguir:

' Declare a WithEvents variable.
Dim WithEvents EClass As New EventClass

' Call the method that raises the object's events.
Sub TestEvents()
    EClass.RaiseEvents()
End Sub

' Declare an event handler that handles multiple events.
Sub EClass_EventHandler() Handles EClass.XEvent, EClass.YEvent
    MsgBox("Received Event.")
End Sub

Class EventClass
    Public Event XEvent()
    Public Event YEvent()
    ' RaiseEvents raises both events.
    Sub RaiseEvents()
        RaiseEvent XEvent()
        RaiseEvent YEvent()
    End Sub
End Class

A WithEvents instrução e a Handles cláusula geralmente são a melhor opção para manipuladores de eventos, pois a sintaxe declarativa que eles usam facilita o tratamento de eventos para codificar, ler e depurar. No entanto, lembre-se das seguintes limitações sobre o uso de WithEvents variáveis:

• Você não pode usar uma WithEvents variável como uma variável de objeto. Ou seja, você não pode declará-lo como Object— você deve especificar o nome da classe ao declarar a variável.

• Como os eventos compartilhados não estão vinculados a instâncias de classe, você não pode usar WithEvents para lidar declarativamente com eventos compartilhados. Da mesma forma, você não pode usar WithEvents ou Handles para manipular eventos de um Structure. Em ambos os casos, você pode usar a AddHandler declaração para lidar com esses eventos.

• Você não pode criar matrizes de WithEvents variáveis.

WithEvents as variáveis permitem que um único manipulador de eventos manipule um ou mais tipos de evento ou um ou mais manipuladores de eventos para lidar com o mesmo tipo de evento.

Embora a Handles cláusula seja a maneira padrão de associar um evento a um manipulador de eventos, ela é limitada à associação de eventos com manipuladores de eventos em tempo de compilação.

Em alguns casos, como com eventos associados a formulários ou controles, o Visual Basic automaticamente descarta um manipulador de eventos vazio e o associa a um evento. Por exemplo, quando você clica duas vezes em um botão de comando em um formulário no modo de design, o Visual Basic cria um manipulador de eventos vazio e uma WithEvents variável para o botão de comando, como no seguinte código:

Friend WithEvents Button1 As System.Windows.Forms.Button
Protected Sub Button1_Click() Handles Button1.Click
End Sub

AddHandler e RemoveHandler

A AddHandler instrução é semelhante à Handles cláusula na qual ambos permitem que você especifique um manipulador de eventos. No entanto, AddHandler, usado com RemoveHandler, fornece maior flexibilidade do que a Handles cláusula, permitindo que você adicione, remova e altere dinamicamente o manipulador de eventos associado a um evento. Se você quiser lidar com eventos compartilhados ou eventos de uma estrutura, deverá usar AddHandler.

AddHandler leva dois argumentos: o nome de um evento de um remetente do evento, como um controle, e uma expressão que avalia um delegado. Você não precisa especificar explicitamente a classe delegada ao usar AddHandler, pois a AddressOf instrução sempre retorna uma referência ao delegado. O exemplo a seguir associa um manipulador de eventos a um evento gerado por um objeto:

AddHandler Obj.XEvent, AddressOf Me.XEventHandler

RemoveHandler, que desconecta um evento de um manipulador de eventos, usa a mesma sintaxe que AddHandler. Por exemplo:

RemoveHandler Obj.XEvent, AddressOf Me.XEventHandler

No exemplo a seguir, um manipulador de eventos é associado a um evento e o evento é gerado. O manipulador de eventos captura o evento e exibe uma mensagem.

Em seguida, o primeiro manipulador de eventos é removido e um manipulador de eventos diferente é associado ao evento. Quando o evento é gerado novamente, uma mensagem diferente é exibida.

Por fim, o segundo manipulador de eventos é removido e o evento é acionado pela terceira vez. Como não há mais um manipulador de eventos associado ao evento, nenhuma ação é tomada.

Module Module1

    Sub Main()
        Dim c1 As New Class1
        ' Associate an event handler with an event.
        AddHandler c1.AnEvent, AddressOf EventHandler1
        ' Call a method to raise the event.
        c1.CauseTheEvent()
        ' Stop handling the event.
        RemoveHandler c1.AnEvent, AddressOf EventHandler1
        ' Now associate a different event handler with the event.
        AddHandler c1.AnEvent, AddressOf EventHandler2
        ' Call a method to raise the event.
        c1.CauseTheEvent()
        ' Stop handling the event.
        RemoveHandler c1.AnEvent, AddressOf EventHandler2
        ' This event will not be handled.
        c1.CauseTheEvent()
    End Sub

    Sub EventHandler1()
        ' Handle the event.
        MsgBox("EventHandler1 caught event.")
    End Sub

    Sub EventHandler2()
        ' Handle the event.
        MsgBox("EventHandler2 caught event.")
    End Sub

    Public Class Class1
        ' Declare an event.
        Public Event AnEvent()
        Sub CauseTheEvent()
            ' Raise an event.
            RaiseEvent AnEvent()
        End Sub
    End Class

End Module

Manipulando eventos herdados de uma classe base

Classes derivadas — classes que herdam características de uma classe base — podem lidar com eventos gerados pela classe base usando a Handles MyBase instrução.

Para lidar com eventos de uma classe base

• Declare um manipulador de eventos na classe derivada adicionando uma declaração Handles MyBase.eventname à linha de declaração do procedimento do manipulador de eventos, onde eventname é o nome do evento na classe base que você está manipulando. Por exemplo:

  Public Class BaseClass
      Public Event BaseEvent(ByVal i As Integer)
      ' Place methods and properties here.
  End Class
  
  Public Class DerivedClass
      Inherits BaseClass
      Sub EventHandler(ByVal x As Integer) Handles MyBase.BaseEvent
          ' Place code to handle events from BaseClass here.
      End Sub
  End Class
  

Seções relacionadas

Título	Descrição
Instruções passo a passo: declarando e acionando eventos	Fornece uma descrição passo a passo de como declarar e gerar eventos para uma classe.
Passo a passo: manipulando eventos	Demonstra como escrever um procedimento de manipulador de eventos.
Como declarar eventos personalizados para evitar o bloqueio	Demonstra como definir um evento personalizado que permite que seus manipuladores de eventos sejam chamados de forma assíncrona.
Como declarar eventos personalizados para conservar memória	Demonstra como definir um evento personalizado que usa memória somente quando o evento é tratado.
Solução de problemas de manipuladores de eventos herdados no Visual Basic	Lista problemas comuns que surgem com manipuladores de eventos em componentes herdados.
Eventos	Fornece uma visão geral do modelo de evento no .NET Framework.
Criação de Manipuladores de Eventos no Windows Forms	Descreve como trabalhar com eventos associados a objetos do Windows Forms.
Representantes	Fornece uma visão geral dos delegados no Visual Basic.