Routed Events

WPF gives us a number of different mechanisms for handling events – they are bubbling, tunneling, and direct. These are all known as Routed events.

Direct event

You are probably already used to the direct routed event. This is where the item itself handles the event that occurred A good example would be handling he "onClick" event of a mouse button in standard WinForms. This is where the event is raised in the GUI item and gets handled by said GUI element.

Bubbling Event

Now we all like some bubbles in one form or another. Bubbling happens when the event is not handled by the element (say a textbox) and the event "bubbles" its way up the UI containers which hold it. For example, let's say you have a window that contains a panel and inside that panel you have a grid and inside the grid you have a textbox. If the event is not handled by the textbox, then it moves, is passed or "bubbles" up to the grid level (as the grid contains the textbox), if it is not handled at that level then the event bubbles further up the "tree" (known as a visual tree) to the panel where it may or may not be handled. This process continues until it is handled or the event "escapes" the top most element.
Examples of a bubbling event would be something like a "MouseButtonDown" event. Or a "Keydown" event.

Tunneling

It would probably surprise your cotton white socks off that Tunneling is the opposite of Bubbling. So instead of an event going "up" the visual tree, the event travels down the visual tree toward the element that is considered the source. The standard WPF naming definition of a tunneling event is that they all start with "preview" for example "previewdownkey" and "previewmousebuttondown". You can catch them on their way to the "target" element and handle it. An example for this might be perhaps you have some controls inside a grid control and for some reason you have decided that no control within that grid will be allowed to have the letter "t" reach it.

Event Pairing

Most of the bubbling events are paired with a Tunneling event. For example, the PreviewKeyDown (tunneling) key event is paired with the Keydown event (bubbling).

E.g.:

• PreviewMouseDown is paired with MouseDown
• PreviewMouseWheel is paired with MouseWheel

Handling the event

Regardless of how you get your event, once you have your hands on it you can tell the event that it has been handled, and prevent it being passed along.
Each type of event handler passes a "RoutedEventArgs" object. Inside this object there is a property called "Handled". Set "Handled" to true and any event handlers further along the visual tree will no longer handle that particular event.
Earlier our example described a tunneling "Keydown" event heading towards a Textbox. If a containing ui element (the window, panel or grid) catches and handles the tunneling event (by setting the Handled property to true) then the Textbox will not receive the event and no matching bubbling event will be kicked off.

How do I catch and handle the event?

 

 

 

 If you examine at the XAML you will see entries for "Keyboard.PreviewKeyDown" and entries for "Keyboard.KeyDown" for each of the containers(except the button itself).

You will also see that each of the controls except the button and textbox has entries for these two events.
private void Window_PreviewKeyDown(object sender, KeyEventArgs e)
{
    MessageBox.Show("Window_PreviewKeyDown");
    //e.Handled = true;
}

private void StackPanel_PreviewKeyDown(object sender, KeyEventArgs e)
{
    MessageBox.Show("StackPanel_PreviewKeyDown");
    //e.Handled = true;
}

private void Grid1_PreviewKeyDown(object sender, KeyEventArgs e)
{
    MessageBox.Show("Grid1_PreviewKeyDown");
    //e.Handled = true;
}

private void Grid1_KeyUp(object sender, KeyEventArgs e)
{
    MessageBox.Show("Grid1_KeyUp");
    //e.Handled = true;
}

private void StackPanel_KeyUp(object sender, KeyEventArgs e)
{
    MessageBox.Show("StackPanel_KeyUp");
    //e.Handled = true;
}

private void StackPanel_KeyDown(object sender, KeyEventArgs e)
{
    MessageBox.Show("StackPanel_KeyDown");
    //e.Handled = true;
}

private void Grid1_KeyDown(object sender, KeyEventArgs e)
{
    MessageBox.Show("Grid1_KeyDown");
    //e.Handled = true;
}

private void Window_KeyDown(object sender, KeyEventArgs e)
{
    MessageBox.Show("Window_KeyDown");
    //e.Handled = true;
}


In the code we see that each event handler will pop up a messagebox telling us where the message currently sits.
Build and run the application, click in the textbox - nothing will appear to happen.
Keep the focus on the window and press a key on your keyboard. Message boxes will appear as you clear each one.
The order they appear is;
Window_PreviewKeyDown -> StackPanel_PreviewKeyDown -> Grid1_PreviewKeyDown -> Grid1_KeyDown -> StackPanel_KeyDown -> Window_KeyDown
As you can see the tunneling events displayed first, then the bubbling events second. Hurray!

Handling the event

The next stage is to Handle the event. In each function you will see I have included the following (commented out) code;

e.Handled = true;

Your next exercise, dear reader, is to uncomment out the line in 
        StackPanel_PreviewKeyDown so that the code looks like the following;

private void StackPanel_PreviewKeyDown(object sender, KeyEventArgs e)
{
    MessageBox.Show("StackPanel_PreviewKeyDown");
    e.Handled = true;
}

Build and run the application - what change in behaviour do you see?
Comment it back out and play around with the equivalent code  in the remaining sections. This should give you a good idea of how and when the events bubble or tunnel.