Timmy Kokke

When building custom or user controls you probably end up with a large amount of properties on that control. When using the control in a visual designer like Blend or the Visual Studio designer these properties just show up. Adding a bit of structure in this can be done very easily by adding a couple of attributes to the properties.

The attributes to let the visual design know what to do can be found in the System.ComponentModel namespace. There’s a WPF version of this namespace also.

For the sake of simplicity I’ve created a UserControl and set the background color of the LayoutRoot grid to red to be able to spot it in the designer. I’ll add properties with attributes to that control and show you what happens in Visual Studio and Expression Blend.

Categorizing

By default all properties on UserControls are grouped together in the Miscellaneous section at the bottom of the properties Panels in Blend and or in the Others section in Visual Studio.

The first property I’ve named CategoryDemo1 and it’s of type string. It doesn’t have an attribute to go with it.

When adding the control to the MainPage the properties look like this:

To add a property to an existing category add a Category Attribute to the property and give it the name of the category you would like to have you property added too.

For example, this adds the property Category2 to the Layout category:

[Category("Layout")]

public string CategoryDemo2 { get; set; }

Your property might need a category of its own. This can be done just as easily as adding to an existing category. Just use a category name that doesn’t exist yet.

[Category("CustomCategory")]

public string CategoryDemo3 { get; set; }

You might have noticed that some categories are named differently in Visual Studio and Blend, there might even be some localization used. Take for example the Common category in Visual Studio. It is called Common Properties in Expression Blend. The CategoryAttribute class contains a couple of static properties that return the CategoryAttribute for a default category. Unfortunately the static properties can’t be used when placing an attribute on a property. In part 2 of this tutorial I’ll talk about how this can be done. In the meantime you’ll have to guess a little.

The common properties category can be used like this:

[Category("Common Properties")]

public string CategoryDemo4 { get; set; }

Description

Often you might want to add a description to a property, like you would do in code. You can use the DescriptionAtrribute for this purpose.

[Category("CustomCategory")]

[Description("This is a description")]

public string DescriptionExample { get; set; }

Default Value

Often you would like to set a default value for a property. Numeric or a string or whatever. When the value is reset in the designer the property should show the default value. You can accomplish this by adding a DefaultValueAttribute to the property.

[Category("CustomCategory")]

[DefaultValue("Hello")]

public string DefaultExample { get; set; }

Hide properties

There are situations where you have properties that you do not want to expose through the UI. In cases like this you can set the BrowsableAttribute to false.

[Browsable(false)]

public string NotBrowsable { get; set; }

(intentionally left blank: can’t make a screenshot of something that’s not there)

AlternateContentProperty

The last thing I would like to show is the AlternateContentPropertyAttribute. I’m still not sure what it is used for, but it lets Expression Blend know to display the property in a different way. The property is shown in the Objects and Timeline panel. The charting controls in the Silverlight Toolkit do this too. Visual Studio doesn’t seem to do anything with this property.

[Category("CustomCategory")] 
    
[AlternateContentProperty]

public string AlternateExample { get; set; }

Wrap up

As you can see there are various possibilities on how to display your properties in the design surfaces. But there is more. Have you ever notices the .design.dll files that came with Silverlight and the Silverlight Toolkit? I’ll continue this article in part 2 about these.

To be the first to know when it’s done, please subscribe to the RSS feed or follow me on twitter (@sorskoot).