7 Mistakes Developers make when implementing WP Custom Controls

by WindowsPhoneGeek

In this article I am going to talk about 7 common mistakes that developers make when implementing Windows Phone Custom Controls. All of the examples given below are taken from real questions that we were asked or from real Windows Phone projects that we have helped developers with the implementation.

Generally, Custom Controls are skinable, themable and reusable controls that once created can be used by simply loading the assembly in any project.  All controls that are used in Silverlight for Windows Phone 7 (eg., Button, TextBlock, ListBox) and UserControl are also Custom Controls. Usually Custom Controls inherit from Control, ItemsControl, ContentControl, etc.

NOTE: You can also take a look at the following article for reference: Creating a WP7 Custom Control in 7 Steps

Mistake #1: Wrong choice of whether to implement a Custom Control or a UserControl

Generally when talking about Windows Phone controls you have two options: either to implement a User Control or a Custom Control.

Example1: Correct choice  of using Custom Control

Control Description: We want our control to :

• contain a collection of items
• expose ItemsSource
• be easily reusable
• allow automatic sorting, filtering,etc. based on some condition
• have multiple Views/States, i.e. FullScreen mode, Minimized mode, Standard mode, etc.
• allow item selection
• expose custom properties
• be fully customizable

Control Usage: We will use this control multiple times in our application and in several other applications.

Our Comment: In this case we would suggest that you implement a Custom Control that derives from ListBox or optionally directly from ItemsControl. The control will be compiled into a separate assembly (.dll) so that it can be easily reused in other applications as well.

Example2: Incorrect choice of using Custom Control

Control Description: We want our control to:

• have ListBox which will be automatically sorting, filtering,etc based on some condition. For example Button click.
• consists of a ListBox, two Buttons and a TextBlock
• exposes several custom properties
• not necessarily provide great flexibility in appearance customization

Control Usage: We will use this control only a couple of times in a single application.

Our Comment: In this case we would suggest that you implement a UserControl instead of Custom Control because you will use it only a couple of  times in the same project and it will be easier to implement the desired functionality in code behind rather than trying to implement a Custom Control from scratch.

Mistake #2: Deriving from an inappropriate base class

When implementing a Custom Control you need to derive from an appropriate base type . Here are some suggestions:

ItemsControl: When you want to implement a control that has multiple items usually using the ItemsControl is a good choice.

ContentControl: When you want to implement a control that displays a single element (through the Content property), possibly using different templates.

ListBox: When you want to implement a selectable ItemsControl

Control: When there is no other suitable type to derive from.

Controls such as Button, CheckBox, ScrollViewer, etc.: When you want to implement a specific type of control and need some of the properties/method of the parent control.

Mistake #3: Forgetting to set DefaultStyleKey in the constructor

It is very important not to forget to set the DefaultStyleKey in the constructor of your custom control.

NOTE: DefaultStyleKey gets or sets the key that references the default style for the control.

public class MyCustomControl : ContentControl
{
    public MyCustomControl()
    {
        DefaultStyleKey = typeof(MyCustomControl);
    }
}

Mistake #4: Control theme(default Style) in the wrong place

This is one of the most common mistakes that we have seen. In short the base structure of a Custom Control is:

MyCustomControl.cs + Themes/generic.xaml

• MyCustomControl.cs: place the C#/VB code here
• Themes/generic.xaml: place the UI here

NOTE: You must  create a Themes folder(the name is very important) and place the generic.xaml there

For now in Silverlight for Windows Phone Mango there is no suitable VisualStudio Template for adding a XAML file or ResourceDictionary  as a file in your project. So in order to add generic.xaml file you can create a new Class by choosing Add->NewItems->Class  and rename it to generic.xaml.

NOTE: The name is important!

NOTE:It is very important that you remember to set the generic.xaml file's build action to Resource. This is necessary in order  to make sure that the template is packed in the same assembly as the control otherwise the template wont be available.

Mistake #5: generic.xaml defined or used in a wrong way

Example1: Correct

• Themes/generic.xaml
• Build Action: Resource
• ResourceDictionary without any x:Key or x:Name
• include

xmlns:vsm="clr-namespace:System.Windows;assembly=System.Windows" if using any VisualStates

Example2: Incorrect

• /generic.xaml
• Build Action: Content
• ResourceDictionary with x:Key or x:Name

Mistake #6: Wrong Style

The default style and the ControlTemplate of the custom control determine how the control will look like.

When creating the default style(theme) of a Custom Control it is very important to consider the following things:

• You must define a valid ControlTemplate
• Add a valid TargetType
• No x:Key
• No x:Name

Example1: Correct Style

<Style TargetType="local:MyCustomControl">
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="local:MyCustomControl">
               ..
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</Style>

where local is your new Custom Control namespace for example:

xmlns:local="clr-namespace:CustomControlSample"

Example2: Incorrect Style

Here is an example of incorrectly defined Style.

Mistake #7: Using Binding instead of TemplateBinding

TemplateBinding links the value of a property in a control template to be the value of a property on the templated custom control!

Example1: Correct

Example2: Incorrect

In this article I talked about 7 common mistakes that developers make when implementing a Custom Control in Silverlight for Windows Phone.

I hope that the post was helpful.

You can also follow us on Twitter @winphonegeek

Comments

<vsm:VisualStateManager.VisualStateGroups>
...
</vsm:VisualStateManager.VisualStateGroups>

<VisualStateManager.VisualStateGroups>
...
<VisualStateManager.VisualStateGroups>