Handling Events in .NET
Event handling has changed, for the better, in .NET. I never really thought anything of it, but event procedures in Visual Basic 6.0 were attached to the appropriate object and event based solely on the procedure's name. This reliance on names meant that if you had already created and written code for CommandButton1_Click and you renamed your button to the more meaningful saveFile, your event procedure would no longer be attached to this button.
If event handling is no longer based on procedure names, how do you connect a specific event handler with an object's event? There are two ways; one combines the familiar WithEvents keyword in your variable declarations with a new keyword Handles, and the other dynamically connects an object's event to an event handling procedure at runtime.
Using WithEvents and the Handles Keyword
Although event handling in VB .NET has changed, as I described, using the Handles keyword is the closest model to pre-.NET Visual Basic and it is the model used by default by the Windows forms designer. Objects, such as controls, that expose events are declared using the WithEvents keyword, like they were in Visual Basic 6.0, and event procedures provide a Handles myObj.myEvent clause after the procedure declaration. Those two parts, the Handles and WithEvents, wire up a specific event handling procedure.
Returning to the first example, a simple button on a form, look at the code generated by the Windows forms designer to see how the designer wired the Button's Click event to a code procedure. The first line to look at is the declaration of the button itself:
Friend WithEvents Button1 As System.Windows.Forms.Button
The button is declared using the WithEvents keyword, which is required if you want to use the Handles keyword on the event handling procedure. Only having both will make the proper connection between this object (the button) and the event procedure. Next, you double-click the Button1 and the Windows forms designer automatically creates a new event procedure for the default event (Click). Controls can specify one of their events to be the default. If they do, the Windows forms designer will assume you want to work with that event when you double-click the control. The designer knows that the button was declared using the WithEvents keyword, so it creates the procedure declaration with Handles Button1.Click appended to the end (see Listing 3.5).
Listing 3.5 Designer Generated Event Handlers Use the Handles Keyword
Private Sub Button1_Click( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles Button1.Click MsgBox("Hello World!") End Sub
Up to this point, the syntax might be a little different, but the general idea is the same as in Visual Basic 6.0. The only change, the addition of the Handles keyword, is just a way to get around relying on the name of your event handling procedure. Even using WithEvents and Handles though, there is a new feature built into this method of handling events. It is possible to specify that a specific event procedure handle more than one event. If you were to add a second button to the form, (automatically named Button2) and to double-click it, the Windows forms designer would create a second event procedure (see Listing 3.6).
Listing 3.6 The Windows Forms Designer Automatically Creates a Handler for the Default Event When You Double-Click a Control
Private Sub Button2_Click( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles Button2.Click End Sub
This procedure declaration is followed by Handles Button2.Click, but you could instead modify the first Click procedure to handle both buttons' Click events, as shown in Listing 3.7.
Listing 3.7 Listing More than One Object's Events After a Procedure Declaration Allows You to Consolidate Code
Private Sub Button1_Click( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles Button1.Click, Button2.Click MsgBox("Hello World!") End Sub
Now, when either button is clicked, the same code will run. Any number of events can be handled by the same event procedure, assuming that all of the events have the same signature (the same set of arguments to their event procedures). It is also possible to have a single event handled by multiple procedures (see Listing 3.8) by having that event specified in multiple Handles clauses.
Listing 3.8 One Event, Such as a Button's Click, Can be Handled by Multiple Routines
Private Sub ClickEvent1( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles Button2.Click MsgBox("ClickEvent1") End Sub Private Sub ClickEvent2( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles Button2.Click MsgBox("ClickEvent2") End Sub
When Button2 is clicked, the code in both ClickEvent1 and ClickEvent2 is executed. You will use the first concept (multiple events being handled by a single event handler) more often than the second (multiple handlers for a single event), but it is good to know that the functionality exists if you need it. In the case of multiple events all being handled by a single event handler, you will likely need to know which specific control is raising (firing or causing) the event. For most events, the object that raises the event is passed in as the first parameter (usually named "sender") to the event procedure. The sender parameter is typed as an object, which means that you have to convert it into a more useful type (such as a Control or a Button) before you can work with it. Listing 3.9 shows a sample event procedure that is handling the Click event of 10 buttons; it casts (views an object as a different type) the sender parameter from Object to Button to determine the Button's text (caption).
Listing 3.9 If You Handle the Events of Many Different Objects, the Sender Parameter Tells You which Object Caused the Current Event
Private Sub LotsOfButtons( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles Button1.Click, Button2.Click, _ Button3.Click, Button4.Click, _ Button5.Click, Button6.Click, _ Button7.Click, Button8.Click, _ Button9.Click, Button10.Click Dim clickedBtn As Button If TypeOf sender Is Button Then clickedBtn = DirectCast(sender, Button) MsgBox(clickedBtn.Text) End If End Sub
It is worth noting, although perhaps a bit confusing, that you could have also written this routine using Control instead of Button, and this alternative is shown in Listing 3.10.
Listing 3.10 All Windows Forms Controls Inherit from Control, so a Variable of that Type Can Be Used to Hold Any Control on Your Form
Private Sub LotsOfButtons( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles Button1.Click, Button2.Click, _ Button3.Click, Button4.Click, _ Button5.Click, Button6.Click, _ Button7.Click, Button8.Click, _ Button9.Click, Button10.Click Dim clickedCtrl As Control If TypeOf sender Is Control Then clickedCtrl = DirectCast(sender, Control) MsgBox(clickedCtrl.Text) End If End Sub
The reason this works, and it does work, is due to the way in which Windows Forms controls have been written. All Windows Forms controls share the same base class, System.Windows.Forms.Control, and that class provides them with a set of common properties, events, and methods. Text is one of those common properties, so you can cast to Control instead of Button and everything will still work. What does that mean to you? It means you can write code to handle any control on a form and you never have to know what type of control it is. Without casting it to a specific type of control, you can work with any of the common properties available on the Control class including position and size properties, color properties, and many more. Combining the new flexibility in event handling with this common control class, there is a lot you can accomplish using WithEvents and handles. There are a few cases though, when even more flexibility is required, and that is where the other method of event handling comes in.
Wiring Up Events Manually with AddHandler/ RemoveHandler
The WithEvents/Handles method of event handling is designed for when you know at design time which controls and which event handling procedures you are dealing with. If you are going to be working with objects and event procedures in a more dynamic fashion, you can use the AddHandler and RemoveHandler statements to connect an object's event to an event procedure at runtime. This is more of an advanced technique, and it will not likely be necessary in most applications, but here is a basic example to illustrate how these statements could be used. In this example, there is a Button and a CheckBox (set to look like a button) on an otherwise empty form (see Figure 3.3). When the CheckBox is pressed (see Listing 3.11), the button's Click event is attached using AddHandler to a simple event handler that displays a MsgBox. When the CheckBox is in its up position, the button is detached from its event handler using RemoveHandler.Figure 3.3 The check box on this form, which is using the new toggle button appearance, turns event handling on and off for the button.
Listing 3.11 The CheckedChanged Event of the Check Box Is Used to Add and Remove an Event Handler for the Button's Click Event
Private Sub CheckBox1_CheckedChanged( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) _ Handles CheckBox1.CheckedChanged If CheckBox1.Checked Then AddHandler Button1.Click, _ AddressOf myClickHandler Else RemoveHandler Button1.Click, _ AddressOf myClickHandler End If End Sub Private Sub myClickHandler( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) MsgBox("Event Handled!") End Sub
Adding and removing an event handler is a more useful technique with non-form classes that raise events, but the procedure is the same.
Dynamic Event Handling
The AddHandler/RemoveHandler statements open up a completely new form of event handling, one that wasn't available in Visual Basic 6.0. There are many occasions where you will find yourself dynamically creating objects such as controls, but also including such things as forms, database objects, socket objects for TCP/IP communication, and more. By using AddHandler, you can still trap events from these objects even though you never declared them using WithEvents.
Behind the scenes, AddHandler and RemoveHandler are doing work with the delegate related Framework classes, wrapping the functionality of adding and removing additional methods (event handlers) to the same delegate (event). If you need to, you can still work natively with the System.Delegate class instead of, or in addition to, using AddHandler and RemoveHandler.