Visual Basic Language Reference  

RaiseEvent Statement

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.

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

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 of a class module.
Event LogonCompleted(UserName As String)

Sub
   ' Raise the event.
   RaiseEvent LogonCompleted("AustinSteele")
End Sub

You can't use RaiseEvent to raise events that are not explicitly declared in the module. For example, if a form has a Click event, you can't fire 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.

Example

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 (Text1 and 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 TextBox1 and 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.

Imports Microsoft.VisualBasic.DateAndTime

Add a WithEvents variable to the declarations sectin 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 = "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.

See Also

Events and Delegates | Adding Events to a Class | Event Statement