As I mentioned in my previous post, I am willing to write a multi part tutorial on how to add Design Time Support to your custom controls.
In this part, I will talk about the common attributes for Properties and Events
| Attribute | Applied To | Description |
|---|---|---|
| Browsable | Properties and events | Specifies whether a property or an event should be displayed in the property browser. |
| Category |
Properties and events |
Specifies the name of the category in which to group a property or event. When categories are used, component properties and events can be displayed in logical groupings in the property browser. |
| Description | Properties and events | Defines a small block of text to be displayed at the bottom of the property browser when the user selects a property or event. |
| DefaultProperty | Properties (Insert this attribute before the class declaration.) |
Specifies the default property for the component. This property is selected in the property browser when a user clicks on the control. |
| DefaultValue | Properties | Sets a simple default value for a property. |
| DefaultEvent | Events (Insert this attribute before the class declaration.) |
Specifies the default event for the component. This is the event that is selected in the property browser when a user clicks on the component. |
To illustrate how these attributes work I need first to set a custom control, let's start with simple windows forms button. [more]
[code:c#]
using System;
using System.Windows.Forms;
namespace Elsehemy.Controls
{
public class ButtonEx : Button
{
}
}
[/code]
Now add a property to make use of some attributes (I will use simple ones first)
[code:c#]
private int _numOfClicks;
public int NumOfClicks
{
get { return _numOfClicks; }
set { _numOfClicks = value; }
}
[/code]
Now add the ButtonEx control to a windows form to test the effect of attributes one by one.
[code:c#]
[Description("Tells how many time the button has been clicked")]
public int NumOfClicks{…}
[/code]
[code:c#]
[Category("Special Properties")]
[Description("Tells how many time the button has been clicked")]
public int NumOfClicks{…}
[/code]
[code:c#]
[DefaultValue(10)]
[Category("Special Properties")]
[Description("Tells how many time the button has been clicked")]
public int NumOfClicks{…}
[/code]
As you can notice the default value attribute now enabled the Reset context menu item which (of course) will reset the Property value to 10, the Reset command is only enabled when the value is not equal to 10, further more the value is always bold when it is not the default.
NOTE: The DefaultValue Attribute just writes the value of the box beside the property name to the value chosen, which means the actual inner variable isn't set to that value, so if you reset the value and 10 is written then ran the program and tested for NumOfClicks value you will find it equal to 0, even though its written 10.
Solution: Make sure to set the default value in the constructor of the control to have it work as expected.
More on DefaultValue Attribute as you already noticed the constructor has overloads for different types however all types are simple (bool, int, short, string ….) and one more constructor overload that has 2 parameters a type and a string value, consider we have a System.Drawing.Color Property that needs to have a default value.
[code:c#]
[DefaultValue(typeof(System.Drawing.Color),"Red")]
public System.Drawing.Color ColorProperty
[/code]
More over not only KnownColors can be set as default values, you can set the default value as RGB by supplying its Hex value..
[code:c#]
[DefaultValue(typeof(System.Drawing.Color),"#FFBA00")]
public System.Drawing.Color ColorProperty
[/code]
Sometimes there are more complex properties that need default values as System.Drawing.Font where DefaultValueAttribute will not fit, two special purpose methods named
void ResetPropertyname(), bool ShouldSerializePropertyname().
if Reset method is available it will be called one Reset command, ShouldSerialize method is for (should the designer generate a line in the form.designer.cs file or not) so obviously you should serialize when the value is not the default and not serialize if the property value is changed.
[code:c#]
System.Drawing.Font f;
public System.Drawing.Font FontProperty
{
get
{
if (f == null)
return this.Font; //this should be the default value you want
else return f;
}
set { f = value; }
}
void ResetFontProperty()
{
f = null;
}
bool ShouldSerializeFontProperty()
{
return f == null ? false : true;
}
[/code]
The DefaultPropertyAttribute just tells the designer which Property should be selected when the PropretyWindow opens (control:right click > Properties Or selected control: press F4). For example, Text is the default property of the TextBox control.
The DefaultEventAttribute tells the designer which Event should be selected when the ProperyWindow (Events Tab) opens, more over when double click the control the designer will generate an event handler method for that event. For example, Click is the default event of the Button control.
[code:c#]
[DefaultEvent("NumofClicksChanged")]
[DefaultProperty("NumOfClicks"]
public class ButtonEx : Button
[/code]
To be continued…
References:
http://msdn2.microsoft.com/en-us/library/tk67c2t8.aspx
Download Code : ButtonEx.cs (2.10 kb)
Leave a Reply