#604 – Defining a New Routed Event

You can create a new routed event in your own class, typically in a control.  Here, we define a new event named RightDrag in the MyButton class, which derives from Button.

Define a static object of type RoutedEvent.

public static readonly RoutedEvent RightDragEvent;

In the static constructor, register the event and set the RoutedEvent object.

        static MyButton()
        {
            RightDragEvent = EventManager.RegisterRoutedEvent("RightDrag", RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(MyButton));
        }

Define a CLR event of type RoutedEventHandler or one of its subtypes.  Call the AddHandler/RemoveHandler methods.

        public event RoutedEventHandler RightDrag
        {
            add { AddHandler(RightDragEvent, value); }
            remove { RemoveHandler(RightDragEvent, value); }
        }

Add a helper method to fire the event.

        protected virtual void OnRightDrag()
        {
            RoutedEventArgs evargs = new RoutedEventArgs(RightDragEvent, this);
            RaiseEvent(evargs);
        }

Finally, fire your event when appropriate.

        void MyButton_MouseMove(object sender, System.Windows.Input.MouseEventArgs e)
        {
            if (e.RightButton == MouseButtonState.Pressed)
                OnRightDrag();
        }

#603 – Sender, Source and OriginalSource Example

Event handlers for routed events in WPF will have access to three different user interface elements within the handler:

  • sender – the element that raised the event
  • e.Source – element where the event originated
  • e.OriginalSource – original low-level element where the event originated (e.g. sub-element in a control)

Suppose that we have the following logical tree:

    <StackPanel Orientation="Vertical" UIElement.MouseMove="StackPanel_MouseMove">
        <Button Content="Move Mouse Over Me" MouseMove="Button_MouseMove"/>
    </StackPanel>

When we move the mouse over the text on the Button, the MouseMove event fires, first on the Button itself and then on the StackPanel (because MouseMove is a bubbling event).  Here are the values of the three fields when you handled each of these events:

  • MouseMove fires on the Button
    • senderButton
    • SourceButton
    • OriginalSource = TextBlock (the TextBlock that is a child control of the Button)
  • MouseMove fires on the StackPanel
    • senderStackPanel
    • Source = Button
    • OriginalSource = TextBlock

#602 – Accessing Information in RoutedEventArgs

All predefined routed events in WPF are declared as instances of a delegate type that passes back either an instance of RoutedEventArgs or of some subclass of RoutedEventArgs.

public delegate void RoutedEventHandler(object sender, RoutedEventArgs e);

The RoutedEventArgs type includes the following properties, which you can make use of in your event handlers:

  • Handled – has event been handled yet?
  • OriginalSource – original low-level element where the event originated (e.g. sub-element in a control)
  • RoutedEvent – an instance of the associated routed event
  • Source – element where the event originated

Note that if the event is bubbling or tunneling, the Source property will refer to the element where the event originated, while the sender parameter will refer to the element that raised the event.  If the event is bubbling or tunneling, this element may be higher up the logical tree than the source element.

#601 – The RoutedEventHandler Delegate Type

In the example showing the implementation of the ButtonBase.Click routed event, you’ll notice that the Click event is declared as a standard CLR event whose type is the RoutedEventHandler delegate type.

If we look at RoutedEventHandler, we see that it has this signature:

public delegate void RoutedEventHandler(object sender, RoutedEventArgs e);

In WPF, many routed events have this signature and others declare a new delegate type that passes back a subclass of RoutedEventArgs.  For example, UIElement.KeyDown has a delegate type of KeyEventHandler, which has the following signature:

public delegate void KeyEventHandler(Object sender, KeyEventArgs e)

The KeyEventArgs type inherits from RoutedEventArgs (indirectly), adding some properties that make sense for key press events.

So event handlers for predefined routed events in WPF will normally be passed either an instance of RoutedEventArgs or an instance of a type that inherits from RoutedEventArgs.

#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

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

#597 – Naming Conventions for Event Handlers

It’s customary to use the following convention when naming event handlers:

objectName_EventName

For example, if you were attaching a handler for the Click event to a Button and the button was labeled “Like”, you might name the handler btnLike_Click.

    <StackPanel>
        <Label Content="Tractors"/>
        <Button Content="Like" Click="btnLike_Click"/>
    </StackPanel>

Even though the Button control isn’t actually named, you can still use meaningful control names when naming event handlers.  In the example above, I’ve used a the “btn” three-letter prefix to refer to a Button.  Some other common control prefixes for naming purposes are:

  • cbo – ComboBox
  • chk – CheckBox
  • cnv – Canvas
  • dg – DataGrid
  • lbo – ListBox
  • lbl – Label
  • mnu – Menu
  • sp – StackPanel
  • tbl – TextBlock
  • txt – TextBox
  • win – Window

#596 – Using Lamba Expressions When Declaring Event Handlers

When you attach an event handler to an event in WPF, you can use several different types of syntax for specifying the method that will serve as a handler.  This includes using both anonymous methods and lambda expressions.

Below are some examples of declaring an event handler using a lambda expression.

            // Use lambda expression to specify handler
            myButton.Click += (object s, RoutedEventArgs e) => Trace.WriteLine("Hey, you clicked a button");

            // You can omit the parameter types
            myTextBox.KeyDown += (s, e) => Trace.WriteLine("KEY pressed");

            // Expression can include a block of code
            myTextBox.KeyUp += (s, e) =>
                {
                    Trace.WriteLine("KEY released!");
                    Trace.WriteLine(string.Format("Key is {0}", e.Key));
                };

#595 – Syntax Choices for Defining an Event Handler

There are several different syntaxes that you can use when specifying an event handler in code.  (This is assuming that you’re using a CLR event wrapper, rather than calling UIElement.AddHandler directly).

The most common syntax for defining an event handler is to declare a new instance of the appropriate handler type, passing it the name of a preexisting method.  Since the handler type is a delegate, you’re passing the name of a method to the delegate’s constructor.

myButton.Click += new RoutedEventHandler(myButton_Click);
myTextBox.KeyDown += new KeyEventHandler(myTextBox_KeyDown);

As a shortcut, you can just use the name of the method (your handler).

myButton.Click += myButton_Click;
myTextBox.KeyDown += myTextBox_KeyDown;

Instead of defining a separate method, you can just specify an anonymous method, with or without arguments.

            myButton.Click += delegate { Trace.WriteLine("Hey, you clicked a button"); };
            myTextBox.KeyDown += delegate(object sender, KeyEventArgs e) { Trace.WriteLine(string.Format("sender: {0}", sender)); };