Visual Basic and WPF event handling (WPF .NET)

If you're coding in Visual Basic .NET, you can use the language-specific Handles keyword to attach an event handler to an object. The object can be an instance in code-behind or an element in Extensible Application Markup Language (XAML). Handles can be used to assign event handlers for common language runtime (CLR) events or Windows Presentation Foundation (WPF) routed events. However, Handles has some usage limitations when used to attach event handlers for routed events.

Prerequisites

The article assumes a basic knowledge of routed events, and that you've read Routed events overview. To follow the examples in this article, it helps if you're familiar with Extensible Application Markup Language (XAML) and know how to write Windows Presentation Foundation (WPF) applications.

Syntax

The syntax for a Sub declaration that uses the Handles keyword is: Sub <procedure name> Handles <object name>.<event name>. That syntax designates a procedure as the event handler that will run when an event specified by <event name> is raised on an object specified by <object name>. The event must be a member of the object's class or base class. The following example shows how to attach an event handler to a XAML element using Handles.

' Click event handler attached to XamlButton using Handles.
Private Sub XamlButton_Click(sender As Object, e As RoutedEventArgs) Handles XamlButton.Click

    ' Handler logic.
    Debug.WriteLine($"Click event handler attached to XamlButton using Handles.")

End Sub

To use Handles with an object defined in code-behind, typically you declare the object using the WithEvents keyword. For more information on WithEvents usage, see these examples. WPF automatically declares all XAML elements using Friend WithEvents. The following example shows how to declare an object defined in code-behind using WithEvents.

' Declare a new button using WithEvents.
Dim WithEvents CodeButton As New Button With {
    .Content = "New button",
    .Background = Brushes.Yellow
}

' Click event handler attached to CodeButton using Handles.
Private Sub CodeButton_Click(sender As Object, e As RoutedEventArgs) Handles CodeButton.Click

    ' Handler logic.
    Debug.WriteLine($"Click event handler attached to CodeButton using Handles.")

End Sub

To use the same handler for multiple events, comma-separate the <object name>.<event name> events. For example, Sub Button_Click(sender As Object, e As RoutedEventArgs) Handles Button1.Click, Button2.Click. The order of the comma-separated events is immaterial.

You can assign different handlers for the same event with multiple Handles statements. The order of the Handles statements doesn't determine the order in which handlers are invoked when the event occurs.

Using 'Handles' in a WPF application

For an object defined in XAML, the Handles event syntax <object name>.<event name> requires the XAML element that represents the object to have a Name or x:Name property. However, a name property isn't required for the XAML page root element, for which you can use the name Me. The following example shows how to attach an event handler to an XAML page root using Handles.

' Loaded event handler attached to the XAML page root using Handles.
Private Sub Window_Loaded(sender As Object, e As RoutedEventArgs) Handles Me.Loaded

    ' Handler logic.
    Debug.WriteLine($"Loaded event handler attached to Window using Handles.")

End Sub

When a XAML page is compiled, every XAML element with a Name or x:Name parameter is declared as Friend WithEvents. As a result, you can use any XAML element with Handles.

Regardless whether you attach an event handler using Handles, XAML attribute syntax, the AddHandler statement, or the AddHandler method, the event system behavior is the same.

Limitations

The Handles keyword has these usage limitations:

• You can only use Handles to attach an event handler to an object if the event is a member of the object's class or base class. For example, you can use Handles to attach a Click event handler to a button whose base class ButtonBase raises the Click routed event. However, one of the features of routed events is that they traverse the element tree, which makes it possible to listen for and handle a Click event at a higher level than the element that raised it. A routed event that a parent element listens for and handles is called an attached event. Handles can't be used for attached events because its syntax doesn't support specifying a different listener in the XAML element tree than the element that raised the event. To assign event handlers for attached events, you'll need to use either XAML attribute syntax or the AddHandler method. For more information on attached events, see Attached events overview and Attached events in WPF.

• Handles syntax doesn't support event handler invocation for Handled events. To enable your event handler to be invoked for Handled events, attach the event handler using the AddHandler(RoutedEvent, Delegate, Boolean) method and set its handledEventsToo parameter to true.

See also

• AddHandler
• Marking routed events as handled, and class handling
• Routed events overview
• Attached events overview
• XAML in WPF