9.4 Using Design-Time Attributes

You want to control various design-time behaviors of your control to aid users who use your control within their Windows Forms.

Technique

Use attributes on your control's class declaration and any properties or events it contains to insert additional information about your control that can be read by the Visual Studio .NET property browser. You apply attributes to a class, property, or method by placing the attributes and their associated parameters within brackets immediately preceding the type declaration. These attributes only add information to the property browser during design time, and they have no effect on the control at runtime. Listing 9.3 shows design-time attributes used on the control class to set the default property of the control, which is the initial property that a user edits when the control is first created within the forms designer. The Percentage property in Listing 9.3 contains several design-time attributes that control the category of the property within the property browser, the description that appears when the user selects the property, parentheses that are used on the property name , and a default value that is initially filled in property browser. The LogFile property also uses the EditorAttribute attribute to assign the editor used to edit the property's value, which in this case is a open file dialog editor.

Listing 9.3 Properties of a Control with Design-Time Attributes

 [Description("Percentage of gauge that is filled."),Category("Data"), ParenthesizePropertyNameAttribute(true), DefaultValue(100)] public int Percentage {     get     {         return percent;     }     set     {         if( value < 0  value > 100 )             return;         percent = value;         Invalidate();     } } [Category("Appearance"), Description("Color of filled gauge."), ParenthesizePropertyNameAttribute(true), DefaultValue(typeof(Color), "Red")] public Color GaugeColor {     get     {         return gaugeColor;     }     set     {         gaugeColor = value;         Invalidate();     } } [Description("Filename to log runtime data to."), Category("Behavior"), ParenthesizePropertyNameAttribute(true), EditorAttribute(typeof(System.Windows.Forms.Design.FileNameEditor),    typeof(System.Drawing.Design.UITypeEditor)) ] public string LogFile {     get     {         return fileName;     }     set     {         fileName = value;     } } 

Comments

Attributes provide a way to associate additional information for a class, method, or property. When an attribute is encountered during compilation, it is placed within the metadata accompanying the type to which it is bound. An attribute itself is nothing more than an instance of a .NET class derived from System.Attribute . In fact, the syntax when applying an attribute to a type translates to the code used for the constructor of the object that is created for that attribute. In Listing 9.3, you can see a Description attribute for the Percentage property.

When you place the control onto a Windows Form and select a property within the property browser, the property browser queries the property using Reflection to retrieve the DescriptionAttribute by accessing the property's Attributes collection. This is just one example of how an attribute is used within the context of a property. Other attributes are used in different ways, either as information to the CLR or some custom consumer of that information. You can easily create your own custom attributes by deriving a class from the System.Attribute class and then access that information in a manner similar to the way the property browser accesses attributes for a control. Chapter 23, "Reflection," contains a more extensive examination of custom attributes.