#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"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Events" Width="208" Height="183"
        MouseDown="Window_MouseDown">

    <StackPanel MouseDown="StackPanel_MouseDown"
                Background="AliceBlue" Margin="10">
        <Label Content="Label" Background="Orange" Margin="10"
               MouseDown="Label_MouseDown"
               IsEnabled="False"/>
    </StackPanel>
</Window>

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

1066-002

1066-001

#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);
            RaiseEvent(evargs);
        }

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

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

#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;
            RaiseEvent(evargs);
        }

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

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