Declarative Event Handling

Of the two ways of handling events, declarative event handling is simpler because it allows you to declare what events you handle, and the compiler takes care of the rest for you. For example, the following class has a Button field that has a Click event.

 Class Form1   Public Button1 As Button End Class 

To handle the Click event, the first thing that has to happen is that the Button1 field must be declared as something that can raise events. This is done by adding the WithEvents modifier to the beginning of the declaration.

 Class Form1   Public WithEvents Button1 As Button End Class 

The WithEvents modifier can only be specified on fields whose type is a reference type that actually raises events. Also, the WithEvents modifier can only be specified on fields in classes, not in structures.

Advanced

Adding the WithEvents modifier to a field changes its behavior when the field is passed to reference parameters. Because the containing class needs to track when the value of a field is changed, the field will be passed using copy-in/copy-out rather than true byref, even if the type exactly matches the type of the parameter.

Now that Button1 has been declared as raising events, a method can be declared that handles an event that Button1 raises. In this case, a subroutine named Button1_Click is declared with no parameters to handle the Click event. The declaration includes a Handles clause that references the particular event of Button1 that is handled.

 Class Form1   Public WithEvents Button1 As Button   Public Sub Button1_Click() Handles Button1.Click     MsgBox("Button1 was clicked!")   End Sub End Class 

The variable specified in a Handles clause must always be a WithEvents variable in the class, and the parameters of the event must exactly match the parameters of a method that handles it. A particular method can choose to handle multiple events by listing them all in the Handles clause.

 Class Form1   Public WithEvents Button1 As Button   Public WithEvents Button2 As Button   Public Sub Button_Click() Handles Button1.Click, Button2.Click     MsgBox("A button was clicked!")   End Sub End Class 

A derived class may also handle events raised by its base class by specifying the keyword MyBase instead of a WithEvents variable name . For example:

 Class BaseForm   Event Click() End Class Class DerivedForm   Inherits BaseForm   Sub Clicked() Handles MyBase.Click     ...   End Sub End Class 

In the declarative event model, events are always handled for the instance that is stored in the WithEvents variable. When a new value is assigned to a WithEvents variable, the type stops handling events from the instance currently stored in the variable and starts handling events from the new instance being stored into the variable. For example:

 Class Form1   Public WithEvents Button1 As Button   Public Sub Button1_Moved(ByVal X As Integer, ByVal Y As Integer) _     Handles Button1.Moved     MsgBox("Button1 was moved!")   End Sub   Public Sub Test()     Dim Temp As Button     Button1 = New Button()     Button1.Move(10, 10)     Temp = Button1     Button1 = New Button()     Temp.Move(20,20)   End Sub End Class 

In this example, the message " Button1 was moved! " will appear only once rather than twice. When a new button is assigned to Button1 a second time, all the handlers automatically stop handling events from the existing instance, now only stored in Temp , and start handling events from the new instance. So when Move is called on Temp , the Form1 class is no longer handling the Moved event for that particular instance, and Button1_Moved is not called.