(untagged)

WPF: A Beginner's guide: Part 3 of n

Sacha Barber

0.00/5 (No votes)

11 Mar 2008

An introduction into RoutedEvents / RoutedCommands.

Preface and Thanks

I am a .NET programmer, but a busy one; I do VB.NET and C#, ASP.NET / WinForms / WPF / WCF, Flash, Silverlight, the lot. Basically, I keep my toe in. But when I started writing this article series, I naturally chose my favourite language (which happens to be C#). I since got an email from an individual who requested that I publish this series with source code in VB.NET and C#. I simply stated I didn't have time. So this individual (Robert Ranck) volunteered to help out and do the translation to VB.NET based on my original C# projects.

So for that and the subsequent VB.NET projects that you will find here, I ask you to thank Robert Ranck. Cheers Robert, your contributions will surely make this series more open to all .NET developers.

Introduction

This article is the third in my series of beginner's articles for WPF. In this article, we will discuss two important parts of WPF development, RoutedEvents and RoutedCommands. The proposed schedule for this series will still be roughly as follows:

Layout
XAML vs. Code / Markup Extensions and Resources (previous article)
Commands and Events (this article)
Dependancy Properties
DataBinding
Styles/Templates

In this article, I'm aiming to cover a brief introduction into the following:

RoutedEvents; what they are, how they work, how to consume/create them
RoutedCommands; what they are, how they work, how to consume/create them
Automation Peers
Demo Applications

RoutedEvents

What they are

Routed events are a new concept to most developers. In good old fashioned .NET 1.x/2.0, we all probably used some custom events or hooked some delegates onto some existing event, such as:

private System.Web.Forms.Button button1;
button1.click+=new EventHandler(button1_Click);
...
private void button1_Click(object sender, EventArge e)
{
    //Click Event seen, so something about it
}

This is all well and good, right? The System.Web.Forms.Button exposes an OnClick event, which we subscribe to using a standard EventHandler delegate, and we receive the event when the System.Web.Forms.Button raises its internal OnClick event. From here on in, this type of event subscription/notification will be referred to as CLR events. In WPF, things are a little different. There are three types of event notification methods, namely:

Bubbling: Allows events to bubble up the VisualTree (the tree of Visual UI Elements), to the root element.
Tunneling: Allows events to tunnel down the VisualTree.
Direct: Works just like the old .NET 1.x/2.0 CLR events. Only the subscriber gets to see the event.

What actually happens is that when an event is raised, it travels up and down the VisualTree, invoking any handlers that are subscribed to the RoutedEvent. This traversal of the VisualTree will not be the entire tree, but rather the portion of the tree that is directly related to the element that raised the event. Josh smith has an excellent blog entry about this, which you can read right here, should you prefer to look at other resources.

It is fairly common for one logical event to be represented by two actual events, one Tunneling and one Bubbling. There is a naming convention in place to aid in determining how these events were created. Tunneling events usually start with "PreviewXXX" and Bubbling events are usually just XXX. For example, PreviewKeyDown (Tunneling) and KeyDown (Bubbling).

How they work

In order to understand them further, I have provided as part of the overall demo solution (at the top of this article) a project entitled "Part3_RoutedEventViewer" which is a standard WPF application, that when run can be used to examine WPF commands. When the application is launched, it should resemble something like the following:

This little demo application should give you a better understanding of how routed events work. But before I show you a few more screenshots, let's just familiarise ourselves with the application's XAML code, as this is fairly important before I can discuss the routed events, that you'll see.

