Routed Events, WPF Tree Structures, Event Sequence for Beginners

Introduction

As you perhaps know, a native CLR event is fired whenever a user action is initiated on a Control object and the specified control’s event handler only gets triggered. No other controls are affected by this event. E.g., any event that you can think of in WPF is essentially a CLR event.

On the contrary, a routed event is a type of event that can invoke handlers on multiple listeners in an element tree rather than just the object that raised the event. It is basically a CLR event that is supported by an instance of the Routed Event class. It is registered with the WPF event system.

To explain routed events in details, let us take an example of a WPF UI window, where there are a few nested controls.

Window
- StackPanel 1
  - StackPanel 2
    - Textbox 1
    - Textbox 2
  - Button

I hope the above structure is clear to you. Please keep this UI structure in your mind, we will refer to it as and when required.

Now, we will introduce WPF tree structures briefly for your benefit.

Tree Structures

To create and identify the relationship between UI elements in a WPF application, there are two object tree structures.

Logical Tree Structure
The structure of the UI elements in XAML represents the logical tree structure. In the above WPF UI window, if you look at the XAML code, you will see the logical tree structure.
Visual Tree Structure
Describes the structure of visual objects, as represented by the Visual Base Class. It signifies all the UI elements which are rendered to the output screen. It is used to render the visual objects and the layouts. The routed events mostly travel along the visual tree, not the logical tree. If you compile and run the XAML, you will see the Live Visual Tree in the Visual Studio. The visual tree is typically a superset of the logical tree with additional information on visual formatting options.

Keeping this in mind, we will dig deep into the routing strategies.

Routed Events

Routed Events have three main routing strategies which are as follows,

Direct Event
Bubbling Event
Tunneling Event

Direct Event

A direct event is similar to events in Windows forms which are raised by the element in which the event is originated.

Unlike a standard CLR event, direct routed events support class handling and they can be used in Event Setters and Event Triggers within your style of your Custom Control.

A good example of a direct event would be the MouseEnter event.

Bubbling Event

A bubbling event begins with the element where the event is originated. Then it travels up the visual tree to the topmost element in the visual tree. As you probably have guessed, in WPF, the topmost element is most likely a window.

Now coming to the example that I set earlier, if you click the Button, then the Bubbling event shall move in this direction,

Button > Stackpanel 1 > Window

If you click any of the Textboxes, then the event route will be,

Textbox 1 or 2 > Stackpanel 2 > Stackpanel 1> Window

Tunnel Event

The direction of Tunneling event is opposite to the Bubbling event. Here the event handlers on the element tree root are invoked and then the event travels down the visual tree to all the children nodes until it reaches the element in which the event originated.

The difference between a bubbling and a tunneling event (apart from the direction) is that a tunneling event name will always start with a ‘preview’.

In a WPF application, events are often implemented as a tunneling/bubbling pair. So, you'll have a previewMouseDown and then a MouseDown event.

Event Sequence

Now let’s clear your concept a bit more with the proper event chain.

A standard Button control is derived from ButtonBase, and so it inherits a Click event that fires when a user clicks on the button. As ButtonBase inherits from UIElement, a Button will also have access to all of the mouse button events (like MouseLeftButtonDown and MouseDown) defined for UIElement. But as the Button does something in response to button presses, it swallows the bubbling events (e.g. MouseLeftButtonDown and MouseDown). In general, controls that do something as the result of a user pressing a mouse button will swallow the related events. Clicking on a TextBox gives it focus. Clicking on a Button or ComboBox also results in the control responding to the click, so these controls also swallow the non-preview events. Remember, these types of controls only fire the Tunneling events.

E.g. When a user clicks on a button, there are a series of preview events (tunneling) and actual events (bubbling) that travel up and down the logical tree.

For a left-click on a Button, you’ll normally see click-related events in the following order,

