There have been a few postings about creating Dependency Properties for User Controls and Custom Controls in WPF going around the blog world recently but not a lot of talk about how to expose those properties in Expression Blend. I'm assuming part of the reason for this is by default when you create a Dependency Property in the code-behind file for your User Control or Custom Control that property will be available in the Miscellaneous category of the Properties Panel in Expression Blend. When you add your User Control or Custom Control to a project in Expression Blend and add the control to the Art Board, you will see all of the properties for the control appear in the Properties Panel. Expand the Miscellaneous category and you should see the Dependency Property you created. If you mouseover your Dependency Property you will see a tooltip that gives you the name of the property and the type of property you are exposing.
That's amazingly simple but what if you need to:
A) Give your designer more information about the Dependency Property you've created .
B) Group your Dependency Property into a category other than Miscellaneous.
C) "ALL OF THE ABOVE", to give your User Control or Custom Control a polished\professional look when you distribute it.
Well thankfully that is easily accomplished so let's get to it.
**NOTE**
(There have been some great postings on creating Dependency Properties for User Controls and Custom Controls so this posting assumes you already know how to create a Dependency Property and now you want to expose that property or properties to your designer using Expression Blend. If you need some insight on UserControls and Dependency Properties Kirupa has a great 10 page write up here: http://www.kirupa.com/blend_wpf/usercontrols_dependency_properties_pg1.htm).
So, you've created a User Control or Custom Control with Custom Dependency Properties and you want to give your control and it's Custom Dependency Properties a description in Expression Blend beyond the plain old defaults.
The first step is to add a reference to the System.ComponentModel namespace at the top of your code-behind file.
===========================
In VB
Imports System.ComponentModel
===========================
In C#
Using System.ComponentModel;
===========================
The second step is to add your Dependency Property
=========================================
In VB:
Public Shared myStringProperty As DependencyProperty = DependencyProperty.Register("myString", GetType(String), GetType(UserControl1))
========================================
In C#:
public static DependencyProperty myStringProperty = DependencyProperty.Register("myString", typeof(string), typeof(UserControl1));
========================================
The third step is to set a few attributes from System.ComponentModel on your Dependency Property. In this example we're going to use "DisplayName", "Description" and "Category". The names of these attributes pretty much sum up what they do but here is a brief description of each.
DisplayName: If you've given your Dependency Property a cryptic name in the code-behind file for your control you may want to provide a user friendly name in Expression Blend for your designer.
Description: Allows you to give a description of how the property is used. This description will be visible as a tooltip when you mouseover the Dependency Property you've created in the code-behind file for your control.
Category: This specifies the category your Dependency Property will appear in under the Properties Panel in Expression Blend.
There are three basic scenarios when setting the Category attribute that deterime where the Dependency Property you created will appear in the Properties Panel in Expression Blend.
1. Don't set the Category attribute on your Dependency Property. This will place your Dependency Property in the Miscellaneous category in the Properties Panel. This is the default behavior.
2. Set the Category attribute to an existing category in the Properties Panel, such as "Common Properties". Your Dependency Property wil now show up in the Common Properties category.
3. Create your own category. Since the Category attribute is just a string you can make up your own category. When you do this your new category will show up below the Miscellaneous category in the Properties Panel.
Setting the attributes on your Dependency Property:
======================================
In VB:
' This Dependency Property will appear in the Common Properties category in Expression Blend with a Display Name of "My Prop"
<Description("This is the Description for myString Custom Dependency Property"), Category("Common Properties"), DisplayName("My Prop")> _
Public Property myString() As String
Get
Return CType(GetValue(myStringProperty), String)
End Get
Set(ByVal value As String)
SetValue(myStringProperty, value)
End Set
End Property
================================
In C#:
//This Dependency Property will appear in the Common Properties category in Expression Blend with a Display Name of "My Prop"
[Description("This is the Description for myString Custom Dependency Property"), Category("Common Properties"), DisplayName("My Prop")]
public string myString {
get { return (string)GetValue(myStringProperty); }
set { SetValue(myStringProperty, value); }
}
When you build your project and open it in Expression Blend, add your Control to the artboard and under the Common Properties category you should see the following.
Using this same concept we can add a tooltip for the UserControl or Custom Control that is added to our Asset Library. **NOTE** DisplayName and Category will have no affect on your control in Expression Blend. Your control will always be placed under the Custom Controls tab of the Asset Libary and the name of the control displayed will always be the name of your Class.
================================
In VB:
<Description("This is the Description for my UserControl that will appear as a tooltip when I mouseover the control in the Asset Library in Expression Blend.")> _
Class UserControl1
================================
Rebuild the project and open in Expression Blend. From the Asset Library select the Custom Controls tab, mouseover your control and you should see the following.
I'm going to play around with the System.ComponentModel a bit more to see what other goodies it yields. I want to find out if I can create a Custom Dependency Property for my control with a type of Boolean and see if I can get it to display as a check box in Expression Blend. If anyone knows how to do this then give me a shout!
Cheers,
-LT