<Window x:Class="Part3_RoutedEventViewer.Window1"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      Title="Examining Routed Events" 
      Height="300" Width="300"
      WindowState="Maximized">
    <Grid x:Name="gridMain">

        <Grid.Resources>
         //Ommiited for clarity    
        </Grid.Resources>

        <Grid.RowDefinitions>

            <RowDefinition Height="auto"/>
            <RowDefinition Height="auto"/>
            <RowDefinition Height="100*"/>
       </Grid.RowDefinitions>

        <StackPanel Orientation="Horizontal" 
                  HorizontalAlignment="Left">
            <Button x:Name="btnTop" Margin="10" Padding="2" 
                Content="Examining Routed Events" Height="auto"/>
            <Button x:Name="btnClearItems" Margin="10" Padding="2" 
                Content="Clear Items" Height="auto" 
                Click="btnClearItems_Click"/>

        </StackPanel>

        <ListView x:Name="lvResults" Margin="0,0,0,0" 
                IsSynchronizedWithCurrentItem="True" Grid.Row="2" >
                <ListView.View>
                    <GridView ColumnHeaderContainerStyle=
                                    "{StaticResource headerContainerStyle}" >
                        <GridViewColumn  Header="RoutedEventName" Width="150" 
                          CellTemplate="{StaticResource RoutedEventNameTemplate}"/>
                        <GridViewColumn  Header="SenderName" Width="100" 
                          CellTemplate="{StaticResource SenderNameTemplate}"/>
                        <GridViewColumn  Header="ArgsSource" Width="100" 
                          CellTemplate="{StaticResource ArgsSourceTemplate}"/>
                        <GridViewColumn  Header="OriginalSource" Width="100" 
                          CellTemplate="{StaticResource OriginalSourceTemplate}"/>
                </GridView>
                </ListView.View>
        </ListView>
    </Grid>
</Window>

And the C# code-behind is very simple; it basically just subscribes to a whole bunch of Tunneling and Bubbling RoutedEvents.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Data;
using System.Windows.Documents;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Imaging;
using System.Windows.Navigation;
using System.Windows.Shapes;

namespace Part3_RoutedEventViewer
{
    /// <summary>
    /// Demo application that displays some data about the events 
    /// that were recieved by a users actions. Which allows users
    /// to see the difference between tunneling/routed events
    /// </summary>
    public partial class Window1 : Window
    {
        #region Ctor
        /// <summary>
        /// Wires up several of the standard <see cref="FrameworkElement">
        /// FrameworkElement</see> Tunneling/Bubbling
        ///    <see cref="RoutedEvent">RoutedEvents</see>.
        /// This demo also displays some data
        /// about the events that were recieved by
        /// a users actions.
        /// </summary>
        public Window1()
        {
            InitializeComponent();
            UIElement[] els = { this, gridMain, btnTop, lvResults };
            foreach (UIElement el in els)
            {
                //keyboard
                el.PreviewKeyDown += GenericHandler;
                el.PreviewKeyUp += GenericHandler;
                el.PreviewTextInput += GenericHandler;
                el.KeyDown += GenericHandler;
                el.KeyUp += GenericHandler;
                el.TextInput += GenericHandler;

                //Mouse
                el.MouseDown += GenericHandler;
                el.MouseUp += GenericHandler;
                el.PreviewMouseDown += GenericHandler;
                el.PreviewMouseUp += GenericHandler;

                //Stylus
                el.StylusDown += GenericHandler;
                el.StylusUp += GenericHandler;
                el.PreviewStylusDown += GenericHandler;
                el.PreviewStylusUp += GenericHandler;

                el.AddHandler(Button.ClickEvent, 
                              new RoutedEventHandler(GenericHandler));
            }
        }
        #endregion

        #region Private Methods
        /// <summary>
        /// Creates a new <see cref="EventDemoClass">EventDemoClass</see>
        /// to represent the <see cref="RoutedEvent">RoutedEvent</see>.
        /// And adds this new EventDemoClass to the listbox
        /// </summary>
        private void GenericHandler(object sender, RoutedEventArgs e)
        {

            lvResults.Items.Add(new EventDemoClass()
            {
                RoutedEventName = e.RoutedEvent.Name,
                SenderName = typeWithoutNamespace(sender),
                ArgsSource = typeWithoutNamespace(e.Source),
                OriginalSource = typeWithoutNamespace(e.OriginalSource)
            });

        }
        /// <summary>
        /// Returns the type name without the namespace portion
        /// </summary>
        private string typeWithoutNamespace(object obj)
        {
            string[] astr = obj.GetType().ToString().Split('.');
            return astr[astr.Length - 1];
        }

