|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer|
Triggers an event declared at module level within a class, form, or document.
RaiseEvent eventname[( argumentlist )]
The required eventname is the name of an event declared within the module. It follows Visual Basic variable naming conventions.
- Required. Name of the event to trigger.
- 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.
If the event has not been declared within the module in which it is raised, an error occurs. The following fragment illustrates an event declaration and a procedure in which the event is raised.
' Declare an event at module level. Event LogonCompleted(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, if a form has a Click event, you cannot raise its Click event using RaiseEvent. 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 using normal syntax for calling the event, but not using the RaiseEvent statement.
Events are raised in the order that the connections are established. Since events can have ByRef parameters, a process that connects late may receive parameters that have been changed by an earlier event handler.
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 runtime errors, they may fail to be caught by associated event handlers. Use the Shared keyword to create a shared event if you need to raise an event from a constructor.
The following example uses events to count off seconds during a demonstration of the fastest 100-meter race. The code illustrates all 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 (
Command1), a label (
Label1), and two text boxes (
Text2). When you click the button, the first text box displays "From Now" and the second starts to count seconds. When the full time (9.84 seconds) has elapsed, the first text box displays "Until Now" and the second displays "9.84"
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 Forms project, add a button named
Button1, a label named
Label1 and two text boxes, named
TextBox2, to the main form, named
form1. Then right click the form and click View Code to open the code editor.
To simplify access to the Timer property, add an Imports statement as the first line of code above the
Class Form1 statement.
Add a WithEvents variable to the declarations section of the
Private WithEvents mText As TimerState
Add the following code to the code for
Form1. Replace any duplicate procedures that may exist, such as
Private Sub Form1_Load(ByVal sender As Object, _ ByVal e As System.EventArgs) _ Handles MyBase.Load Button1.Text = "Click to Start Timer" TextBox1.Text = "" TextBox2.Text = "" Label1.Text = "The fastest 100 meters ever run took this long:" mText = New TimerState() End Sub Private Sub Button1_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles Button1.Click TextBox1.Text = "From Now" TextBox1.Refresh() TextBox2.Text = "0" TextBox2.Refresh() mText.TimerTask(9.84) End Sub Private Sub mText_ChangeText() Handles mText.ChangeText TextBox1.Text = "Until Now" TextBox2.Text = "9.84" End Sub Private Sub mText_UpdateTime(ByVal Jump As Double) _ Handles mText.UpdateTime TextBox2.Text = Format(Jump, "##0.00") Application.DoEvents() End Sub Class TimerState Public Event UpdateTime(ByVal Jump As Double) Public Event ChangeText() Public Sub TimerTask(ByVal Duration As Double) Dim Start As Double Dim Second As Double Dim SoFar As Double Start = Timer SoFar = Start Do While Timer < Start + Duration If Timer - SoFar >= 0.1 Then SoFar = SoFar + 0.1 RaiseEvent UpdateTime(Timer - Start) End If Loop RaiseEvent ChangeText() End Sub End Class
Press F5 to run this example, and click the button labeled Click to start timer. The text box will count up to 9.84 seconds.