| WithEvents Keyword |
Named Arguments
No
Syntax
Dim|Private|Public WithEvents objVarname As objectType
objVarName
Use: Required
Data Type: String
The name of any object variable that refers to an object that exposes events.
objectType
Use: Required
Data Type: Any object type other than the generic Object
The ProgID of a referenced object.
Description
The WithEvents keyword informs VB that the object being referenced exposes events. When you declare an object variable using WithEvents, an entry for the object variable is placed in the code window's drop-down Object List, and a list of the events available to the object variable is placed in the code window's drop-down Procedures List. You can then write code event handlers for the object variable in the same way that you write other more common event handlers such as Form_Load.
Rules at a Glance
An object variable declaration using the WithEvents keyword can be used only in an object module such as a Form or Class module.
An object variable declaration using the WithEvents keyword should be placed only in the Declarations section of the object module.
Any ActiveX object or class module that exposes events can be used with the WithEvents keyword. WithEvents is valid only when used to declare an object variable.
You can't use WithEvents when declaring the generic Object type.
Unlike other variable declarations, the As keyword is mandatory.
There is no limit to the number of object variables that can refer to the same object using the WithEvents keyword; they all respond to that object's events.
You can't create an array variable that uses the WithEvents keyword.
Example
The following example demonstrates how to trap and respond to the events within an ADO recordset. An object variable is declared using the WithEvents keyword in the declarations section of a form module. This allows you to write event-handling code for the ADO's built-in events, in this case the FetchProgress event. (The FetchProgress event allows you to implement a Progress Bar control that shows progress in populating the recordset.)
Private WithEvents oADo As ADODB.Recordset
Private Sub oADo_FetchProgress(ByVal Progress As Long, _
ByVal MaxProgress As Long, _
adStatus As ADODB.EventStatusEnum, _
ByVal pRecordset As ADODB.Recordset)
ProgressBar1.Max = MaxProgress
ProgressBar1.Value = Progress
End SubProgramming Tips and Gotchas
Placing the object variable declaration that uses the WithEvents keyword in a procedure doesn't add the object variable name to the module's Object List. In other words, the events fired from the object would have scope only in the procedure and therefore can't be handled.
Even if you declare the object variable using the Public keyword, the events fired by the object have scope only in the module in which the object variable has been declared.
Because you can't use WithEvents to declare a generic Object type, WithEvents can be used only with early bound object references. In other words, objects must have been added to the project using the References dialog. Without this prior knowledge of the object's interface, VB has no chance of knowing how to handle events from the object.
If the object you are referencing doesn't expose any public events, you will generate a compile-time error, "Object doesn't source Automation Events."
You can't handle any type of event from within a code module. This isn't really a limitation, because to pass program control to a code module, you can simply call one of its functions or procedures from your event handler, just as you would from a form or control's event handler.
For information about generating your own custom events in form and class modules, see Section 4.3.3 in Chapter 4.