Instrução EventEvent Statement

Declara um evento definido pelo usuário.Declares a user-defined event.

SintaxeSyntax

[ <attrlist> ] [ accessmodifier ] _  
[ Shared ] [ Shadows ] Event eventname[(parameterlist)] _  
[ Implements implementslist ]  
' -or-  
[ <attrlist> ] [ accessmodifier ] _  
[ Shared ] [ Shadows ] Event eventname As delegatename _  
[ Implements implementslist ]  
' -or-  
 [ <attrlist> ] [ accessmodifier ] _  
[ Shared ] [ Shadows ] Custom Event eventname As delegatename _  
[ Implements implementslist ]  
   [ <attrlist> ] AddHandler(ByVal value As delegatename)  
      [ statements ]  
   End AddHandler  
   [ <attrlist> ] RemoveHandler(ByVal value As delegatename)  
      [ statements ]  
   End RemoveHandler  
   [ <attrlist> ] RaiseEvent(delegatesignature)  
      [ statements ]  
   End RaiseEvent  
End Event  

PartesParts

PartePart DescriçãoDescription
attrlist Opcional.Optional. Lista de atributos que se aplicam a este evento.List of attributes that apply to this event. Vários atributos são separados por vírgulas.Multiple attributes are separated by commas. Você deve colocar a lista de atributos entre colchetes angulares ("<" e ">").You must enclose the Attribute List in angle brackets ("<" and ">").
accessmodifier Opcional.Optional. Especifica qual código pode acessar o evento.Specifies what code can access the event. Pode ser um dos seguintes:Can be one of the following:

- público— qualquer código que possa acessar o elemento que o declara pode acessá-lo.- Public—any code that can access the element that declares it can access it.
- protegido— somente o código dentro de sua classe ou de uma classe derivada pode acessá-lo.- Protected—only code within its class or a derived class can access it.
- Friend— somente o código no mesmo assembly pode acessá-lo.- Friend—only code in the same assembly can access it.
- privado— somente o código no elemento que o declara pode acessá-lo.- Private—only code in the element that declares it can access it.
- código somente Friend-onlyprotegidona classe do evento, uma classe derivada ou o mesmo assembly pode acessá-lo.- Protected Friend-only code in the event's class, a derived class, or the same assembly can access it.
- código somenteprotegido privadona classe do evento ou em uma classe derivada no mesmo assembly pode acessá-lo.- Private Protected-only code in the event's class or a derived class in the same assembly can access it.
Shared Opcional.Optional. Especifica que esse evento não está associado a uma instância específica de uma classe ou estrutura.Specifies that this event is not associated with a specific instance of a class or structure.
Shadows Opcional.Optional. Indica que esse evento redeclara e oculta um elemento de programação de nome idêntico, ou conjunto de elementos sobrecarregados, em uma classe base.Indicates that this event redeclares and hides an identically named programming element, or set of overloaded elements, in a base class. Você pode sombrear qualquer tipo de elemento declarado com qualquer outro tipo.You can shadow any kind of declared element with any other kind.

Um elemento sombreado não está disponível de dentro da classe derivada que o sombreia, exceto de onde o elemento de sombreamento está inacessível.A shadowed element is unavailable from within the derived class that shadows it, except from where the shadowing element is inaccessible. Por exemplo, se um elemento Private sombreia um elemento de classe base, o código que não tem permissão para acessar o elemento Private acessa o elemento de classe base em vez disso.For example, if a Private element shadows a base-class element, code that does not have permission to access the Private element accesses the base-class element instead.
eventname Necessário.Required. Nome do evento; segue as convenções padrão de nomenclatura de variável.Name of the event; follows standard variable naming conventions.
parameterlist Opcional.Optional. Lista de variáveis locais que representam os parâmetros deste evento.List of local variables that represent the parameters of this event. Você deve colocar a lista de parâmetros entre parênteses.You must enclose the Parameter List in parentheses.
Implements Opcional.Optional. Indica que esse evento implementa um evento de uma interface.Indicates that this event implements an event of an interface.
implementslist Necessário se Implements for fornecido.Required if Implements is supplied. Lista de procedimentos de Sub que estão sendo implementados.List of Sub procedures being implemented. Vários procedimentos são separados por vírgulas:Multiple procedures are separated by commas:

implementedprocedure [, implementedprocedure ...]implementedprocedure [ , implementedprocedure ... ]

Cada implementedprocedure tem a seguinte sintaxe e partes:Each implementedprocedure has the following syntax and parts:

interface.definednameinterface.definedname

