#600 – Registering a Routed Event

When you implement a routed event in a class, you end up creating an instance of the RoutedEvent type.

Instead of explicitly creating the RoutedEvent instance, you create it indirectly by calling EventManager.RegisterRoutedEvent.  This method accepts some information about the routed event that you want to create and returns an instance of a RoutedEvent, which you typically store in a static field.  You typically register the event in your static constructor, or at the time that it is declared, so you end up having only one instance of the RoutedEvent, no matter how many instances of your class get created.

        // Define/create the routed event object
        public static readonly RoutedEvent ClickEvent = EventManager.RegisterRoutedEvent("Click", RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(ButtonBase));

RegisterRoutedEvent takes the following parameters:

  • name – the name of the event
  • routingStrategy – the routing strategy–tunneling, bubbling or direct
  • handlerType – the delegate type for event handlers
  • ownerType – the class type for the event’s owner
Advertisements

#599 – A Complete Example of a Routed Event

To help you understand how routed events in WPF work, it’s helpful to look at how they are implemented.  Here is all of the relevant code from the ButtonBase class for the Click event.

    public abstract class ButtonBase : ContentControl, ICommandSource
    {
        // Define/create the routed event object
        public static readonly RoutedEvent ClickEvent = EventManager.RegisterRoutedEvent("Click", RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(ButtonBase));

        // CLR event wrapper, adds/removes handlers
        public event RoutedEventHandler Click { add { AddHandler(ClickEvent, value); } remove { RemoveHandler(ClickEvent, value); } }

        // Method used internally to fire the Click event
        protected virtual void OnClick()
        {
            RoutedEventArgs newEvent = new RoutedEventArgs(ButtonBase.ClickEvent, this);
            RaiseEvent(newEvent);
        }
    }

Both the AddHandler and RaiseEvent methods are defined in UIElement.

#598 – Three Flavors of Routed Events

In WPF, every routed event will adopt one of three different routing strategies:

  • Bubbling – the event propagates up the hierarchy of elements in the user interface
  • Tunneling – the event propagates down the hierarchy of elements
  • Direct – the event fires on the source element, but does not propagate

Routed events that are part of the WPF class libraries will have one of these three routing strategies.  For example:

  • ButtonBase.Click is a bubbling event
  • UIElement.PreviewKeyDown is a tunneling event
  • UIElement.MouseEnter is a direct event

When you define your own routed events, you can also specify one of these routing strategies for the event.

#594 – Routed Events Under the Covers

Traditional CLR events are basically a wrapper around a private instance of a multicast delegate type.  When you add an event handler using the += operator, your handler gets added to the delegate’s invocation list.

// CLR event under the covers
private EventHandler barked;
public event EventHandler Barked
{
    add { barked += value; }
    remove { barked -= value; }
}

Routed events in WPF look like standard CLR events because they are exposed via a CLR event.  But they are implemented differently.

When you use += for a routed event, the UIElement.AddHandler method is called.

    // From ButtonBase.cs
    public static readonly RoutedEvent ClickEvent;
    public event RoutedEventHandler Click { add { AddHandler(ClickEvent, value); } remove { RemoveHandler(ClickEvent, value); } }

The AddHandler method adds information about both the event and the handler to list of event handlers that is stored within the UIElement, used when the event is raised.

#593 – AddHandler Method Can Add Handler for Any Event

If you’re adding an event handler from code, rather than specifying the handler in XAML, you can just use the += notation for an event that is defined for the control in question.  For example, the Button control defines a Click control, so you can do the following:

myButton.Click += new RoutedEventHandler(Button_Click);

But let’s say that you want to add a handler for the Click event to a StackPanel control, which does not define the Click event, and you want to do it from code.  You can then use the AddHandler syntax:

myStackPanel.AddHandler(ButtonBase.ClickEvent, (RoutedEventHandler)HandleTheClick);

Notice that the AddHandler method accepts any routed event type as its first parameter.  This means that any UIElement instance can call its AddHandler method to indicate that it wants to handle any routed event.  Even though StackPanel doesn’t define a Click event, it can handle the Button’s Click event.

#592 – Adding an Event Handler in Code

You typically specify handlers for routed events in XAML:

        <Button Content="Like" Click="Button_Click"/>

You then add the code for the handler in your code-behind:

        private void Button_Click(object sender, RoutedEventArgs e)
        {
            MessageBox.Show("Click");
        }

You can also add the handler from code. Adding a handler to the Button control for the  Click event requires that you give the Button control a name that you can then reference from your code-behind.

        <Button Name="myButton" Content="Like"/>

You can then add a handler by using the += operator on the event for which you want a handler.

myButton.Click += new RoutedEventHandler(Button_Click);

This is equivalent to calling the UIElement.AddHandler method.

            myButton.AddHandler(ButtonBase.ClickEvent, (RoutedEventHandler)Button_Click);

#591 – You Can Attach Any Routed Event to Any Control

When you attach an event handler to a control, you most typically attach a handler for an event that is defined for that control.  For example, the Button control has a Click event defined.

<Button Content="Like" Click="Button_Click"/>

In WPF, however, you can actually attach any routed event to any control–whether or not that control defines the event or not.  For example, we can attach a handler for the Click event to a StackPanel object, using the full name for the ButtonBase.Click event.

A control won’t normally fire events that it doesn’t define, except that when events are routed, they can fire on every control higher up (or down) in the logical tree.

    <StackPanel ButtonBase.Click="StackPanel_Click">
        <Button Content="Like" Click="Button_Click"/>
    </StackPanel>

Now, when you click on the Button, both handlers that you define will see the Click event, because it bubbles up the logical tree.