RaiseEvent (Instrucción)

Artículo
08/10/2011

Desencadena un evento declarado en el nivel de módulo dentro de una clase, formulario o documento.

RaiseEvent eventname[( argumentlist )]

Partes

eventname
Obligatorio. Nombre del evento que se va a desencadenar.
argumentlist
Opcional. Lista de variables, matrices o expresiones delimitadas por comas. El argumento argumentlist debe estar entre paréntesis. Si no hay argumentos, deben omitirse los paréntesis.

Comentarios

El parámetro eventname requerido es el nombre de un evento declarado en el módulo. Sigue las convenciones de nomenclatura de Visual Basic.

Si el evento no se ha declarado dentro del módulo en el que se produce, ocurrirá un error. El siguiente fragmento de código muestra una declaración de evento y un procedimiento en el que se produce el evento.

' Declare an event at module level.
Event LogonCompleted(ByVal UserName As String)

Sub Logon(ByVal UserName As String)
    ' Raise the event.
    RaiseEvent LogonCompleted(UserName)
End Sub

No se puede utilizar RaiseEvent para generar eventos que no estén explícitamente declarados en el módulo. Por ejemplo, todos los formularios heredan un evento Click de System.Windows.Forms.Form; no se puede producir utilizando RaiseEvent en un formulario derivado. Si se declara un evento Click en el módulo de formulario, sombrea el propio evento Click del formulario. Sin embargo, todavía se puede invocar el evento Click del formulario llamando al método OnClick.

De manera predeterminada, un evento definido en Visual Basic provoca sus controladores de eventos en el orden en que se establecen las conexiones. Como los eventos pueden tener parámetros ByRef, un proceso que se conecta tarde puede recibir parámetros modificados por un controlador de eventos anterior. Después de que se ejecutan los controladores de eventos, el control se devuelve a la subrutina que provocó el evento.

Nota

Los eventos no compartidos no se deben provocar dentro del constructor de la clase en la que están declarados. Aunque dichos eventos no provocan errores en tiempo de ejecución, es posible que los controladores de eventos asociados no los puedan capturar. Se debe utilizar el modificador Shared para crear un evento compartido si es necesario provocar un evento a partir de un constructor.

Nota

El comportamiento predeterminado de eventos se puede cambiar definiendo un evento personalizado. En los eventos personalizados, la instrucción RaiseEvent invoca al descriptor de acceso RaiseEvent del evento. Para obtener más información sobre eventos personalizados, vea Event (Instrucción).

Ejemplo

En el siguiente ejemplo se utilizan eventos para hacer una cuenta atrás de los segundos de 10 a 0. El código muestra algunos de los métodos, propiedades e instrucciones relacionados con eventos, incluyendo 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.

En el ejemplo también se 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 presenta una cuenta atrás de 10 a 0 segundos. Cuando ha transcurrido todo el tiempo (10 segundos), el primer cuadro de texto presenta "Done".

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 aplicación para Windows, agregue un botón denominado Button1 y un cuadro de texto denominado TextBox1 al formulario principal, denominado Form1. 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() 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 que tiene la etiqueta Iniciar. El primer cuadro de texto empieza la cuenta atrás. Cuando ha transcurrido todo el tiempo (10 segundos), el primer cuadro de texto presenta "Done".

Nota

El método My.Application.DoEvents no procesa los eventos exactamente de la misma manera en que lo hace el formulario. Para permitir que el formulario controle directamente los eventos, puede utilizar el multithreading. Para obtener más información, vea Subprocesamiento (C# y Visual Basic).