- interface-obrigatório.- interface - Required. Nome de uma interface que o procedimento que contém a classe ou a estrutura está implementando.Name of an interface that this procedure's containing class or structure is implementing.
- Definedname-obrigatório.- Definedname - Required. Nome pelo qual o procedimento é definido em interface.Name by which the procedure is defined in interface. Isso não precisa ser o mesmo que name, o nome que este procedimento está usando para implementar o procedimento definido.This does not have to be the same as name, the name that this procedure is using to implement the defined procedure.
Custom Necessário.Required. Eventos declarados como Custom devem definir acessadores AddHandler, RemoveHandler e RaiseEvent personalizados.Events declared as Custom must define custom AddHandler, RemoveHandler, and RaiseEvent accessors.
delegatename Opcional.Optional. O nome de um delegado que especifica a assinatura do manipulador de eventos.The name of a delegate that specifies the event-handler signature.
AddHandler Necessário.Required. Declara um acessador de AddHandler, que especifica as instruções a serem executadas quando um manipulador de eventos é adicionado, seja explicitamente usando a instrução AddHandler ou implicitamente usando a cláusula Handles.Declares an AddHandler accessor, which specifies the statements to execute when an event handler is added, either explicitly by using the AddHandler statement or implicitly by using the Handles clause.
End AddHandler Necessário.Required. Encerra o bloco de AddHandler.Terminates the AddHandler block.
value Necessário.Required. Nome do parâmetro.Parameter name.
RemoveHandler Necessário.Required. Declara um acessador RemoveHandler, que especifica as instruções a serem executadas quando um manipulador de eventos é removido usando a instrução RemoveHandler.Declares a RemoveHandler accessor, which specifies the statements to execute when an event handler is removed using the RemoveHandler statement.
End RemoveHandler Necessário.Required. Encerra o bloco de RemoveHandler.Terminates the RemoveHandler block.
RaiseEvent Necessário.Required. Declara um acessador RaiseEvent, que especifica as instruções a serem executadas quando o evento é gerado usando a instrução RaiseEvent.Declares a RaiseEvent accessor, which specifies the statements to execute when the event is raised using the RaiseEvent statement. Normalmente, isso invoca uma lista de delegados mantidos pelo AddHandler e RemoveHandler acessadores.Typically, this invokes a list of delegates maintained by the AddHandler and RemoveHandler accessors.
End RaiseEvent Necessário.Required. Encerra o bloco de RaiseEvent.Terminates the RaiseEvent block.
delegatesignature Necessário.Required. Lista de parâmetros que corresponde aos parâmetros exigidos pelo delegatename delegado.List of parameters that matches the parameters required by the delegatename delegate. Você deve colocar a lista de parâmetros entre parênteses.You must enclose the Parameter List in parentheses.
statements Opcional.Optional. Instruções que contêm os corpos dos métodos AddHandler, RemoveHandler e RaiseEvent.Statements that contain the bodies of the AddHandler, RemoveHandler, and RaiseEvent methods.
End Event Necessário.Required. Encerra o bloco de Event.Terminates the Event block.

ComentáriosRemarks

Depois que o evento tiver sido declarado, use a instrução RaiseEvent para gerar o evento.Once the event has been declared, use the RaiseEvent statement to raise the event. Um evento típico pode ser declarado e gerado conforme mostrado nos seguintes fragmentos:A typical event might be declared and raised as shown in the following fragments:

Public Class EventSource
    ' Declare an event.
    Public Event LogonCompleted(ByVal UserName As String)
    Sub CauseEvent()
        ' Raise an event on successful logon.
        RaiseEvent LogonCompleted("AustinSteele")
    End Sub
End Class

Observação

Você pode declarar argumentos de evento da mesma forma como faz argumentos de procedimentos, com as seguintes exceções: eventos não podem ter argumentos nomeados, argumentos de ParamArray ou argumentos de Optional.You can declare event arguments just as you do arguments of procedures, with the following exceptions: events cannot have named arguments, ParamArray arguments, or Optional arguments. Os eventos não têm valores de retorno.Events do not have return values.

Para lidar com um evento, você deve associá-lo a uma sub-rotina do manipulador de eventos usando a instrução Handles ou AddHandler.To handle an event, you must associate it with an event handler subroutine using either the Handles or AddHandler statement. As assinaturas da sub-rotina e do evento devem corresponder.The signatures of the subroutine and the event must match. Para manipular um evento compartilhado, você deve usar a instrução AddHandler.To handle a shared event, you must use the AddHandler statement.

Você pode usar Event somente no nível do módulo.You can use Event only at module level. Isso significa que o contexto de declaração para um evento deve ser uma classe, estrutura, módulo ou interface e não pode ser um arquivo de origem, namespace, procedimento ou bloco.This means the declaration context for an event must be a class, structure, module, or interface, and cannot be a source file, namespace, procedure, or block. Para obter mais informações, consulte Contextos de declaração e níveis de acesso padrão.For more information, see Declaration Contexts and Default Access Levels.

Na maioria das circunstâncias, você pode usar a primeira sintaxe na seção sintaxe deste tópico para declarar eventos.In most circumstances, you can use the first syntax in the Syntax section of this topic for declaring events. No entanto, alguns cenários exigem que você tenha mais controle sobre o comportamento detalhado do evento.However, some scenarios require that you have more control over the detailed behavior of the event. A última sintaxe na seção sintaxe deste tópico, que usa a palavra-chave Custom, fornece esse controle permitindo que você defina eventos personalizados.The last syntax in the Syntax section of this topic, which uses the Custom keyword, provides that control by enabling you to define custom events. Em um evento personalizado, você especifica exatamente o que ocorre quando o código adiciona ou remove um manipulador de eventos de ou para o evento ou quando o código gera o evento.In a custom event, you specify exactly what occurs when code adds or removes an event handler to or from the event, or when code raises the event. Para obter exemplos, consulte como: declarar eventos personalizados para conservar memória e como declarar eventos personalizados para evitar o bloqueio.For examples, see How to: Declare Custom Events To Conserve Memory and How to: Declare Custom Events To Avoid Blocking.

