Understanding events. I: The basics

The whole FAQ consists of four parts
the basics (this one)
automation events
some useful stuff
a substitute for control arrays in VBA

Events are one of ways objects communicate with each other. It is a kind of promise given by first object (event server) to notify other objects-subscribers that the event took place. Events can be either custom (user-defined) or automation (activeX).Event must be either handled (event procedure) or ignored.
VBA supports three magic keywords to deal with events: Event, RaiseEvent (both to declare and create events) and WithEvents (to ask for notifying about object serverÆs events). As events are strictly connected with objects, they can only be declared and handled in class/object/form modules. It is not permitted to define arrays of objects using WithEvents.

As an example, create a simple class named cE with:

[tt][color blue]Public Event Count(i As Integer)

Public Property Let MaxCount(MaxK As Integer)
Dim k As Integer
For k = 1 To MaxK
RaiseEvent Count(k)
Next k
MsgBox "Counting finished"
End Property[/color][/tt]

First line declares event named ôCountö that will pass an integer argument.
The write-only property MaxCount, when set, rises declared event with internal counter k as argument, finally informs that counting was finished.
To make use of this, letÆs add a userform with a spinbutton and label to the project, with code:

[tt][color blue]Private WithEvents xE As cE

Private Sub UserForm_Initialize()
Me.Label1.Caption = Me.SpinButton1.Value
Set xE = New cE
End Sub

Private Sub xE_Count(i As Integer)
MsgBox "Counting: " & i
End Sub

Private Sub SpinButton1_Change()
xE.MaxCount = Me.SpinButton1.Value
Me.Label1.Caption = Me.SpinButton1.Value
End Sub[/color][/tt]

First, we declare variable xE using WithEvents to be notified about xE events. It works like object-type property, with initial set to Nothing. Also only early binding is permitted, no generic ôAs Objectö declaration allowed. In the Initialize procedure we create xE as an instance of cE û events are passed between real objects, not their classes!
Now, when we drop-down the left (object) list of the userform module, we can find the object xE declared with WithEvents keyword (also other objects if we used more WithEvents). After selecting the object, the right list displays available events. VBA creates automatically a procedure having name WithEventsVariable_EventName. Put here an information about counting progress.
Now, when we show the userform and change the spinbutton, we change also property MaxCount of xE and the xE should raise events.
LetÆs notice here that after execution of xE_Count procedure in the userform module, the program flow returns back to the property procedure. So we can think of events as calling specific procedures in external objects.