Eventos (Visual Basic)Events (Visual Basic)

Embora você possa visualizar um projeto do Visual Studio como uma série de procedimentos executados em uma sequência, na realidade, a maioria dos programas são controlados por eventos, o que significa que o fluxo de execução é determinado por ocorrências externas chamadas de eventos.While you might visualize a Visual Studio project as a series of procedures that execute in a sequence, in reality, most programs are event driven—meaning the flow of execution is determined by external occurrences called events.

Um evento é um sinal que informa a um aplicativo que algo importante ocorreu.An event is a signal that informs an application that something important has occurred. 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.For example, when a user clicks a control on a form, the form can raise a Click event and call a procedure that handles the event. Os eventos também permitem que tarefas separadas se comuniquem.Events also allow separate tasks to communicate. Por exemplo, digamos que seu aplicativo executa uma tarefa de classificação separadamente do aplicativo principal.Say, for example, that your application performs a sort task separately from the main application. Se um usuário cancelar a classificação, seu aplicativo poderá enviar um evento de cancelamento instruindo o processo de classificação para parar.If a user cancels the sort, your application can send a cancel event instructing the sort process to stop.

Conceitos e termos de eventoEvent Terms and Concepts

Esta seção descreve os termos e conceitos usados com eventos no Visual Basic.This section describes the terms and concepts used with events in Visual Basic.

Declarando eventosDeclaring Events

Você declara eventos dentro de classes, estruturas, módulos e interfaces usando a palavra-chave Event, como no exemplo a seguir:You declare events within classes, structures, modules, and interfaces using the Event keyword, as in the following example:

Event AnEvent(ByVal EventNumber As Integer)

Acionar eventosRaising Events

Um evento é como uma mensagem anunciando que algo importante ocorreu.An event is like a message announcing that something important has occurred. O ato de transmitir a mensagem é chamado para acionar o evento.The act of broadcasting the message is called raising the event. No Visual Basic, você gera eventos com a RaiseEvent instrução, como no exemplo a seguir:In Visual Basic, you raise events with the RaiseEvent statement, as in the following example:

RaiseEvent AnEvent(EventNumber)

Os eventos devem ser acionados dentro do escopo da classe, módulo ou estrutura na qual eles são declarados.Events must be raised within the scope of the class, module, or structure where they are declared. Por exemplo, uma classe derivada não pode acionar eventos herdados de uma classe base.For example, a derived class cannot raise events inherited from a base class.

Remetentes do eventoEvent Senders

Qualquer objeto capaz de acionar um evento é um remetente do evento, também conhecido como uma origem do evento.Any object capable of raising an event is an event sender, also known as an event source. Formulários, controles e objetos definidos pelo usuário são exemplos de remetentes de eventos.Forms, controls, and user-defined objects are examples of event senders.

Manipuladores de eventosEvent Handlers

Manipuladores de eventos são procedimentos que são chamados quando ocorre um evento correspondente.Event handlers are procedures that are called when a corresponding event occurs. Você pode usar qualquer sub-rotina válida com uma assinatura correspondente como um manipulador de eventos.You can use any valid subroutine with a matching signature as an event handler. 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.You cannot use a function as an event handler, however, because it cannot return a value to the event source.

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.Visual Basic uses a standard naming convention for event handlers that combines the name of the event sender, an underscore, and the name of the event. Por exemplo, o evento Click de um botão chamado button1 seria nomeado Sub button1_Click.For example, the Click event of a button named button1 would be named 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.We recommend that you use this naming convention when defining event handlers for your own events, but it is not required; you can use any valid subroutine name.

Associar eventos a manipuladores de eventosAssociating Events with Event Handlers

Antes de um manipulador de eventos se tornar útil, você deve primeiro associá-lo a um evento usando a instrução Handles ou AddHandler.Before an event handler becomes usable, you must first associate it with an event by using either the Handles or AddHandler statement.

WithEvents e a cláusula HandlesWithEvents and the Handles Clause

A instrução WithEvents e a cláusula Handles fornecem uma maneira declarativa de especificar os manipuladores de eventos.The WithEvents statement and Handles clause provide a declarative way of specifying event handlers. 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:An event raised by an object declared with the WithEvents keyword can be handled by any procedure with a Handles statement for that event, as shown in the following example:

' 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.The WithEvents statement and the Handles clause are often the best choice for event handlers because the declarative syntax they use makes event handling easier to code, read and debug. No entanto, esteja ciente das seguintes limitações no uso de variáveis WithEvents:However, be aware of the following limitations on the use of WithEvents variables:

  • Não é possível usar uma variável WithEvents como uma variável de objeto.You cannot use a WithEvents variable as an object variable. Ou seja, você não pode declará-la como Object— você deve especificar o nome da classe quando declarar a variável.That is, you cannot declare it as Object—you must specify the class name when you declare the variable.

  • Como os eventos compartilhados não estão vinculados a instâncias de classe, você não pode usar o WithEvents para manipular eventos compartilhados de forma declarativa.Because shared events are not tied to class instances, you cannot use WithEvents to declaratively handle shared events. Da mesma forma, você não pode usar WithEvents ou Handles para manipular eventos de um Structure.Similarly, you cannot use WithEvents or Handles to handle events from a Structure. Em ambos os casos, você pode usar a instrução AddHandler para manipular esses eventos.In both cases, you can use the AddHandler statement to handle those events.

  • Não é possível criar matrizes de variáveis WithEvents.You cannot create arrays of WithEvents variables.

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.WithEvents variables allow a single event handler to handle one or more kind of event, or one or more event handlers to handle the same kind of event.

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.Although the Handles clause is the standard way of associating an event with an event handler, it is limited to associating events with event handlers at compile time.

