RaiseEvent Statement

RaiseEvent Statement

---

Syntax

     RaiseEvent   eventName[(argList)] 

eventName (required)

The name of the event to raise

argList (optional)

A comma-delimited list of arguments, each of which has its accepted data type defined by the original event definition

Description

The RaiseEvent statement causes a specific event to fire, passing any required arguments expected by the event handler(s).

Usage at a Glance

• eventName must already be defined within the same module as the RaiseEvent statement.

• argList must correctly match the number and data type of parameters defined in the Event statement that defined the target event, and it must be surrounded by parentheses.

• To allow the client code to handle the event being fired, the client object variable must be declared using the WithEvents keyword.

• RaiseEvent is not asynchronous. When you call the RaiseEvent statement in your class code, your class code will not continue executing until the event has been either handled by the client or ignored (if the client is not handling the events raised by the class).

• For more information about implementing your own custom events, see Chapter 8.

Example

The following code uses an event to notify the calling code when something important occurs (in this case, having some processing limit exceeded). The event handler can return a status code through one of its parameters. The instance of the object with the event must be declared with the WithEvents keyword.

     Public Class Transact        ' ----- Define the event with two arguments.        Public Event Status(ByVal Message As String, _           ByRef Cancel As Boolean)        Public Function UpdateRecords(ByRef level As Integer) As Boolean           ' ----- Pretend to process real records.           Dim cancelNow As Boolean = False           If (level > 1000) Then              RaiseEvent Status("Is value too high?", cancelNow)              If cancelNow Then                 Console.WriteLine("Abandoning operation...")                 Exit Function              Else                 level = 1000              End If           End If           Console.WriteLine(level)        End Function     End Class     Module GeneralCode        ' ----- Declare the object that has an event.        Public WithEvents workObject As New Transact        Public Sub Main           workObject.UpdateRecords(1100)        End Sub        Private Sub CheckForProblem(ByVal problemPrompt As String, _              ByRef cancelNow As Boolean) Handles workObject.Status           If (MsgBoxResult.Yes = MsgBox(problemPrompt, _              MsgBoxStyle.YesNo Or MsgBoxStyle.Question)) Then _              cancelNow = True        End Sub     End Module 

Version Differences

Visual Basic 2005 includes a new Custom Event declaration that provides for additional management of event-related activities.

See Also

Event Statement