        /// <summary>
        /// Clears the listbox of events
        /// </summary>
        private void btnClearItems_Click(object sender, RoutedEventArgs e)
        {
            lvResults.Items.Clear();
        }
        #endregion
    }

    #region EventDemoClass CLASS
    /// <summary>
    /// A simpy data class that is used to display event data
    /// </summary>
    public class EventDemoClass
    {
        public string RoutedEventName { get; set; }
        public string SenderName { get; set; }
        public string ArgsSource { get; set; }
        public string OriginalSource { get; set; }
    }
    #endregion
}

And here's the VB.NET version:

Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Text
Imports System.Windows
Imports System.Windows.Controls
Imports System.Windows.Data
Imports System.Windows.Documents
Imports System.Windows.Input
Imports System.Windows.Media
Imports System.Windows.Media.Imaging
Imports System.Windows.Navigation
Imports System.Windows.Shapes

    ''' <summary> 
    ''' Demo application that displays some data about the events 
    ''' that were recieved by a users actions. Which allows users 
    ''' to see the difference between tunneling/routed events 
    ''' </summary> 
    Partial Public Class Window1
        Inherits Window
#Region "Ctor"
        ''' <summary> 
        ''' Wires up several of the standard <see cref="FrameworkElement"> 
        ''' FrameworkElement</see> Tunneling/Bubbling
        '''    <see cref="RoutedEvent">RoutedEvents</see>. 
        ''' This demo also displays some data about the events that were recieved by 
        ''' a users actions. 
        ''' </summary> 
        Public Sub New()
            InitializeComponent()
            Dim els As UIElement() = {Me, gridMain, btnTop, lvResults}
            For Each el As UIElement In els

            'key board
            AddHandler el.PreviewKeyDown, AddressOf GenericHandler
            AddHandler el.PreviewKeyUp, AddressOf GenericHandler
            AddHandler el.PreviewTextInput, AddressOf GenericHandler
            AddHandler el.KeyDown, AddressOf GenericHandler
            AddHandler el.KeyUp, AddressOf GenericHandler
            AddHandler el.TextInput, AddressOf GenericHandler

            'mouse
            AddHandler el.MouseDown, AddressOf GenericHandler
            AddHandler el.MouseUp, AddressOf GenericHandler
            AddHandler el.PreviewMouseDown, AddressOf GenericHandler
            AddHandler el.PreviewMouseUp, AddressOf GenericHandler

            'stylus
            AddHandler el.StylusDown, AddressOf GenericHandler
            AddHandler el.StylusUp, AddressOf GenericHandler
            AddHandler el.PreviewStylusDown, AddressOf GenericHandler
            AddHandler el.PreviewStylusUp, AddressOf GenericHandler

            el.AddHandler(Button.ClickEvent, _
                          New RoutedEventHandler(AddressOf GenericHandler))
        Next
        End Sub
#End Region

#Region "Private Methods"
        ''' <summary> 
        ''' Creates a new <see cref="EventDemoClass">EventDemoClass</see> 
        ''' to represent the <see cref="RoutedEvent">RoutedEvent</see>. 
        ''' And adds this new EventDemoClass to the listbox 
        ''' </summary> 
        Private Sub GenericHandler(ByVal sender As Object, ByVal e As RoutedEventArgs)

        Dim eventClass As New EventDemoClass()
        eventClass.RoutedEventName = e.RoutedEvent.Name
        eventClass.SenderName = typeWithoutNamespace(sender)
        eventClass.ArgsSource = typeWithoutNamespace(e.Source)
        eventClass.OriginalSource = typeWithoutNamespace(e.OriginalSource)
        lvResults.Items.Add(eventClass)
    End Sub
    ''' <summary> 
    ''' Returns the type name without the namespace portion
    ''' </summary> 
    Private Function typeWithoutNamespace(ByVal obj As Object) As String
        Dim astr As String() = obj.GetType().ToString().Split(".")
        Return astr(astr.Length - 1)
    End Function
    ''' <summary> 
    ''' Clears the listbox of events
    ''' </summary> 
    Private Sub btnClearItems_Click(ByVal sender As System.Object, _
                                    ByVal e As System.Windows.RoutedEventArgs)
        lvResults.Items.Clear()
    End Sub
#End Region
End Class

#Region "EventDemoClass CLASS"
''' <summary> 
''' A simpy data class that is used to display event data 
''' </summary> 
Public Class EventDemoClass