Em alguns casos, como com eventos associados a formulários ou controles, Visual Basic stubs automaticamente de um manipulador de eventos vazio e o associa a um evento.In some cases, such as with events associated with forms or controls, Visual Basic automatically stubs out an empty event handler and associates it with an event. Por exemplo, quando você clica duas vezes em um botão de comando em um formulário no modo de design, Visual Basic cria um manipulador de eventos vazio e uma WithEvents variável para o botão de comando, como no código a seguir:For example, when you double-click a command button on a form in design mode, Visual Basic creates an empty event handler and a WithEvents variable for the command button, as in the following code:

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

AddHandler e RemoveHandlerAddHandler and RemoveHandler

A instrução AddHandler é semelhante à cláusula Handles, pois ambas permitem que você especifique um manipulador de eventos.The AddHandler statement is similar to the Handles clause in that both allow you to specify an event handler. 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.However, AddHandler, used with RemoveHandler, provides greater flexibility than the Handles clause, allowing you to dynamically add, remove, and change the event handler associated with an event. Se quiser manipular eventos compartilhados ou eventos de uma estrutura, você deverá usar AddHandler.If you want to handle shared events or events from a structure, you must use 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.AddHandler takes two arguments: the name of an event from an event sender such as a control, and an expression that evaluates to a delegate. Você não precisa especificar explicitamente a classe delegado ao usar AddHandler, pois a instrução AddressOf sempre retorna uma referência ao delegado.You do not need to explicitly specify the delegate class when using AddHandler, since the AddressOf statement always returns a reference to the delegate. O exemplo a seguir associa um manipulador de eventos a um evento acionado por um objeto:The following example associates an event handler with an event raised by an object:

AddHandler Obj.XEvent, AddressOf Me.XEventHandler

RemoveHandler, que desconecta um evento de um manipulador de eventos, usa a mesma sintaxe que AddHandler.RemoveHandler, which disconnects an event from an event handler, uses the same syntax as AddHandler. Por exemplo:For example:

RemoveHandler Obj.XEvent, AddressOf Me.XEventHandler

No exemplo a seguir, um manipulador de eventos é associado a um evento e o evento é acionado.In the following example, an event handler is associated with an event, and the event is raised. O manipulador de evento captura o evento e exibe uma mensagem.The event handler catches the event and displays a message.

Em seguida, o primeiro manipulador de eventos é removido e um manipulador de eventos diferente é associado ao evento.Then the first event handler is removed and a different event handler is associated with the event. Quando o evento for acionado novamente, será exibida uma mensagem diferente.When the event is raised again, a different message is displayed.

Por fim, o segundo manipulador de eventos é removido e o evento é acionado pela terceira vez.Finally, the second event handler is removed and the event is raised for a third time. Como não há um manipulador de eventos associado ao evento, nenhuma ação será tomada.Because there is no longer an event handler associated with the event, no action is taken.

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 baseHandling Events Inherited from a Base Class

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.Derived classes—classes that inherit characteristics from a base class—can handle events raised by their base class using the Handles MyBase statement.

Como manipular eventos de uma classe baseTo handle events from a base class

  • 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.Declare an event handler in the derived class by adding a Handles MyBase.eventname statement to the declaration line of your event-handler procedure, where eventname is the name of the event in the base class you are handling. Por exemplo:For example:

    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
    
TítuloTitle DescriçãoDescription
Instruções passo a passo: declarando e acionando eventosWalkthrough: Declaring and Raising Events Fornece uma descrição passo a passo de como declarar e acionar eventos para uma classe.Provides a step-by-step description of how to declare and raise events for a class.
Instruções passo a passo: tratando eventosWalkthrough: Handling Events Demonstra como escrever um procedimento de manipulador de eventos.Demonstrates how to write an event-handler procedure.
Como declarar eventos personalizados para evitar bloqueioHow to: Declare Custom Events To Avoid Blocking Demonstra como definir um evento personalizado que permite que seus manipuladores de eventos sejam chamados assincronicamente.Demonstrates how to define a custom event that allows its event handlers to be called asynchronously.
Como declarar eventos personalizados para conservar memóriaHow to: Declare Custom Events To Conserve Memory Demonstra como definir um evento personalizado que utiliza memória somente quando o evento é manipulado.Demonstrates how to define a custom event that uses memory only when the event is handled.
Solucionando problemas de manipuladores de eventos herdados no Visual BasicTroubleshooting Inherited Event Handlers in Visual Basic Lista problemas comuns que ocorrem com os manipuladores de eventos em componentes herdados.Lists common issues that arise with event handlers in inherited components.
EventosEvents Apresenta uma visão geral do modelo de evento no .NET Framework.Provides an overview of the event model in the .NET Framework.
Criando manipuladores de eventos no Windows FormsCreating Event Handlers in Windows Forms Descreve como trabalhar com eventos associados aos objetos do Windows Forms.Describes how to work with events associated with Windows Forms objects.
RepresentantesDelegates Fornece uma visão geral de delegados no Visual Basic.Provides an overview of delegates in Visual Basic.