Event Implementation for Components and Custom Controls with Visual Basic
Events are ways for your control to communicate with the rest of the program. You raise an event in code after predetermined conditions are met. For example, if you were authoring a control that provided a password-protected login, you might raise an event after three unsuccessful login attempts. Once an event is raised, it may be handled by the hosting form or control, or it may be ignored altogether. An event is handled by a special method called an event handler, which is invoked when the event is raised.
Implementation of events in components is essentially the same as implementation of events in custom controls. The difference, however, is that components do not have a user interface. Therefore, they will usually not respond to events that occur through interaction with the user (for example, mouse clicks). More often, components will respond to events raised by other components. Because event implementation is somewhat different between Visual Basic and C#, there are separate topics for each language. If you are using C#, see Events Tutorial
Declaring an Event in Visual Basic
For an event to be raised, it must first be declared. The following example shows how to declare an event:
Public Event TooManyUsersLoggedOn(Users as Integer)
There now exists an event called TooManyUsersLoggedOn. It passes a single parameter, Users, when it is raised. An event can have multiple parameters, or none, depending on what is required by the author.
Raising an Event in Visual Basic
Once an event has been declared, it can be raised in code. Raising the event causes the event and its parameters to be shuttled to its event handler, whereupon the code in the event handler executes. An event can be raised in the following manner.
When an event is raised, it must provide the same number and type of parameters as are in its declaration. Parameters can be used by events to carry information between parts of a program that might not be able to communicate otherwise. This is particularly useful in multi-threaded applications where parameters are the best means of passing methods between threads. For more information, see Walkthrough: Authoring a Simple Multithreaded Component with Visual Basic.
Handling an Event in Visual Basic
After an event is raised, one of two things can occur:
- If there is no handler for the event, it is ignored, and program execution proceeds normally.
- If there is a handler for the event, the code within that method executes and the program proceeds from there.
There are two ways to add an event handler:
- Using the Handles keyword and WithEvents
- Using the AddHandler keyword
The Handles Keyword
The first way to add an event handler is by using the Handles keyword as shown:
Public Sub RemoveAUser(ByVal Users as Integer) Handles _ Mycontrol.TooManyUsersLoggedOn ' Insert implementation here End Sub
Using this syntax, the method RemoveAUser will be invoked whenever the TooManyUsersLoggedOn event of MyControl is raised. After this method completes, the program execution will return to the line after where the event was raised. Note that in order to add an event handler in this manner, the control where the event originates must be declared using the keyword WithEvents, as shown in the following example:
Private WithEvents MyControl as MyUserControl
Dynamic Event Handlers with the AddHandler Keyword
A second method of adding an event handler, which does not require the WithEvents keyword, is to add the event handler dynamically using the AddHandler keyword. Using this method, handlers may be created or removed at run time in accordance with the needs of the program. The AddHandler keyword is used as follows:
AddHandler MyControl.TooManyUsersLoggedOn, AddressOf RemoveAUser
This line dynamically creates a handler for the TooManyUsersLoggedOn event of MyControl. The AddressOf keyword creates a delegate that points to the method RemoveAUser, and directs the event to that method. Note that a method added as a handler in this way must take the same number and type of parameters as the event passes.
A handler may also be removed dynamically, using the RemoveHandler keyword and similar syntax, as shown:
RemoveHandler MyControl.TooManyUsersLoggedOn, AddressOf RemoveAUser