Section 7.2. Events and Event Binding

7.2 Events and Event Binding

An event is an action that occurs. This action can take place on the part of the user of an application (such as when the user clicks a command button), on the part of application code (such as when a change is made to a record in a recordset), or on the part of the operating system (such as a timer event). When an event occurs, we say that the event is raised , or fired .

Each event has a source . This is the object to which the action is applied, such as the button that was clicked. The source is responsible for alerting the operating system that an event has occurred. It does so by sending an event notification message, generally to its parent or container window. For this reason, Microsoft refers to the event source as the sender .

An event often has an event argument , which is simply data that pertains to the event. For instance, the press of a keyboard key generates an event that includes event arguments describing the keycode of the key pressed and information on the state of modifier keys (the Shift, Alt, and Ctrl keys). The event arguments are part of the message sent by the event source.

An event handler is a procedure (or method) that is executed as a result of event notification. The process of declaring an event handler for an event is called binding the procedure to the event.

7.2.1 Control-Related Events

Most controls have a large number of built-in events associated with them. For instance, the textbox control has events associated with changing the text in the textbox, hitting a key while the textbox has the focus, clicking on the textbox with the mouse, dragging the mouse over the textbox, and more.

The VB IDE can be used to insert an empty event handler, complete with the proper event parameters, for any built-in control. The procedure is simply to select the control, then click the Events button in the Properties window. This displays a list of built-in events for the control. Selecting one of these events causes the VB IDE to insert an empty event handler for that event into the code editor window.

Note that each control has a default event . For instance, the default event for the command button is the Click event. As a shortcut, we can get the VB IDE to insert an empty event handler for the default event simply by double clicking the control. For instance, double clicking a command button produces the following code:

 Private Sub button1_Click(ByVal sender As System.Object, _                           ByVal e As System.EventArgs) _     Handles button1.Click End Sub 

The sender variable is the source of the event. The second parameter is an object whose properties describe the event arguments.

Note the Handles clause, which tells the compiler that this procedure handles the button1.Click event. Using this clause, we can assign any procedure to handle this event. We will discuss this further when we talk about AddHandler later in this chapter.

As another example, double clicking a Windows form causes the VB IDE to insert the following empty event handler:

 Protected Sub Form1_Click(ByVal sender As Object, _                           ByVal e As System.EventArgs) End Sub 

7.2.2 WithEvents

To define a custom event in a class module, we can use the WithEvents keyword. To illustrate with a very simple example, suppose we create the class module shown here:

 Public Class Class1     ' Declare an event     Public Event AnEvent(ByVal EventParam As Integer)     ' Method to raise the event     Public Sub RaiseTheEvent(ByVal iEventNumber As Integer)         RaiseEvent AnEvent(iEventNumber)     End Sub End Class 

In a class module with a Windows form, we declare a variable of type Class1 using the WithEvents keyword to hook the class' events:

 Public WithEvents   ev   As Class1 

This automatically causes the VB IDE to add the variable name ev to the left-hand drop-down list above the code window. When we select this variable, the right- hand drop-down list displays the events for this class. In this case, the list contains only the ev_AnEvent event. Selecting this event places an empty event shell in the code editor window (to which we have added a single line of code):

 Public Sub ev_AnEvent(ByVal EventParam As System.Integer) _     Handles ev.AnEvent     MsgBox("Event raised: " & EventParam) End Sub 

Finally, in a button click event, we can place code to implement our simple example:

 Protected Sub Button1_Click(ByVal sender As Object, _                             ByVal e As System.EventArgs) _                             Handles Button1.Click     ' Define a new Class1 instance     ev = New Class1(  )     ' Raise the event     ev.RaiseTheEvent(7) End Sub 

We should note that the WithEvents keyword approach to event handling has one slight drawback. Namely, we cannot use the New keyword with WithEvents , as in:

 Public WithEvents ev As New Class1 

Thus, the object must be instantiated separately from the variable declaration, as we did in the previous example.

7.2.3 AddHandler and RemoveHandler

The AddHandler statement can be used to bind an event handler to a built-in or custom event using code. This makes it possible to bind several event handlers to a single event. To illustrate, proceed as follows . Add the default event handler for a form's Click event:

 Protected Sub Form1_Click(ByVal sender As Object, _                           ByVal e As System.EventArgs) _                           Handles MyBase.Click     MsgBox("Default Click Event")  End Sub 

Next, add another procedure with the same signature as the default event handler:

 Protected Sub Form1Click(ByVal sender As Object, _                          ByVal e As System.EventArgs)     msgbox("Custom Click Event") End Sub 

Finally, we use the AddHandler statement, which must be executed in order to bind the custom Form1Click event handler to the Click event:

 AddHandler Form1.Click, AddressOf Me.Form1Click 

This is actually shorthand for:

 AddHandler Form1.Click, New EventHandler(AddressOf Me.Form1Click) 

In general, the AddHandler statement has the following syntax:

 AddHandler NameOfEventSender, AddressOf NameOfEventHandler 

Note that the binding can also be accomplished using the Handles keyword, as shown in the default event syntax. However, using AddHandler and RemoveHandler allows dynamic binding of event handlers to events.

The syntax for RemoveHandler is the same as that of AddHandler :

 RemoveHandler   NameOfEventSender   , AddressOf   NameOfEventHandler