Creating Custom WPF Controls

The advent of any new programming model generates a great deal of excitement, and the Windows Presentation Foundation (WPF) is no exception. This powerful UI framework provides a plush set of controls to construct rich user experiences. The controls provided within this coding quiver will help you hit the mark for the majority of your UI targets.

Occasionally, you will come across a development requirement that you have not previously encountered. When this occurs, the need for a custom control may arise. A custom control generally involves melding a collection of standard controls together to address the needs of a specific task. Think of a custom control as one of the drag-and-drop UI components often used to develop ASP.NET and Windows Forms applications within Visual Studio. The primary benefit of creating a custom control is that it opens the door for reuse.

The remainder of this article walks you through the process of creating a custom control within WPF. However, it is not meant to be an introduction to XAML or WPF. For an introduction to XAML and WPF, please refer to the Windows SDK documentation for .NET 3.0.

Meet Your Custom Control

User-generated ratings have become commonplace amongst both media players and community-based Web sites. This article walks through the process of using WPF to create a simple, reusable rating control. By the end, you will have a valuable control that looks like this:

Before diving into the implementation, make sure that your system has the .NET 3.0 runtime components and Windows SDK. If you would like just to experiment with Extensible Application Markup Language (XAML), Lorin Thwaits has posted a great article on his blog to help you get started with WPF quickly.

Getting Started

In WPF, all projects must include a project file. The project file is composed entirely of XML. For custom controls, the outputType element is of particular interest. This element must have the value set to “library”. In general, Visual Studio 2005 automatically creates the project file for you, provided you have the necessary Visual Studio extensions installed. If you are creating a project file from scratch, Microsoft has provided an example on its MSDN site.

Control Design

After the project itself has been created, the next step is to add your XAML pages. In general, the code for your control will reside within a single XAML file. By using a project file, you easily can add additional controls and create a custom control library that will allow for easy distribution of multiple custom controls.

For the rating control, you will use the following XAML:

<UserControl x_Class=”CustomControlLibrary.RatingUserControl”

   xmlns_x=”http://schemas.microsoft.com/winfx/2006/xaml” Tag=”Rating”>

   <UserControl.Resources>

      <Style x_Key=”UnselectedStyle” TargetType=”{x:Type Ellipse}”>

         <Setter Property=”Width” Value=”16″ />

         <Setter Property=”Height” Value=”16″ />

         <Setter Property=”Stroke” Value=”Black” />

         <Setter Property=”StrokeThickness” Value=”0″ />

         <Setter Property=”Fill”>

            <Setter.Value>

               <LinearGradientBrush>

                  <LinearGradientBrush.GradientStops>

                     <GradientStopCollection>

                        <GradientStop Color=”#F02821″ Offset=”0.05″ />

                        <GradientStop Color=”#71130F” Offset=”0.95″ />

                     </GradientStopCollection>

                  </LinearGradientBrush.GradientStops>

               </LinearGradientBrush>

            </Setter.Value>

         </Setter>

      </Style>

      <Style x_Key=”SelectedStyle” TargetType=”{x:Type Ellipse}”>

         <Setter Property=”Width” Value=”16″ />

         <Setter Property=”Height” Value=”16″ />

         <Setter Property=”Stroke” Value=”Black” />

         <Setter Property=”StrokeThickness” Value=”0″ />

         <Setter Property=”Fill”>

            <Setter.Value>

               <LinearGradientBrush>

                  <LinearGradientBrush.GradientStops>

                     <GradientStopCollection>

                        <GradientStop Color=”#1AE700″ Offset=”0.05″ />

                        <GradientStop Color=”#074300″ Offset=”0.95″ />

                     </GradientStopCollection>

                  </LinearGradientBrush.GradientStops>

               </LinearGradientBrush>

            </Setter.Value>

         </Setter>

      </Style>

   </UserControl.Resources>

   <StackPanel Name=”EllipsesStackPanel” Orientation=”Horizontal”

               MouseLeave=”OnMouseLeave”>

      <Ellipse Name=”Ellipse1″ Style=”{StaticResource UnselectedStyle}”

               MouseLeftButtonUp=”OnMouseLeftButtonUp”

               MouseEnter=”OnMouseEnter” />

      <Ellipse Name=”Ellipse2″ Style=”{StaticResource UnselectedStyle}”

               MouseLeftButtonUp=”OnMouseLeftButtonUp”

               MouseEnter=”OnMouseEnter” />

      <Ellipse Name=”Ellipse3″ Style=”{StaticResource UnselectedStyle}”

               MouseLeftButtonUp=”OnMouseLeftButtonUp”

               MouseEnter=”OnMouseEnter” />

      <Ellipse Name=”Ellipse4″ Style=”{StaticResource UnselectedStyle}”

               MouseLeftButtonUp=”OnMouseLeftButtonUp”

               MouseEnter=”OnMouseEnter” />

      <Ellipse Name=”Ellipse5″ Style=”{StaticResource UnselectedStyle}”

               MouseLeftButtonUp=”OnMouseLeftButtonUp”

               MouseEnter=”OnMouseEnter” />

   </StackPanel>

</UserControl>

By separating the UI from the procedural code, you quickly can use SDK tools such as XAMLPad to preview what the control will look like without having to compile it. By removing the need for compilation, you quickly can receive feedback from your end users by designing the user interface right in front of them and saving the implementation details for a later time.

