Eventos (Visual Basic)

Enquanto você visualiza um projeto Visual Studio como uma série de procedimentos que executam em uma sequência, na realidade, a maioria dos programas é orientada a eventos, o que significa que o fluxo de execução é determinado pelas ocorrências externas chamadas 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 lançar um evento Click e chamar um procedimento que manipula o evento. Os eventos também permitem que tarefas separadas se comuniquem. Por exemplo, digamos 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 para parar.

Conceitos e termos de evento

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

Declarando eventos

Você declara eventos dentro de classes, estruturas, módulos e interfaces usando a palavra-chave Event, 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. Em Visual Basic, você aciona eventos com a instrução RaiseEvent, como no exemplo a seguir:

RaiseEvent AnEvent(EventNumber)

Os eventos devem ser acionados dentro do escopo da classe, módulo ou estrutura na qual eles são declarados. Por exemplo, uma classe derivada não pode acionar eventos herdados de uma classe base.

Remetentes do evento

Qualquer objeto capaz de acionar um evento é um remetente do evento, também conhecido como uma origem do 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. Você não pode usar uma função como um manipulador de eventos, porque ela não retorna um valor para a origem do evento.

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 evento Click de um botão chamado button1 seria nomeado Sub button1_Click.

Observação

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

Associar eventos a manipuladores de eventos

Antes de um manipulador de eventos se tornar útil, você deve primeiro associá-lo a um evento usando a instrução Handles ou AddHandler.

WithEvents e a cláusula Handles

A instrução WithEvents e a cláusula Handles fornecem uma maneira declarativa de especificar os manipuladores de eventos. Um evento gerado por um objeto declarado com a palavra-chave WithEvents pode ser tratado por qualquer procedimento com uma instrução Handles 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 instrução WithEvents e a cláusula Handles geralmente são a melhor opção para manipuladores de eventos, pois a sintaxe declarativa usada torna mais fácil a codificação, a leitura e a depuração para a manipulação de eventos. No entanto, esteja ciente das seguintes limitações no uso de variáveis WithEvents:

• Não é possível usar uma variável WithEvents como uma variável de objeto. Ou seja, você não pode declará-la como Object— você deve especificar o nome da classe quando declarar a variável.

• Como os eventos compartilhados não são ligados às instâncias de classe, você não pode usar WithEvents para manipular eventos compartilhados declarativamente. 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 instrução AddHandler para manipular esses eventos.

• Não é possível criar matrizes de variáveis WithEvents.

As variáveis WithEvents permitem que um único manipulador de eventos manipule um ou mais tipos de evento, ou que um ou mais manipuladores de eventos manipulem o mesmo tipo de evento.

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

Em alguns casos, como com os eventos associados a formulários ou controles, Visual Basic automaticamente extingue um manipulador de eventos vazio e o associa a um evento. Por exemplo, quando você clica duas vezes em um formulário no modo de design, Visual Basic cria um manipulador de eventos vazio e uma variável WithEvents 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 instrução AddHandler é semelhante à cláusula Handles, pois ambas permitem que você especifique um manipulador de eventos. No entanto, AddHandler, usado com RemoveHandler, fornece maior flexibilidade do que a cláusula Handles, permitindo que você adicione, remova e altere dinamicamente o manipulador de eventos associado a um evento. Se quiser manipular eventos compartilhados ou eventos de uma estrutura, você 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 delegado ao usar AddHandler, pois a instrução AddressOf sempre retorna uma referência ao delegado. O exemplo a seguir associa um manipulador de eventos a um evento acionado 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 é acionado. O manipulador de evento 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 for acionado novamente, será exibida uma mensagem diferente.

Por fim, o segundo manipulador de eventos é removido e o evento é acionado pela terceira vez. Como não há um manipulador de eventos associado ao evento, nenhuma ação será 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

Manipulação de eventos herdados de uma classe base

Classes derivadas — classes que herdam características de uma classe base e que podem manipular eventos acionados por suas classes base usando a instrução Handles MyBase.

Como manipular eventos de uma classe base

• Declare um manipulador de eventos na classe derivada adicionando uma instrução Handles MyBase.eventname à linha da declaração de seu procedimento do manipulador de eventos, no qual eventname é o nome do evento na classe base manipulada. 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 acionar eventos para uma classe.
Instruções passo a passo: tratando eventos	Demonstra como escrever um procedimento de manipulador de eventos.
Como declarar eventos personalizados para evitar bloqueio	Demonstra como definir um evento personalizado que permite que seus manipuladores de eventos sejam chamados assincronicamente.
Como declarar eventos personalizados para conservar memória	Demonstra como definir um evento personalizado que utiliza memória somente quando o evento é manipulado.
Solucionando problemas de manipuladores de eventos herdados no Visual Basic	Lista problemas comuns que ocorrem com os manipuladores de eventos em componentes herdados.
Eventos	Apresenta uma visão geral do modelo de evento no .NET Framework.
Criando manipuladores de eventos no Windows Forms	Descreve como trabalhar com eventos associados aos objetos do Windows Forms.
Representantes	Fornece uma visão geral de delegados no Visual Basic.