Bubbling and Tunneling Routing Strategies

DevToolsGuy / Wednesday, June 19, 2013

A routed event is an event that can invoke handlers on several listeners in an element tree, rather than only on the object which raised the event.

In simple words, routed events are, basically, events sent (which means routed) from one control to another, through the control hierarchy.

Each routed event has a routing strategy associated with it, the purpose of which is to tell the routed event where it should be routed to and in what way.

In WPF, routed events use one of the following three routing strategies:

  • Bubbling: Here, event handlers on the event source are invoked. The routed event then routes or bubbles up to successive parent elements one by one until it reaches the element tree root. The bubbling routing strategy is the most commonly used strategy.
  • Examples of a bubbling event would be something like a MouseButtonDown event. Or a KeyDown event.
  • Direct: Here, only the source element itself is given the opportunity to invoke handlers in response. This behavior is similar to a normal .NET event.
  • Tunneling: In the beginning, event handlers at the element tree root are invoked. The routed event then traverses through successive child elements along the route, towards the node element that is the routed event source (the element that raised the routed event).

Bubbling routed events are typically used to notify input or state changes from distinct controls or other UI elements whereas tunneling routed events are frequently used or handled as part of the compositing for a control. This means that events from composite parts can be deliberately suppressed or replaced by events that are specific to the complete control.

Input events provided in WPF often come implemented as a tunneling/bubbling pair. Tunneling events are also sometimes referred to as Preview events, because of a naming convention that is used for the pairs.

All bubbling events are routed events but not all routed events bubble.

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).

For example, the following is a snapshot of the events defined in the UIElement class from MSDN:

As you can observe, for the KeyDown event, there is a corresponding Preview event: PreviewKeyDown, which is a tunneling event. This is an example of an event pair of a bubbling and a tunneling event.

As you can see from the MSDN page for this event, there is a table explaining the details of this event, which also indicates whether the event is a bubbling one or tunneling one. 

Handling the Event

When a routed event is encountered it is important to notify the event that it is being handled and that it need not be passed along any further. Each type of event handler passes an object of type RoutedEventArgs, inside which is a property called Handled.

You need to set this Handled property to true. Once this is done, any other event handlers further present on the visual tree will not handle that event.

Tunneling events can be useful for handling events on elements that you have not created yourself, and hence have no easy way to add an event handler to. Tunneling makes sense if you want the actual targeted element to be the last that receives the event.

Consider that on your UI, you have a list box control with one of its items containing a text box. Clicking the textbox will end up consuming the click, however the list box will not be selected at all.

In this case, if you define the tunneled or preview mouse click event, you can select the list box first, leaving it unhandled and then the click on the text box is handled. This way, you ensure that the list box will be selected, and at the same time, have the click on the text box handled in the event handler.