How to: Call an Event Handler in Visual Basic

An event is an action or occurrence — such as a mouse click or a credit limit exceeded — that is recognized by some program component, and for which you can write code to respond. An event handler is the code you write to respond to an event.

An event handler in Visual Basic is a Sub procedure. However, you do not normally call it the same way as other Sub procedures. Instead, you identify the procedure as a handler for the event. You can do this either with a Handles Clause (Visual Basic) clause and a WithEvents (Visual Basic) variable, or with an AddHandler Statement. Using a Handles clause is the default way to declare an event handler in Visual Basic. This is the way the event handlers are written by the designers when you program in the integrated development environment (IDE). The AddHandler statement is suitable for raising events dynamically at run time.

When the event occurs, Visual Basic automatically calls the event handler procedure. Any code that has access to the event can cause it to occur by executing a RaiseEvent Statement.

You can associate more than one event handler with the same event. In some cases you can dissociate a handler from an event. For more information, see Events (Visual Basic).

To call an event handler using Handles and WithEvents

1. Make sure the event is declared with an Event Statement.

2. Declare an object variable at module or class level, using the WithEvents (Visual Basic) keyword. The As clause for this variable must specify the class that raises the event.

3. In the declaration of the event-handling Sub procedure, add a Handles Clause (Visual Basic) clause that specifies the WithEvents variable and the event name.

4. When the event occurs, Visual Basic automatically calls the Sub procedure. Your code can use a RaiseEvent statement to make the event occur.

   The following example defines an event and a WithEvents variable that refers to the class that raises the event. The event-handling Sub procedure uses a Handles clause to specify the class and event it handles.

   Public Class raisesEvent
       Public Event somethingHappened()
       Dim WithEvents happenObj As New raisesEvent
       Public Sub processHappen() Handles happenObj.somethingHappened
           ' Insert code to handle somethingHappened event. 
       End Sub 
   End Class
   

To call an event handler using AddHandler

1. Make sure the event is declared with an Event statement.

2. Execute an AddHandler Statement to dynamically connect the event-handling Sub procedure with the event.

3. When the event occurs, Visual Basic automatically calls the Sub procedure. Your code can use a RaiseEvent statement to make the event occur.

   The following example defines a Sub procedure to handle the Closing event of a form. It then uses the AddHandler Statement to associate the catchClose procedure as an event handler for Closing.

   ' Place these procedures inside a Form class definition. 
   Private Sub catchClose(ByVal sender As Object, ByVal e As System.ComponentModel.CancelEventArgs)
       ' Insert code to deal with impending closure of this form. 
   End Sub 
   Public Sub formOpened()
       AddHandler Me.Closing, AddressOf catchClose
   End Sub
   

   You can dissociate an event handler from an event by executing the RemoveHandler Statement.

See Also

Tasks

How to: Create a Procedure (Visual Basic)

How to: Call a Procedure that Does Not Return a Value (Visual Basic)

Reference

Sub Statement (Visual Basic)

AddressOf Operator (Visual Basic)

Concepts

Procedures in Visual Basic

Sub Procedures (Visual Basic)