An interesting point about custom controls is that their root elements are usually the UserControl element. This element provides the simplest means for creating a custom control. If you would like to provide developers with the added functionality of templates (or skins), your control MUST derive from the Control class.

Also, WPF provides a unified user experience development platform, meaning a WPF control that works within your Windows applications can also work within your Web applications that use WPF. The only difference is the security mode within which they run. Please refer to the Windows SDK for further information on security modes.

Interaction Implementation

When developing a custom control, you have to go beyond developing just the look of the control. You also must decide how an end user can interact with the control. When determining the user interaction implementation, you have to consider the functionality you want your control to provide and consider how you believe your end users would want to drive this functionality. In the event of the control, you are basing the design on something that already is familiar to users.

Once you have the functionality defined, you can begin taking this functionality and converting it into collections of controls and events. For the rating control, you use five ellipse elements, one for each rating. For each of these rating elements, you will implement the user’s interactions through the following events:

In addition to handling events, it is important to commit to your developer audience. Because of this, you also must decide which functionality and properties you will allow other developers to access. In the case of the rating control, providing a hook into the rating that the user selected seems beneficial. Because of this, provide a rating property that other developers can use to access the control:

using System;
using System.Collections.Generic;
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 CustomControlLibrary
{
   /// <summary>
   /// Interaction logic for RatingUserControl.xaml
   /// </summary>
   public partial class RatingUserControl :
      System.Windows.Controls.UserControl
   {
      public RatingUserControl()
      {
         InitializeComponent();
      }
      // The selected rating within the control
      private int rating = 0;
      /// <summary>
      /// The selected rating within the control
      /// </summary>
      public int Rating
      {
         get { return rating; }
         set { rating = value;}
      }
      /// <summary>
      /// Handles the user clicking a rating element (an ellipse)
      /// </summary>
      public void OnMouseLeftButtonUp(object sender, RoutedEventArgs e)
      {
         // The last value of the name of the object represents the rating
         string selectedEllipseName = ((Ellipse)(e.Source)).Name;
         string selectedRating =
            selectedEllipseName.Substring(selectedEllipseName.Length-1);
         // Convert the rating to an int
         rating = Convert.ToInt32(selectedRating);
      }
      /// <summary>
      /// Handles the user entering the boundaries of a rating
      /// element (an ellipse)
      /// </summary>
      public void OnMouseEnter(object sender, RoutedEventArgs e)
      {
         // Store the name of the ellipse that the user is over and
         /// create a flag.
         string selectedEllipseName = ((Ellipse)(e.Source)).Name;
         bool found = false;
         // Iterate through the child ellipses and set the rating
         // based on the currently selected ellipse. It is assumed
         // that the children will always be ellipses.
         foreach (UIElement child in EllipsesStackPanel.Children)
         {
            // Set the style of the ellipse accordingly
            if (found == true)
               ellipse.Style = (Style)(this.Resources["UnselectedStyle"]);
            else
               ellipse.Style = (Style)(this.Resources["SelectedStyle"]);
            // Determine if this is the ellipse the user is currently
            // hovering over.
            if (ellipse.Name == selectedEllipseName)
               found = true;
         }
      }
      /// <summary>
      /// Handles the user leaving the boundaries of a rating
      /// element (an ellipse)
      /// </summary>
      public void OnMouseLeave(object sender, RoutedEventArgs e)
      {
         // Determine which entry you want to stop at
         string previousRating = "Ellipse" + rating;
         bool found = false;
         // Iterate through the child ellipses and set the rating
         // based on the currently selected ellipse. It is assumed
         // that the children will always be ellipses.
         foreach (UIElement child in EllipsesStackPanel.Children)
         {
            // Set the style of the ellipse accordingly
            Ellipse ellipse = (Ellipse)(child);
            if ((found == true) || (rating == 0))
               ellipse.Style = (Style)(this.Resources["UnselectedStyle"]);
            else
               ellipse.Style = (Style)(this.Resources["SelectedStyle"]);
            // Determine if you have found what you were looking for
            if (ellipse.Name == previousRating)
               found = true;
         }
      }
   }
}

Much like user controls from previous .NET UI components, you have the ability to implement a code-behind class; this enables you to separate the procedural code from the user experience implementation. The custom class derives from System.Windows.Controls.UserControl. The rest of the implementation will be familiar to .NET developers. This familiarity makes WPF development great!

Testing

To test the custom control, you need to create a wrapper application. The purpose of the wrapper application is to test the complete control conclusively, including the following:

• User experience: XAMLPad is a great tool for testing the layout and appearance of controls. However, it lacks the ability to test user interaction because the event handling is implemented within the code-behind.
• Data binding: It is possible that through the programmatic handles (the methods and properties) another developer may render the control differently based on data from a data source. For instance, you may want to display the rating the user previously entered.

The Custom Controls of Your Dreams

The source code for this practical example provides the framework for developing the custom controls of your dreams, and in the case of the example, the rating control of your dreams. With the combination of the powerful user experience provided by WPF and the productivity of reusing custom controls, it has become easier than ever to fulfill your end users’ application desires.

Download the Code

Download the code for this article (3 Kb).

Acknowledgement

This article was edited by Rachel Wireman.

About the Author

Chad Campbell (MCSD, MCTS) is a solutions developer for mid- to large-sized organizations. He is a thought leader with Crowe Chizek in Indianapolis, Indiana. Chad specializes in Web-based solutions, Reach him at cacampbell@crowechizek.com.