PreviewMouseLeftButtonDown (Tunnel)
PreviewMouseDown (Tunnel)
PreviewMouseLeftButtonUp (Tunnel)
PreviewMouseUp (Tunnel)
Click (Bubble)

But for a Label contained in a StackPanel, which is contained in a Window, the full sequence of events for a left mouse button click on the Label is,

PreviewMouseLeftButtonDown for Window (Tunnel)
PreviewMouseDown for Window (Tunnel)
PreviewMouseLeftButtonDown for StackPanel (Tunnel)
PreviewMouseDown for StackPanel (Tunnel)
PreviewMouseLeftButtonDown for Label (Tunnel)
PreviewMouseDown for Label (Tunnel)
MouseLeftButtonDown for Label (Bubble)
MouseDown for Label (Bubble)
MouseLeftButtonDown for StackPanel (Bubble)
MouseDown for StackPanel (Bubble)
MouseLeftButtonDown for Window (Bubble)
MouseDown for Window (Bubble)
PreviewMouseLeftButtonUp for Window (Tunnel)
PreviewMouseUp for Window (Tunnel)
PreviewMouseLeftButtonUp for StackPanel (Tunnel)
PreviewMouseUp for StackPanel (Tunnel)
PreviewMouseLeftButtonUp for Label (Tunnel)
PreviewMouseUp for Label (Tunnel)
MouseLeftButtonUp for Label (Bubble)
MouseUp for Label (Bubble)
MouseLeftButtonUp for Stackpanel (Bubble)
MouseUp for StackPanel (Bubble)
MouseLeftButtonUp for Window (Bubble)
MouseUp for Window (Bubble)

Now get ready for some hands-on demo of this beautiful feature of routed events. In this example I will show you only Bubble events, but don’t worry! Very soon I will post few more examples on Tunneling events as well.

Many of the easy tutorials available on the internet provide examples based on buttons. It is very basic and easy and it hides the important aspects of using the Routed events. So, I have decided to use controls other than buttons (more specifically TextBlock!) in order to properly indicate the features of routed events.

Hands-on Demo

Here I will create a custom routed event. You need to follow the steps given below to define a custom routed event in C#.

Declare and register your routed event with system call RegisterRoutedEvent.
Specify the Routing Strategy, i.e. Bubble, Tunnel, or Direct.
Provide the event handler.

Follow the steps given below,

Create a new WPF project called WpfCustomRoutedEventTutorial.
Right-click on your solution and select Add > New Item... In the following dialog, select Custom Control (WPF) and name it MyCustomControl.
Click the Add button and you will see that two new files (Themes/Generic.xaml and MyCustomControl.cs) will be added to your solution.

The following XAML code sets the style for the custom control in Generic.xaml file.

<ResourceDictionary
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="clr-namespace:WpfCustomRoutedEventTutorial">
<Style TargetType="{x:Type local:MyCustomControl}">
<Setter Property="Template">
<Setter.Value>
<ControlTemplate TargetType="{x:Type local:MyCustomControl}">
<Border Background="{TemplateBinding Background}"
BorderBrush="{TemplateBinding BorderBrush}"
BorderThickness="{TemplateBinding BorderThickness}">
<TextBlock x:Name = "tbCustomControl" Text = "I am Custom Textblock. Click or Double-click Me!" />
</Border>
</ControlTemplate>
</Setter.Value>
</Setter>
</Style>
</ResourceDictionary>

Given below is the C# code for the MyCustomControl class which inherits from the Control class in which a custom routed event Click is created for the custom control. The code is heavily commented in order to spoon-feed you with the logic. Don’t worry.

