RaiseEvent Statement

RaiseEvent Statement

---

Syntax

 RaiseEvent   eventName   (   [arglist]   ) 

eventName (required; String literal)

The name of the event

arglist (optional; any (defined by the Event statement)

A comma-delimited list of arguments

Description

Generates a predefined, custom event within any procedure of an object module

Rules at a Glance

• eventName must already be defined in the Declarations section of the module using the Event statement.

• arglist must match the number and data type of parameters defined in the Event statement and must be surrounded by parentheses.

• The RaiseEvent and Event statements can only be used in class modules and not in standard modules.

Example

The following code snippet demonstrates how you can use an event to communicate a status message back to the client application and, at the same time, use a ByRef argument to trap a user response in the client application. This gets around the fact that events can't return values. To take advantage of this functionality, the client must declare a reference to this class using the WithEvents keyword:

 Public Class CTransact Public Event Status(Message As String, _                     ByRef Cancel As Boolean) Public Function UpdateRecords(iVal As Integer) as Boolean     Dim blnCancel As Boolean = False     If iVal > 1000 Then         RaiseEvent Status("Is value too high?", blnCancel)         If blnCancel Then            Console.WriteLine("Abandoning operation...")            Exit Function         Else            iVal = 1000         End If     End If     console.writeline(iVal)    End Function End Class Module modMain    Public WithEvents oTran As New CTransact    Public Sub Main       otran.updaterecords(1100)    End Sub    Private Sub UpdateProb(sMsg As String, _                           byref blnCancel as Boolean) _                Handles oTran.Status       If MsgBoxResult.Yes = MsgBox(sMsg, MsgBoxStyle.YesNo _                                    Or MsgBoxStyle.Question) Then          blnCancel = True       End If    End Sub End Module 

Programming Tips and Gotchas

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

• VB custom events do not return a value; however, you can use a ByRef argument in arglist to simulate a return value, as shown in the previous example.

• RaiseEvent is not asynchronous. In other words, 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). This can have undesirable side effects, and you should bear it mind when planning your application. For example, you may have a recordset open or a transaction pending and have to wait for the user to respond to a message dialog box at the client. This could easily turn into a bottleneck, adversely affecting the scalability of your application.

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

See Also

Event Statement