#1,074 – Attached Event Syntax

Attached events allow attaching a handler for an event that is defined in an element other than the one adding the handler.  For example, a StackPanel might define a handler for the Click event that is defined in ButtonBase.

When defining handlers in XAML, the event name is used by itself if that event is defined for the element raising the event.

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

When defining a handler on an element that does not define the handler’s event, you prefix the event name with the name of the class that defines the event.

    <StackPanel Button.Click="StackPanel_Button_Click">

#1,073 – Attached Events

When events are routed in WPF, elements up (bubbling) or down (tunneling) the logical tree are given the chance to add a handler for a particular event.

For example, if you have a Button within a StackPanel and the user clicks on the Button, the Button will raise a Click event, but also bubble the event up to the StackPanel so that it can also raise the Click event.

Click is defined as a RoutedEventHandler in the ButtonBase class.  There is also a public static ClickEvent object of type RoutedEvent defined in ButtonBase.  So we think of ButtonBase as “owning” the Click event.  This makes sense, since buttons are generally the elements that will raise Click events.

The StackPanel does not define a Click event, but can define a handler for a routed event object that it does not own.  This is known as an attached event.

#1,066 – Elements Must Be Visible and Enabled to Fire Events

Events fired from user interface elements in WPF are typically routed events, firing events from elements up or down the logical tree after the source element has fired the event.

A user interface element must be both visible (Visibility = Visible) and enabled (IsEnabled = true) in order to fire an event.  If an element is not visible or is disabled, the topmost element beneath the element may fire the event instead.

Below, if we set IsEnabled on the Label to false, its MouseDown event will not fire and the StackPanel will become the source of the event instead.

<Window x:Class="WpfApplication1.MainWindow"
        Title="Events" Width="208" Height="183"

    <StackPanel MouseDown="StackPanel_MouseDown"
                Background="AliceBlue" Margin="10">
        <Label Content="Label" Background="Orange" Margin="10"

When we click on the Label, the StackPanel fires the MouseDown event, followed by the parent Window.



#606 – Reusing an Existing Routed Event in Your Class

When you are defining a new CLR event in a class that will wrap a routed event, you can either register your own new routed event or you can reuse a routed event that already exists in the WPF framework.

To reuse an existing routed event, you call the AddOwner method on the existing event.

    public class MyButton : Button
        public static readonly RoutedEvent MyTextChangedEvent;

        static MyButton()
            MyTextChangedEvent = TextBoxBase.TextChangedEvent.AddOwner(typeof(MyButton));

        public event TextChangedEventHandler MyTextChanged
            add { AddHandler(MyTextChangedEvent, value); }
            remove { RemoveHandler(MyTextChangedEvent, value); }

        protected virtual void OnMyTextChanged()
            TextChangedEventArgs evargs = new TextChangedEventArgs(MyTextChangedEvent, UndoAction.None);

        public MyButton()
            this.Click += new RoutedEventHandler(MyButton_Click);

        void MyButton_Click(object sender, RoutedEventArgs e)
            this.Content = this.Content + ".";

#605 – Using Subclasses of RoutedEventArgs

When you define your own routed event in a class, you raise the event using the UIElement.RaiseEvent method.  The RaiseEvent method accepts an instance of a RoutedEventArgs object.  Notice that this is same class type passed to event handlers that are declared using the RoutedEventHandler delegate type.

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

When firing a routed event, you can choose to use one of the subclasses of RoutedEventArgs, if you have additional information to pass back.

For example, you might declare your event to be of type MouseEventHandler and then pass back an instance of MouseEventArgs when raising the event.

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

        protected virtual void OnRightDrag(MouseEventArgs e)
            MouseEventArgs evargs = new MouseEventArgs(e.MouseDevice, 0);
            evargs.RoutedEvent = RightDragEvent;

#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);

Finally, fire your event when appropriate.

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

#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);

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.