Event (Instrucción)

Artículo
10/07/2008

Actualización: noviembre 2007

Declara un evento definido por el usuario.

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

Partes

Parte	Descripción
attrlist	Opcional. Lista de atributos que se aplican a este evento. Los atributos múltiples se separan por comas. Debe incluir la lista Lista de atributos entre corchetes angulares ("<" y ">").
accessmodifier	Opcional. Especifica qué código puede tener acceso al evento. Puede ser una de las siguientes: Public: cualquier código que tenga acceso al elemento que lo declara puede tener acceso a él. Protected: sólo el código que está dentro de su clase o de una clase derivada puede tener acceso a él. Friend: sólo el código que está en el mismo ensamblado puede tener acceso a él. Private: sólo el código que está en el elemento que lo declara puede tener acceso a él. Puede especificar Protected Friend para habilitar el acceso desde el código a la clase del evento, la clase derivada o el mismo ensamblado.
Shared	Opcional. Especifica que este evento no está asociado a una instancia específica de una clase o una estructura.
Shadows	Opcional. Indica que este evento vuelve a declarar y ocultar un elemento de programación con el mismo nombre, o un conjunto de elementos sobrecargados, en una clase base. Puede hacer que cualquier tipo de elemento declarado prevalezca sobre cualquier otro tipo. Un elemento sombreado no está disponible desde la clase derivada que lo sombrea, a menos que el elemento que produce el sombreado no esté accesible. Por ejemplo, si un elemento Private sombrea un elemento de clase base, el código que no tiene el permiso para obtener acceso al elemento Private obtiene acceso al elemento de clase base.
eventname	Obligatorio. Nombre del evento. Sigue las convenciones de nomenclatura estándar de las variables.
parameterlist	Opcional. Lista de variables locales que representan los parámetros de este evento. Debe incluir la lista Lista de parámetros entre paréntesis.
Implements	Opcional. Indica que este evento implementa un evento de una interfaz.
implementslist	Requerido si se suministra Implements. Lista de procedimientos Sub que se están implementando. Los diversos procedimientos se separan con comas: procedimientoImplementado [ , procedimientoImplementado ... ] Cada implementedprocedure tiene la sintaxis y las partes siguientes: interface.definedname ParteDescripción interfaceObligatorio. Nombre de una interfaz que está implementando la clase contenedora o la estructura de este procedimiento. definednameObligatorio. Nombre por el que está definido el procedimiento en interface. No es necesario que su valor sea igual al de name, el nombre que está utilizando este procedimiento para implementar el procedimiento definido.
Custom	Obligatorio. Los eventos declarados como Custom deben definir descriptores de acceso AddHandler, RemoveHandler y RaiseEvent personalizados.
delegatename	Opcional. El nombre de un delegado que especifica la firma del controlador de eventos.
AddHandler	Obligatorio. 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 con la instrucción AddHandler o implícitamente con la cláusula Handles.
End AddHandler	Obligatorio. Termina el bloque AddHandler.
value	Obligatorio. Nombre de parámetro.
RemoveHandler	Obligatorio. Declara un descriptor de acceso RemoveHandler, que especifica las instrucciones que se deben ejecutar cuando se quita un controlador de eventos utilizando la instrucción RemoveHandler.
End RemoveHandler	Obligatorio. Termina el bloque RemoveHandler.
RaiseEvent	Obligatorio. Declara un descriptor de acceso RaiseEvent, que especifica las instrucciones que se deben ejecutar cuando se produce el evento utilizando la instrucción RaiseEvent. Normalmente, invoca una lista de delegados mantenida por los descriptores de acceso AddHandler y RemoveHandler.
End RaiseEvent	Obligatorio. Termina el bloque RaiseEvent.
delegatesignature	Obligatorio. Lista de parámetros que hace coincidir los parámetros requeridos por el delegado delegatename. Debe incluir la lista Lista de parámetros entre paréntesis.
statements	Opcional. Instrucciones que contienen los cuerpos de los métodos AddHandler, RemoveHandler y RaiseEvent.
End Event	Obligatorio. Termina el bloque Event.

Comentarios

