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.
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 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.
1
2
3
4
5
6
7
| 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
1
2
3
4
5
6
7
8
9
| <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:
1
| 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.