using System.Windows;
using System.Windows.Controls;
namespace WpfCustomRoutedEventTutorial
{
public class MyCustomControl : Control
{
static MyCustomControl()
{
DefaultStyleKeyProperty.OverrideMetadata(typeof(MyCustomControl), new FrameworkPropertyMetadata(typeof(MyCustomControl)));
}
/* Assign event handler to the Routed events here. Templates are the section of an element's
* completed visual tree that comes from the Template property of a Style that is applied to the element.
*/
public override void OnApplyTemplate()
{
base.OnApplyTemplate();
var custextblock = GetTemplateChild("tbCustomControl") as TextBlock;
if (custextblock != null)
{
/* Assign mouse wheel event handler to the mouse wheel event. This is fired
* when the user rotates the mouse wheel while the cursor is on the control.
* */
custextblock.MouseWheel += Custom_MouseWheel;
/* Assign mouse down event handler to the mouse down event. This is fired
* when the user clicks any mouse button while the cursor is on the control.
* */
custextblock.MouseDown += Custom_MouseClick;
}
}
/* Event handler for mouse click */
private void Custom_MouseClick(object sender, System.Windows.Input.MouseButtonEventArgs e)
{
RaiseMouseClickEvent();
}
/* Event handler for mouse wheel rotate */
void Custom_MouseWheel(object sender, RoutedEventArgs e)
{
RaiseMouseWheelEvent();
}
/***************** 1ST ROUTED EVENT ******************/
/* Now we will create a custom routed event called CustomWheelEvent. The name of the event is MyCustomWheelRotate
* Use bubbling strategy, handler type is RoutedEventHandler, Owner type is MyCustomControl.
*/
public static readonly RoutedEvent CustomWheelEvent =
EventManager.RegisterRoutedEvent("MyCustomWheelRotate", RoutingStrategy.Bubble,
typeof(RoutedEventHandler), typeof(MyCustomControl));
/* Just like Dependency Properties, routed events are also like wrapper over underlying RoutedEvent instance
* and they wrap through a set of getter-setter methods.
*/
public event RoutedEventHandler MyCustomWheelRotate
{
add { AddHandler(CustomWheelEvent, value); }
remove { RemoveHandler(CustomWheelEvent, value); }
}
/***************** 2ND ROUTED EVENT ******************/
/* Now we will create another custom routed event called CustomClickEvent. The name of the event is MyCustomClick
* Use bubbling strategy, handler type is RoutedEventHandler, Owner type is MyCustomControl.
*/
public static readonly RoutedEvent CustomClickEvent =
EventManager.RegisterRoutedEvent("MyCustomClick", RoutingStrategy.Bubble,
typeof(RoutedEventHandler), typeof(MyCustomControl));
/* Just like Dependency Properties, routed events are also like wrapper over underlying RoutedEvent instance
* and they wrap through a set of getter-setter methods.
*/
public event RoutedEventHandler MyCustomClick
{
add { AddHandler(CustomClickEvent, value); }
remove { RemoveHandler(CustomClickEvent, value); }
}
/* Raise the Mouse wheel routed event that travels through the element tree.
*/
protected virtual void RaiseMouseWheelEvent()
{
RoutedEventArgs args = new RoutedEventArgs(CustomWheelEvent);
RaiseEvent(args);
}
/* Raise the Mouse click routed event that travels through the element tree.
*/
protected virtual void RaiseMouseClickEvent()
{
RoutedEventArgs args = new RoutedEventArgs(CustomClickEvent);
RaiseEvent(args);
}
}
}

If you are clear up to here, you are more or less through. Now, only the client-side logic remains, that is, after you create your own custom routed event on a custom control, you want to use this custom control in a WPF application, right?

So, here it is.

Here is the implementation in MainWindow.xaml to add your own custom control with two routed events.

