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.

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.

Note:
Non-shared events should not be raised within the constructor of the class in which they are declared. Although such events do not cause run-time errors, they may fail to be caught by associated event handlers. Use the Shared modifier to create a shared event if you need to raise an event from a constructor.

You can change the default behavior of events by defining a custom event. For custom events, the RaiseEvent statement invokes the event's RaiseEvent accessor. For more information on custom events, see Event Statement.

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 also uses a form (Form1) with a button (Button1) and a text box (TextBox1). When you click the button, the first text box displays a countdown from 10 to 0 seconds. When the full time (10 seconds) has elapsed, the first text box displays "Done".

The code for Form1 specifies the initial and terminal states of the form. It also contains the code executed when events are raised.

To use this example, open a new Windows Application project, add a button named Button1 and a text box named TextBox1 to the main form, named Form1. Then right-click the form and click View Code to open the Code Editor.

Add a WithEvents variable to the declarations section of the Form1 class.

Private WithEvents mText As TimerState

Add the following code to the code for Form1. Replace any duplicate procedures that may exist, such as Form_Load, or 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

Press F5 to run the preceding example, and click the button labeled Start. The first text box starts to count down the seconds. When the full time (10 seconds) has elapsed, the first text box displays "Done".

Note:
The My.Application.DoEvents method does not process events in exactly the same way as the form does. To allow the form to handle the events directly, you can use multithreading. For more information, see Multithreading in Visual Basic.

Tasks

Reference

Other Resources