#Region "Instance Fields"
    Private newRoutedEventName As String
    Private newSenderName As String
    Private newArgsSource As String
    Private newOriginalSource As String
#End Region

#Region "Propeties"
Public Property RoutedEventName() As String
    Get
        Return newRoutedEventName
    End Get
    Set(ByVal value As String)
        newRoutedEventName = value
    End Set
End Property


Public Property SenderName() As String
    Get
        Return newSenderName
    End Get
    Set(ByVal value As String)
        newSenderName = value
    End Set
End Property

Public Property ArgsSource() As String
    Get
        Return newArgsSource
    End Get
    Set(ByVal value As String)
        newArgsSource = value
    End Set
End Property

Public Property OriginalSource() As String
    Get
        Return newOriginalSource
    End Get
    Set(ByVal value As String)
        newOriginalSource = value
    End Set
End Property
#End Region
End Class
#End Region

It can be seen that this Window1.xaml has a VisualTree, which is as follows:

So with this in mind, let me now show you some example screenshots that were generated using this demo project "Part3_RoutedEventViewer".

If we click the Window, we can observe the following events are seen. We only see Window level events; this is due to the Window being the root element in the Visual Tree.

But if we click the actual button (on the left), we can observe the following events are seen, as the Button is a sibling of the Grid, which in turn is a sibling of Window1.

I hope this helps you better understand how RoutedEvents traverse the Visual Tree.

How to consume them

Consuming RoutedEvents is the same as it always was; we can do it in XAML like:

<Button x:Name="btnClearItems" 
   Content="Clear Items" Click="btnClearItems_Click"/>

Of course, you need to have a section of code entitled "btnClearItems_Click" in the code behind, so that the event handler has an actual delegate to a real method.

Alternatively, you can simply subscribe to a RoutedEvent as follows in the code-behind:

Button btn = new Button();
btn.Click += new RoutedEventHandler(btn_Click);
....
....
....
void btn_Click(object sender, RoutedEventArgs e)
{
    //seen event do something
}

And the VB.NET version:

btn.AddHandler(Button.ClickEvent, New RoutedEventHandler(AddressOf btn_Click))
.....
.....
.....
Private Sub GenericHandler(ByVal sender As Object, ByVal e As RoutedEventArgs)
    //seen event do something
End Sub

Or even like this (if you like anonymous delegates):

Button btn = new Button();
btn.Click += delegate(object sender, RoutedEventArgs e) 
{
    //seen event do something  
};

And we can even add directly to the handlers of a UI Element, such as:

Button btn = new Button();
btn.AddHandler(Button.ClickEvent, new RoutedEventHandler(GenericHandler));

Or in VB.NET:

btn.AddHandler(Button.ClickEvent, New RoutedEventHandler(AddressOf GenericHandler))

How to create them

I have attached another demo project (entitled "Part3_RoutedEventsExample") which is part of the overall solution at the top of this article. Within this project, there are two things covered.

How to create and consume a RoutedEvent that uses standard RoutedEventArgs
How to create and consume a RoutedEvent that uses custom RoutedEventArgs

When this application is run, it looks like the following figure:

Where there is a single UserControl placed Window1. The UserControl is responsible for raising two events that Window1 subscribes to. We just discussed the different manners in which to subscribe to RoutedEvents, so I won't dwell on that, but shall instead show you how to raise your own RoutedEvent.

Firstly using standard RoutedEventArgs

The first step is to create and register the event with the EventManager, which is done like this. Note that this is one possible constructor for a RoutedEvent; you should consult the MSDN documentation for others.

//The actual event routing
public static readonly RoutedEvent CustomClickEvent = 
    EventManager.RegisterRoutedEvent(
    "CustomClick", RoutingStrategy.Bubble, 
    typeof(RoutedEventHandler), 
    typeof(UserControlThatCreatesEvent));