<Window x:Class="WpfCustomRoutedEventTutorial.MainWindow"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
xmlns:local="clr-namespace:WpfCustomRoutedEventTutorial"
mc:Ignorable="d"
Title="MainWindow" Height="350" Width="525" MouseDown="Window_Click">
<Grid>
<StackPanel Margin = "20" MouseDown="StackPanel_Click">
<StackPanel Margin = "10">
<TextBlock Name = "txt1" FontSize = "18" Margin = "5" Text = "This is a TextBlock 1" />
<TextBlock Name = "txt2" FontSize = "18" Margin = "5" Text = "This is a TextBlock 2" />
<TextBlock Name = "txt3" FontSize = "18" Margin = "5" Text = "This is a TextBlock 3" />
</StackPanel>
<local:MyCustomControl MyCustomWheelRotate="MyCustomControl_MouseWheel" MyCustomClick="MyCustomControl_MouseClick" />
</StackPanel>
</Grid>
</Window>

Here is the custom routed event implementation in C# which will change the text of the three textboxes depending upon which event you fired.

using System.Windows;
namespace WpfCustomRoutedEventTutorial
{
/// <summary>
/// Interaction logic for MainWindow.xaml
/// </summary>
public partial class MainWindow : Window
{
public MainWindow()
{
InitializeComponent();
}
/* The custom routed event implementation which will display a message box when the user clicks it.
*/
private void MyCustomControl_MouseWheel(object sender, RoutedEventArgs e)
{
txt1.Text = "Wheel rotated! It is the custom routed event of your custom control";
}
private void MyCustomControl_MouseClick(object sender, RoutedEventArgs e)
{
txt1.Text = "Clicked! It is the custom routed event of your custom control";
}
/* The event will be routed to its parent which is a stackpanel.
*/
private void StackPanel_Click(object sender, RoutedEventArgs e)
{
txt2.Text = "Only the Click event is bubbled to Stack Panel";
}
/* The event will then again be routed to its parent which is the window.
*/
private void Window_Click(object sender, RoutedEventArgs e)
{
txt3.Text = "Only the Click event is bubbled to Window";
}
}
}

When the above code is compiled and executed, it will produce the following window which contains a custom control.

WPF

Now you point to the Textblock and rotate your mouse wheel. You will see this. The red colored text is only to indicate (it's not part of the output).

WPF

Now, if you single-click on the Textblock, you will see the following.

WPF

Interesting! Isn’t it?

When you single-click on the Textblock, the MouseEnter event is fired. In this case, the Routed event originated from the TextBlock and moved in the direction,

TextBlock > StackPanel > Window.

So, each of these control’s event handlers are triggered and the textboxes text are changed. So far so good.

But why doesn't the Routed event bubble up when Mouse Wheel is rotated??

To understand this, you need to know why Routed event bubbled up when MouseEnter event fired in the first case.

If you notice in MainWindow.xaml file, you will see that I have set the MouseDown event in both the parent controls i.e. Window and StackPanel. The MyCustomClick event of the MyCustomControl is the Routed Event which is raised when Custom_MouseClick() handler is triggered, which is again when the MouseDown event is raised. So, it is evident that the same event is routed up along the Visual tree. If it’s a MouseDown event, then only the MouseDown event will bubble up and hence, only the MouseDown handlers of all the parent Controls will be triggered.

In the Mouse Wheel event case, you will notice that it’s the MouseWheel event that is getting fired in the Custom Control, but no MouseWheel event handler is set in the parent controls like StackPanel and Window. Hence this MouseWheel event is not handled anywhere except the originating control which is TextBlock because it already has defined Mouse Wheel event handler.

You can in fact set the Mouse wheel event handler in both StackPanel and Window controls and check for yourself the real fun. It's your homework folks!!! 😊

If at any point in time, you want to stop the routed event at any particular level, then you will need to set the e.Handled = true;

Let’s change the StackPanel_Click event as shown below,

private void StackPanel_Click(object sender, RoutedEventArgs e)
{
txt2.Text = "Only the Click event is bubbled to Stack Panel";
e.Handled = true;
}

When you click on the TextBlock, you will observe that the click event will not be routed to the Window and will stop at the StackPanel and the third text block will not be updated.

WPF

Do write to me if you have any questions.