Tuesday, January 10, 2012

7 Mistakes Developers make when implementing Windows Phone Custom Controls

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,ItemsControlContentControl, 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.

User Control: a reusable control that combines existing controls and can implement its own logic.  User-Controls can be reused but  cannot be skinned or themed.
Custom Control: skinable, themable and reusable controls that once created can be used by simply loading the assembly in any project.
Good for static layout
Good for dynamic layout
Easier to create
Harder to create
Usually used to compose a set of existing controls
Usually used to create a new control
Usually used to allow reusability on a larger scale
Usually used to allow reusability on a smaller scale
Provides less flexibility
Provides greater flexibility (ex: the control template can be replaced with a completely different one)
Does not require  too much knowledge of Silverlight UI model
Requires better understanding of Silverlight UI model
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 ButtonCheckBoxScrollViewer, 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
42-2For 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">
            <ControlTemplate TargetType="local:MyCustomControl">

where local is your new Custom Control namespace for example:
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.


No comments: