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:

Event Description
MouseLeftButtonUp Simulates a completed click. The API for the ellipse does not provide a Click event.
MouseEnter Determines which ellipses should be selected.
MouseLeave Determines which ellipses should be selected.

More by Author

Get the Free Newsletter!

Subscribe to Data Insider for top news, trends & analysis

Must Read