What is WithEvents?

WithEvents is a Visual Basic keyword, and is declared as below:

   Private WithEvents mcbo As combo   

WithEvents tells the class that an object will be sourcing events, and that we want to sink those events in this class. By adding the WithEvents keyword to a statement that would normally just declare mcbo As combo , the keyword is literally telling the class to dimension the object "with events". In other words, this object is capable of sourcing events and we will be sinking at least some of those events inside of this class. Once an object is declared using the WithEvents keyword, any or all of its events can be sunk (handled) in the class. Which you sink will depend entirely on which events you need to handle to perform the task.

Since only classes can sink events, the WithEvents keyword can only be used in classes. You cannot declare a control WithEvents in a normal module, or you will get a compile error when you attempt to compile the project.

Of course you are probably wondering how the class knows which combo to sink events for. The answer to that comes in the Init event we define for the class.

   Public Function init(lcbo As ComboBox)     Set mcbo = lcbo     mcbo.AfterUpdate = "[Event Procedure]"     End Function   

Notice that we are passing in a combo box to the function, and inside the init event we set our own mcbo to the lcbo passed in. Thus we have told the class to sink events for whatever combo is passed in. By the way, there is nothing magic about the name Init for the function; it can be whatever you wish. Simply understand that real classes are going to be more complex than the simple examples you have seen so far in this book and it is common practice to initialize all of the variables for the class in an Init statement immediately after setting the class variable.

Having dimensioned the combo WithEvents in the class and told the class which combo to sink events for, you can now create event handlers in the class, and control will be transferred to your event handler when the control fires that event.

   Private sub mcbo_AfterUpdate()     msgbox "this is the after update event"     End Sub   

Of course you can sink as many of the object's events in the class as you wish. To keep things simple we are just showing you one for now.

An event handler that you write in your class is identical in every way to an event handler that the code builder writes . It must be private, it must be a sub, and it must use the name of the object sourcing the event ( mcbo in this case) with an _ ( underscore ) and then the event property name ( AfterUpdate ). If the event passes in any parameters you must also recreate these parameters as well. The easiest way to get an event handler built is to simply place a control of the type you desire in a form, name the control exactly what you will call it in your class, open the properties box for that control, then use the code builder to build the event stub. Now cut the event stub out of the form's module and paste it into your own class. The code builder will also build any parameters that Access requires for that event. After a while you will get used to seeing the event stub and will be able to build your own. If you ever have problems though, just remember you can always fall back on Access to build one for you.

Once you learn and start using WithEvents you are going to discover all kinds of classes written by other developers that raise events that you can sink in your own classes. Want to zip and unzip files? Yep, there's a class out there and guess what, it raises events when it is done doing various things. You will learn all about raising events at the end of this chapter.