Kriya and Meditation for Software / IT Professionals. Conducted by Bipin Joshi in Thane. Read more...
Learn ASP.NET MVC, ASP.NET Core and ASP.NET Design Patterns. Courses conducted by Bipin Joshi on weekends. Click here for more details.

Using Design Time Attributes

Introduction

Developing a nice custom control is just one part of the story. As a control author you should also pay attention about the experience of other developers who will be using your control. In most of the real world cases developers use Visual Studio as the IDE for developing .NET applications. You can enhance the experience of other developers using your control by providing proper designer support. For example, you can control how your control properties and events are displayed in property window and toolbox. A set of attributes often called as Design Time Attributes allow you to accomplish this.

Common Design Time Attributes

The following sections explain the common design time attributes that allow you to change how the control behaves in the property window and toolbox. Most of these attributes reside in System.ComponentModel namespace. In the following sections we use the GraphicButton control that we created earlier in this series.

Deciding whether a property will be visible in the property window

By default all the public properties of a custom control are displayed in the property window. Sometimes you may want that developers should set a property only via code and not via property window. The [Browsable] attribute allows you to control just that. The usage of this attribute is as follows:

[Browsable(false)]
public string ImageUrl
{
get { return ViewState["imgurl"] as string; }
set { ViewState["imgurl"] = value; }
}

The value of false indicates that the ImageUrl property will not be displayed in the property window.

Adding description to a property

Have a look at the screen capture below:

Can you notice a one line description of the Text property at the bottom portion of the property window? Such description can be added using [Description] attribute.

[Description("Specifies the caption of the graphic button")]
public string Text
{
get { return ViewState["text"] as string; }
set { ViewState["text"] = value; }
}

Grouping related properties

The property windows allows you list properties either alphabetically or grouped in categories. Grouping properties by category makes it simple to locate them as per their functionality. Have a look below where the ImageUrl and Text properties are grouped together under Control Values category.

The [Category] attribute allows you to specify category for your property.

[Category("Control Value")]
public string Text
{
get { return ViewState["text"] as string; }
set { ViewState["text"] = value; }
}

Enabling data binding for a property

You may want to use your custom control as a child control of some data bound control (say DataList). Further, you may want to data bind some of the control properties. In other words you want to list your control properties in the data bindings editor as shown below:

The [Bindable] attribute enables this behavior for you.

[Bindable(true)]
public string Text
{
get { return ViewState["text"] as string; }
set { ViewState["text"] = value; }
}

Making a property read only

At times you may want that a control property be listed in the property window but it should be read only. This behavior can enabled using [ReadOnly] attribute.

[ReadOnly(true)]
public string Text
{
get { return ViewState["text"] as string; }
set { ViewState["text"] = value; }
}

Setting a property of multiple control instances

When you select multiple instance of the same control and set a property in the property window all the instances bear the same property value. You may not always this default behavior. You can use [MergableProperty] attribute to indicate this to the IDE.

[MergableProperty(true)]
public string Text
{
get { return ViewState["text"] as string; }
set { ViewState["text"] = value; }
}

Refreshing other properties when a property value changes

Some times your properties are interdependent in that if value of one property changes then it causes value of some other property to change. In such cases you would like to refresh the property window when a property value changes. The [RefreshProperties] attribute allows you to indicate such a behavior.

[RefreshProperties(RefreshProperties.All)]
public string Text
{
get { return ViewState["text"] as string; }
set { ViewState["text"] = value; }
}

The [RefreshProperties] attribute accepts a parameter of type RefreshProperties enumeration. The three possible enumeration values are None, All and Repaint.

Setting a default property and event

When yu drag and drop a control instance on the web form you may want to show a particular property (or event) selected by default in the property window. This can be accomplished with the help of [DefaultProperty] and [DefaultEvent] attributes respectively.

[DefaultEvent("Click")]
[DefaultProperty("Text")]
public class GraphicButton : 
WebControl, IPostBackEventHandler
... 

Notice that unlike other attributes we discussed so far the [DefaultProperty] and [DefaultEvent]  attributes are class level attributes. Both of these attributes take a string parameter indicating the name of the default property and event respectively.

Changing icon displayed in the toolbox

By default a newly created custom control is shown in the toolbox as shown below (see the gear icon):

You may want to change the default icon displayed along with your control. You do this by adding a bitmap file to your custom control project and naming it same as the custom control class. For example, for our BinaryIntellect.UI.GraphicButton control you would add a bitmap with name BinaryIntellect.UI.GraphicButton.bmp. The bitmap must be 16x16 pixels and should use no more than 16 colors.

There is another way to set toolbox bitmap - the [ToolboxBitmap] class level attribute.

[ToolboxBitmap(@"C:\BinaryIntellect.UI.GraphicButton.bmp")]

The [ToolboxBitmap] attribute takes the full path of the bitmap file. Remember that the [ToolboxBitmap] attribute resides in System.Drawing namespace.

The following figure shows how a custom bitmap looks like in the toolbox.

This article covered the basics of design time support. You can further add features such as custom pickup lists and smart tags. I will cover them in my next articles.


Bipin Joshi is a software consultant, an author and a yoga mentor having 22+ years of experience in software development. He also conducts online courses in ASP.NET MVC / Core and Design Patterns. He is a published author and has authored or co-authored books for Apress and Wrox press. Having embraced the Yoga way of life he also teaches Meditation and Mindfulness to interested individuals. To know more about him click here.

Get connected : Twitter  Facebook  Google+  LinkedIn

Posted On : 16 March 2008


Tags : ASP.NET Custom Controls