Event (Instrucción)Event Statement

Declara un evento definido por el usuario.Declares a user-defined event.

SintaxisSyntax

[ <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  

ElementosParts

PartePart DESCRIPCIÓNDescription
attrlist Opcional.Optional. Lista de atributos que se aplican a este evento.List of attributes that apply to this event. Los diversos atributos se separan con comas.Multiple attributes are separated by commas. Debe incluir la lista de atributos entre corchetes angulares (<"" y>"").You must enclose the Attribute List in angle brackets ("<" and ">").
accessmodifier Opcional.Optional. Especifica qué código puede tener acceso al evento.Specifies what code can access the event. Puede ser uno de los siguientes:Can be one of the following:

- Público: cualquier código que pueda tener acceso al elemento que lo declara puede tener acceso al mismo.- Public—any code that can access the element that declares it can access it.
- Protected: solo el código dentro de su clase o una clase derivada puede acceder a él.- Protected—only code within its class or a derived class can access it.
- Friend: solo el código del mismo ensamblado puede acceder a él.- Friend—only code in the same assembly can access it.
- Private: solo el código del elemento que lo declara puede tener acceso al mismo.- Private—only code in the element that declares it can access it.
- Código de solo lectura protegidoen la clase del evento, una clase derivada o el mismo ensamblado que puede tener acceso a él.- Protected Friend-only code in the event's class, a derived class, or the same assembly can access it.
- Un código privado solo protegidoen la clase del evento o una clase derivada en el mismo ensamblado puede tener acceso al mismo.- 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 este evento no está asociado a una instancia específica de una clase o estructura.Specifies that this event is not associated with a specific instance of a class or structure.
Shadows Opcional.Optional. Indica que este evento vuelve a declarar y oculta un elemento de programación con el mismo nombre, o un conjunto de elementos sobrecargados, en una clase base.Indicates that this event redeclares and hides an identically named programming element, or set of overloaded elements, in a base class. Puede reemplazar cualquier tipo de elemento declarado con cualquier otro tipo.You can shadow any kind of declared element with any other kind.

Un elemento reemplazado no está disponible desde la clase derivada que lo reemplaza, excepto desde donde el elemento reemplazado es inaccesible.A shadowed element is unavailable from within the derived class that shadows it, except from where the shadowing element is inaccessible. Por ejemplo, si un elemento Private reemplaza un elemento de clase base, el código que no tiene permiso para acceder al elemento Private accede en su lugar al elemento de clase base.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 Necesario.Required. Nombre del evento; sigue las convenciones estándar de nomenclatura de variables.Name of the event; follows standard variable naming conventions.
parameterlist Opcional.Optional. Lista de variables locales que representan los parámetros de este evento.List of local variables that represent the parameters of this event. Debe incluir la lista de parámetros entre paréntesis.You must enclose the Parameter List in parentheses.
Implements Opcional.Optional. Indica que este evento implementa un evento de una interfaz.Indicates that this event implements an event of an interface.
implementslist Es necesario si se proporciona Implements.Required if Implements is supplied. Lista de procedimientos Sub que se implementan.List of Sub procedures being implemented. Los diversos procedimientos se separan con comas:Multiple procedures are separated by commas:

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

Cada implementedprocedure tiene la sintaxis y las partes siguientes:Each implementedprocedure has the following syntax and parts:

interface.definednameinterface.definedname

- interfaceDesee.- interface - Required. Nombre de una interfaz que implementan la estructura o clase contenedora de este procedimiento.Name of an interface that this procedure's containing class or structure is implementing.
- DefinednameDesee.- Definedname - Required. Nombre por el que se define el procedimiento en interface.Name by which the procedure is defined in interface. No tiene que ser el mismo que name, el nombre que usa este procedimiento para implementar el procedimiento definido.This does not have to be the same as name, the name that this procedure is using to implement the defined procedure.
Custom Necesario.Required. Los eventos declarados como Custom deben definir descriptores de acceso AddHandler, RemoveHandler y RaiseEvent personalizados.Events declared as Custom must define custom AddHandler, RemoveHandler, and RaiseEvent accessors.
delegatename Opcional.Optional. Nombre de un delegado que especifica la firma del controlador de eventos.The name of a delegate that specifies the event-handler signature.
AddHandler Necesario.Required. Declara un descriptor de acceso AddHandler, que especifica las instrucciones que se deben ejecutar cuando se agrega un controlador de eventos, ya sea explícitamente mediante la instrucción AddHandler o implícitamente mediante la 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 Necesario.Required. Finaliza el bloque AddHandler.Terminates the AddHandler block.
value Necesario.Required. Nombre del parámetro.Parameter name.
RemoveHandler Necesario.Required. Declara un descriptor de acceso RemoveHandler, que especifica las instrucciones que se ejecutan cuando se quita un controlador de eventos mediante la instrucción RemoveHandler.Declares a RemoveHandler accessor, which specifies the statements to execute when an event handler is removed using the RemoveHandler statement.
End RemoveHandler Necesario.Required. Finaliza el bloque RemoveHandler.Terminates the RemoveHandler block.
RaiseEvent Necesario.Required. Declara un descriptor de acceso RaiseEvent, que especifica las instrucciones que se ejecutan cuando se produce el evento mediante la instrucción RaiseEvent.Declares a RaiseEvent accessor, which specifies the statements to execute when the event is raised using the RaiseEvent statement. Normalmente, invoca una lista de delegados mantenida por los descriptores de acceso AddHandler y RemoveHandler.Typically, this invokes a list of delegates maintained by the AddHandler and RemoveHandler accessors.
End RaiseEvent Necesario.Required. Finaliza el bloque RaiseEvent.Terminates the RaiseEvent block.
delegatesignature Necesario.Required. Lista de parámetros que coincide con los parámetros requeridos por el delegado delegatename.List of parameters that matches the parameters required by the delegatename delegate. Debe incluir la lista de parámetros entre paréntesis.You must enclose the Parameter List in parentheses.
statements Opcional.Optional. Instrucciones que contienen los cuerpos de los métodos AddHandler, RemoveHandler y RaiseEvent.Statements that contain the bodies of the AddHandler, RemoveHandler, and RaiseEvent methods.
End Event Necesario.Required. Finaliza el bloque Event.Terminates the Event block.

ComentariosRemarks

Una vez declarado el evento, use la instrucción RaiseEvent para generar el evento.Once the event has been declared, use the RaiseEvent statement to raise the event. Un evento típico podría declararse y provocarse tal como se muestra en los fragmentos siguientes: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

Nota

Puede declarar argumentos de evento del mismo modo que los argumentos de procedimientos, con las siguientes excepciones: los eventos no pueden tener argumentos con nombre, argumentos ParamArray o argumentos 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. Los eventos no tienen valores devueltos.Events do not have return values.

Para controlar un evento, debe asociarlo a una subrutina del controlador de eventos mediante la instrucción Handles o AddHandler.To handle an event, you must associate it with an event handler subroutine using either the Handles or AddHandler statement. Las firmas de la subrutina y del evento deben coincidir.The signatures of the subroutine and the event must match. Para controlar un evento compartido, debe usar la instrucción AddHandler.To handle a shared event, you must use the AddHandler statement.

Solo se puede usar Event en un nivel de módulo.You can use Event only at module level. Esto significa que el contexto de la declaración de un evento debe ser una clase, una estructura, un módulo o una interfaz, y no puede ser un archivo de código fuente, un espacio de nombres, un procedimiento o un bloque.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 obtener más información, vea Declaration Contexts and Default Access Levels (Contextos de declaración y niveles de acceso predeterminados).For more information, see Declaration Contexts and Default Access Levels.

En la mayoría de los casos, puede usar la primera sintaxis de la sección Sintaxis de este tema para declarar los eventos.In most circumstances, you can use the first syntax in the Syntax section of this topic for declaring events. Sin embargo, algunos escenarios requieren un mayor control sobre el comportamiento detallado del evento.However, some scenarios require that you have more control over the detailed behavior of the event. La última sintaxis de la sección Sintaxis de este tema, que usa la palabra clave Custom, proporciona ese control permitiéndole definir 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. En un evento personalizado, debe especificar exactamente lo que sucede cuando el código agrega o quita un controlador de eventos a o desde el evento, o cuando el código provoca el 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 obtener ejemplos, vea Cómo: Declarar eventos personalizados para conservar memoria y cómo: Declarar eventos personalizados para evitar bloqueos.For examples, see How to: Declare Custom Events To Conserve Memory and How to: Declare Custom Events To Avoid Blocking.

EjemploExample

En el ejemplo siguiente se usan eventos para contar los segundos de 10 a 0.The following example uses events to count down seconds from 10 to 0. El código muestra algunos de los métodos, propiedades e instrucciones relacionados con eventos.The code illustrates several of the event-related methods, properties, and statements. Esto incluye la instrucción RaiseEvent.This includes the RaiseEvent statement.

La clase que provoca un evento es el origen del evento, y los métodos que procesan el evento son los controladores de eventos.The class that raises an event is the event source, and the methods that process the event are the event handlers. Un origen de eventos puede tener varios controladores para los eventos que genera.An event source can have multiple handlers for the events it generates. Cuando la clase genera el evento, ese evento se genera en cada clase que eligió controlar eventos para esa instancia del 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.

El ejemplo también usa un formulario (Form1) con un botón (Button1) y un cuadro de texto (TextBox1).The example also uses a form (Form1) with a button (Button1) and a text box (TextBox1). Al hacer clic en el botón, el primer cuadro de texto muestra una cuenta atrás de 10 a 0 segundos.When you click the button, the first text box displays a countdown from 10 to 0 seconds. Cuando transcurre el tiempo (10 segundos), el primer cuadro de texto muestra "Done".When the full time (10 seconds) has elapsed, the first text box displays "Done".

El código de Form1 especifica los estados inicial y terminal del formulario.The code for Form1 specifies the initial and terminal states of the form. También contiene el código que se ejecuta cuando se producen eventos.It also contains the code executed when events are raised.

Para usar este ejemplo, abra un nuevo proyecto de Windows Forms.To use this example, open a new Windows Forms project. Agregue un botón denominado Button1 y un cuadro de texto denominado TextBox1 al formulario principal, denominado Form1.Then add a button named Button1 and a text box named TextBox1 to the main form, named Form1. A continuación, haga clic con el botón secundario en el formulario y haga clic en Ver código para abrir el editor de código.Then right-click the form and click View Code to open the code editor.

Agregue una variable WithEvents a la sección de declaraciones de la clase Form1:Add a WithEvents variable to the declarations section of the Form1 class:

Private WithEvents mText As TimerState

Agregue el código siguiente al código de Form1.Add the following code to the code for Form1. Sustituya los procedimientos duplicados que existan, como Form_Load o 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

Presione F5 para ejecutar el ejemplo anterior y haga clic en el botón iniciar.Press F5 to run the previous example, and click the button labeled Start. El primer cuadro de texto empieza la cuenta atrás de los segundos.The first text box starts to count down the seconds. Cuando transcurre el tiempo (10 segundos), el primer cuadro de texto muestra "Done".When the full time (10 seconds) has elapsed, the first text box displays "Done".

Nota

El método My.Application.DoEvents no procesa los eventos de la misma manera que el formulario.The My.Application.DoEvents method does not process events in the same way the form does. Para habilitar el formulario de modo que controle directamente los eventos, puede usar multithreading.To enable the form to handle the events directly, you can use multithreading. Para obtener más información, vea subprocesamiento administrado.For more information, see Managed Threading.

Vea tambiénSee also