RaiseEvent Statement

---

Named Arguments

No

Syntax

RaiseEvent eventName [arglist]

eventName

Use: Required

Data Type: String

The name of the event.

arglist

Use: Optional

Data Type: Any (defined by the Event statement)

A comma-delimited list of variables.

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.

• The RaiseEvent and Event statements can be used only in object modules—i.e., in form and class modules—and not in code modules.

Example

The following 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 Event Status(Message As String, _
                    ByRef Cancel As Boolean)

Private Function UpdateRecords(iVal As Integer) as Boolean
    Dim blnCancel As Boolean
    ...
    If iVal > 1000 Then
        RaiseEvent Status "Is value too high?", blnCancel
        If blnCancel Then
            Exit Function
        End If
    End If
    ...
End Function

Programming Tips and Gotchas

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

• VB custom events don't return a value; however, you can use a ByRef argument in arglist to simulate a return value, as shown in the above example.

• RaiseEvent is not asynchronous. In other words, when you call the Raise-Event statement in your class code, your class code won't continue executing until the event has been either handled by the client or ignored (if the client isn't handling the events raised by the class). This can have undesirable side effects, and you should bear in 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 at the client. This could easily turn into a bottleneck adversely affecting the scalability of your application.

• Events can't be raised from within a Microsoft Transaction Server context.

• For more information about implementing your own custom events, see Section 4.3.3 in Chapter 4.

See Also

Event Statement, WithEvents Keyword