Una vez declarado el evento, utilice la instrucción RaiseEvent para provocar el evento. Un evento típico podría declararse y activarse como se muestra en los siguientes fragmentos de código:

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:
Los argumentos de eventos se pueden declarar como los argumentos de procedimientos, con las siguientes excepciones: los eventos no pueden tener argumentos con nombre, argumentos ParamArray ni argumentos Optional. Los eventos no tienen valores devueltos.

Para controlar un evento, debe asociarlo a una subrutina del controlador de eventos utilizando la instrucción Handles o AddHandler. Las firmas de la subrutina y del evento deben coincidir. Para controlar un evento compartido, debe utilizar la instrucción AddHandler.

Sólo puede utilizar Event en el nivel de módulo. Esto significa que el contexto de declaración de un evento debe ser una clase, estructura, módulo o interfaz, y no un archivo de código fuente, un espacio de nombres o un bloque. Para obtener más información, vea Contextos de declaración y niveles de acceso predeterminados.

En la mayoría de las circunstancias, puede utilizar la primera sintaxis de la sección Sintaxis de este tema para declarar los eventos. Sin embargo, algunos escenarios requieren que tenga mayor control sobre el comportamiento detallado del evento. La última sintaxis de la sección Sintaxis de este tema, que usa la palabra clave Custom, proporciona ese control y le permite definir eventos personalizados. En un evento personalizado, especifica exactamente qué sucede cuando el código agrega o quita un controlador del evento o cuando el código provoca el evento. Para obtener ejemplos, vea Cómo: Declarar eventos que evitan que se pierda memoria y Cómo: Declarar eventos que evitan bloqueos.

Ejemplo

En el ejemplo siguiente se utilizan eventos para contar de 10 a 0 segundos. El código muestra varios métodos, propiedades e instrucciones relacionados con eventos. Esto incluye la instrucción RaiseEvent.

La clase que produce un evento es el origen de evento, y los métodos que procesan el evento son los controladores de eventos. Un origen de evento puede tener múltiples controladores para los eventos que genera. Cuando una clase produce el evento, ese evento se genera en cada clase que ha elegido para controlar eventos para esa instancia del objeto.

El ejemplo también utiliza un formulario (Form1) con un botón (Button1) y un cuadro de texto (TextBox1). Al hacer clic en el botón, el primer cuadro de texto muestra una cuenta atrás de 10 a 0 segundos. Cuando ha transcurrido todo el tiempo (10 segundos), el primer cuadro de texto muestra la palabra "Done" (terminado).

El código para Form1 especifica los estados inicial y terminal del formulario. También contiene el código que se ejecuta cuando se producen eventos.

Para utilizar este ejemplo, abra un nuevo proyecto de formularios Windows Forms. A continuación, agregue al formulario principal, llamado Form1, un botón denominado Button1 y un cuadro de texto con el nombre TextBox1. A continuación, haga clic con el botón secundario del mouse en el formulario y haga clic en Ver código para abrir el editor de código.

Agregue una variable WithEvents a la sección de declaraciones de la clase Form1:

Private WithEvents mText As TimerState

Agregue el código siguiente al código de Form1. Sustituya los procedimientos que estén duplicados, como Form_Load o Button_Click.

Private Sub Form1_Load(ByVal sender As Object, _
                       ByVal e As System.EventArgs) _
                       Handles MyBase.Load
    Button1.Text = "Start"
    mText = New TimerState
End Sub
Private Sub Button1_Click(ByVal sender As System.Object, _
                          ByVal e As System.EventArgs) _
                          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 que tiene la etiqueta Iniciar. El primer cuadro de texto empieza la cuenta atrás de los segundos. Cuando ha transcurrido todo el tiempo (10 segundos), el primer cuadro de texto muestra la palabra "Done" (terminado).

Nota:
El método My.Application.DoEvents no procesa los eventos de la misma manera que el formulario. Para permitir que el formulario controle directamente los eventos, puede utilizar el subprocesamiento múltiple. Para obtener más información, vea Subprocesamiento múltiple en Visual Basic.

Vea también

Event (Instrucción)

Partes

Comentarios

Ejemplo

Vea también

Tareas

Referencia

Otros recursos

Recursos adicionales