ExemploExample

O exemplo a seguir usa eventos para contar os segundos de 10 a 0.The following example uses events to count down seconds from 10 to 0. O código ilustra vários dos métodos, propriedades e instruções relacionados ao evento.The code illustrates several of the event-related methods, properties, and statements. Isso inclui a instrução RaiseEvent.This includes the RaiseEvent statement.

A classe que gera um evento é a origem do evento, e os métodos que processam o evento são os manipuladores de eventos.The class that raises an event is the event source, and the methods that process the event are the event handlers. Uma origem de evento pode ter vários manipuladores para os eventos que ele gera.An event source can have multiple handlers for the events it generates. Quando a classe gera o evento, esse evento é gerado em todas as classes que escolheram manipular eventos para essa instância do objeto.When the class raises the event, that event is raised on every class that has elected to handle events for that instance of the object.

O exemplo também usa um formulário (Form1) com um botão (Button1) e uma caixa de texto (TextBox1).The example also uses a form (Form1) with a button (Button1) and a text box (TextBox1). Quando você clica no botão, a primeira caixa de texto exibe uma contagem regressiva de 10 a 0 segundos.When you click the button, the first text box displays a countdown from 10 to 0 seconds. Quando o tempo total (10 segundos) tiver decorrido, a primeira caixa de texto exibirá "concluído".When the full time (10 seconds) has elapsed, the first text box displays "Done".

O código para Form1 especifica os Estados inicial e de terminal do formulário.The code for Form1 specifies the initial and terminal states of the form. Ele também contém o código executado quando eventos são gerados.It also contains the code executed when events are raised.

Para usar este exemplo, abra um novo projeto Windows Forms.To use this example, open a new Windows Forms project. Em seguida, adicione um botão chamado Button1 e uma caixa de texto chamada TextBox1 ao formulário principal, chamado Form1.Then add a button named Button1 and a text box named TextBox1 to the main form, named Form1. Em seguida, clique com o botão direito do mouse no formulário e clique em Exibir código para abrir o editor de código.Then right-click the form and click View Code to open the code editor.

Adicione uma variável WithEvents à seção declarações da classe Form1:Add a WithEvents variable to the declarations section of the Form1 class:

Private WithEvents mText As TimerState

Adicione o código a seguir ao código para Form1.Add the following code to the code for Form1. Substitua quaisquer procedimentos duplicados que possam existir, como Form_Load ou Button_Click.Replace any duplicate procedures that may exist, such as Form_Load or Button_Click.

Private Sub Form1_Load() Handles MyBase.Load
    Button1.Text = "Start"
    mText = New TimerState
End Sub
Private Sub Button1_Click() Handles Button1.Click
    mText.StartCountdown(10.0, 0.1)
End Sub

Private Sub mText_ChangeText() Handles mText.Finished
    TextBox1.Text = "Done"
End Sub

Private Sub mText_UpdateTime(ByVal Countdown As Double
  ) Handles mText.UpdateTime

    TextBox1.Text = Format(Countdown, "##0.0")
    ' Use DoEvents to allow the display to refresh.
    My.Application.DoEvents()
End Sub

Class TimerState
    Public Event UpdateTime(ByVal Countdown As Double)
    Public Event Finished()
    Public Sub StartCountdown(ByVal Duration As Double, 
                              ByVal Increment As Double)
        Dim Start As Double = DateAndTime.Timer
        Dim ElapsedTime As Double = 0

        Dim SoFar As Double = 0
        Do While ElapsedTime < Duration
            If ElapsedTime > SoFar + Increment Then
                SoFar += Increment
                RaiseEvent UpdateTime(Duration - SoFar)
            End If
            ElapsedTime = DateAndTime.Timer - Start
        Loop
        RaiseEvent Finished()
    End Sub
End Class

Pressione F5 para executar o exemplo anterior e clique no botão chamado Iniciar.Press F5 to run the previous example, and click the button labeled Start. A primeira caixa de texto começa a contar os segundos.The first text box starts to count down the seconds. Quando o tempo total (10 segundos) tiver decorrido, a primeira caixa de texto exibirá "concluído".When the full time (10 seconds) has elapsed, the first text box displays "Done".

Observação

O método My.Application.DoEvents não processa eventos da mesma maneira que o formulário.The My.Application.DoEvents method does not process events in the same way the form does. Para permitir que o formulário manipule os eventos diretamente, você pode usar multithreading.To enable the form to handle the events directly, you can use multithreading. Para obter mais informações, consulte Threading gerenciado.For more information, see Managed Threading.

Consulte tambémSee also