RaiseEvent Statement

Triggers an event declared at module level within a class, form, or document.

Syntax

RaiseEvent eventname[( argumentlist )]  

Parts

eventname
Required. Name of the event to trigger.

argumentlist
Optional. Comma-delimited list of variables, arrays, or expressions. The argumentlist argument must be enclosed by parentheses. If there are no arguments, the parentheses must be omitted.

Remarks

The required eventname is the name of an event declared within the module. It follows Visual Basic variable naming conventions.

If the event has not been declared within the module in which it is raised, an error occurs. The following code fragment illustrates an event declaration and a procedure in which the event is raised.

' 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

You cannot use RaiseEvent to raise events that are not explicitly declared in the module. For example, all forms inherit a Click event from System.Windows.Forms.Form, it cannot be raised using RaiseEvent in a derived form. If you declare a Click event in the form module, it shadows the form's own Click event. You can still invoke the form's Click event by calling the OnClick method.

By default, an event defined in Visual Basic raises its event handlers in the order that the connections are established. Because events can have ByRef parameters, a process that connects late may receive parameters that have been changed by an earlier event handler. After the event handlers execute, control is returned to the subroutine that raised the event.

Example 1

The following example uses events to count down seconds from 10 to 0. The code illustrates several of the event-related methods, properties, and statements, including the RaiseEvent statement.

The class that raises an event is the event source, and the methods that process the event are the event handlers. An event source can have multiple handlers for the events it generates. 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.

The example demonstrates a timer that counts down from 10 to 0 seconds and displays the progress to the console. When the countdown finishes, it displays "Done".

Declare a WithEvents variable in your class to handle events from the timer:

Public Class TimerExample
    Private WithEvents mTimer As TimerState

Example 2

Add the following code to implement the event handlers and timer logic. This example shows how to use the RaiseEvent statement to notify event handlers when the timer updates or completes.

    Public Sub StartCountdownExample()
        mTimer = New TimerState()
        mTimer.StartCountdown(10.0, 1.0)
    End Sub

    Private Sub mTimer_UpdateTime(ByVal Countdown As Double) Handles mTimer.UpdateTime
        Console.WriteLine("Time remaining: " & Format(Countdown, "##0.0") & " seconds")
    End Sub

    Private Sub mTimer_Finished() Handles mTimer.Finished
        Console.WriteLine("Done")
    End Sub
End Class

Public Class TimerState
    Public Event UpdateTime(ByVal Countdown As Double)
    Public Event Finished()
    Public Sub StartCountdown(ByVal Duration As Double,
                              ByVal Increment As Double)
        Dim SoFar As Double = 0
        Do While SoFar < Duration
            System.Threading.Thread.Sleep(CInt(Increment * 1000))
            SoFar += Increment
            RaiseEvent UpdateTime(Duration - SoFar)
        Loop
        RaiseEvent Finished()
    End Sub
End Class

When you run the preceding example, it starts counting down the seconds from 10 to 0, displaying the progress to the console. When the full time (10 seconds) has elapsed, it displays "Done".

See also

• Events
• Event Statement
• AddHandler Statement
• RemoveHandler Statement
• Handles