WithEvents Keyword

   
WithEvents Keyword

Syntax

 DimPrivatePublic WithEvents   objVarName   As   objectType   
objVarName (required; String)

The name of any object variable that refers to an object that exposes events

objectType (required; 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 for which you intend to provide event handlers.

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.

Rules at a Glance

  • An object-variable declaration using the WithEvents keyword can only be used in an object or class module.

  • An object-variable declaration using the WithEvents keyword should only be placed 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 only valid when used to declare an object variable.

  • You cannot use WithEvents when declaring a 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 will all respond to that object's events.

  • You cannot create an array variable that uses the WithEvents keyword.

  • You cannot use the WithEvents keyword in a local variable declaration.

  • If objectType does not expose any events, the WithEvents statement generates a compiler error.

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) _             Handles oADO.FetchProgress         ProgressBar1.Max = MaxProgress    ProgressBar1.Value = Progress              End Sub 

Programming Tips and Gotchas

  • Placing the object-variable declaration that uses the WithEvents keyword in a procedure does not add the object variable name to the module's Object List. In other words, the events fired from the object would only have scope in the procedure and therefore cannot be handled.

  • Even if you declare the object variable using the Public keyword, the events fired by the object only have scope in the module in which the object variable has been declared.

  • Because you cannot use WithEvents to declare a generic Object type, WithEvents can only be used with early-bound object references. In other words, objects must have been added to the project using the References dialog box. 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, "This object does not raise Events."

VB.NET/VB 6 Differences

In VB 6, object variables in a code module couldn't be declared with WithEvents . In VB.NET, this restriction has been lifted.

See Also

Dim Statement, Public Statement

   


VB.Net Language in a Nutshell
VB.NET Language in a Nutshell
ISBN: B00006L54Q
EAN: N/A
Year: 2002
Pages: 503

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net