Design-Time Attributes for Components
If you are not familiar with applying attributes to provide metadata to the common language runtime, see Extending Metadata Using Attributes. Because components can be displayed in a designer, such as Visual Studio, they require attributes that provide metadata to design-time tools. This section describes and provides a list of commonly used design-time attributes.
Attributes and Designer Support
Design-time attributes are essential for displaying your control and its members correctly at design time, as they provide valuable information to a visual design tool.
In the following code fragment, the CategoryAttribute attribute enables the property browser to display the TextAlignment property in the Alignment category. The DescriptionAttribute attribute allows the property browser to provide a brief description of the property when a user clicks on it.
[
Category("Alignment"),
Description("Specifies the alignment of text.")
]
public ContentAlignment TextAlignment { //... }
<Category("Alignment"), _
Description("Specifies the alignment of text.")> _
Public Property _
TextAlignment As ContentAlignment
' ...
End Property
Note
In Visual C# and Visual Basic, an attribute class named AttributeNameAttribute can be referenced simply as AttributeName in the attribute syntax.
Some design-time attributes are applied at the class level. A DesignerAttribute attribute is applied at the class level and informs the forms designer which designer class to use to display the control. Components are associated with a default designer (System.ComponentModel.Design.ComponentDesigner), and Windows Forms and ASP.NET server controls are associated with their own default designers. Apply DesignerAttribute only if you define a custom designer for your component or control.
// Associates the designer class SimpleControl.Design.SimpleDesigner
// with Simple.
[ Designer(typeof(SimpleControl.Design.SimpleDesigner))]
public class Simple : WebControl { //... }
' Associates the designer class SimpleControl.Design.SimpleDesigner
' with Simple.
<Designer(GetType(SimpleControl.Design.SimpleDesigner))> _
Public Class Simple
Inherits WebControl
' ...
End Class
Common Attributes for Properties and Events
The following table lists the attributes that are commonly applied to properties and events.
Attribute |
Applied To |
Description |
|---|---|---|
Properties and events |
Specifies whether a property or an event should be displayed in the property browser. |
|
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. |
|
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. |
|
Properties |
Specifies whether a property is interesting to bind to. |
|
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. |
|
Properties |
Sets a simple default value for a property. |
|
Properties |
Specifies the editor to use for editing (changing) a property in a visual designer. |
|
Properties |
Specifies that a property can be localized. Any properties that have this attribute are automatically persisted into the resources file when a user chooses to localize a form. |
|
Properties |
Specifies whether (and how) a property displayed in the property browser should be persisted into code. |
|
Properties |
Specifies the type converter to use for converting the type of the property to another data type. |
|
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. |
Unless otherwise stated, attributes for properties and events are placed in code immediately before the property or event declaration, as shown in the following example.
// To apply CategoryAttribute to the BorderColor
// property, place it immediately before the declaration
// of the BorderColor property.
[Category("Appearance")]
public Color BorderColor;
// To apply DescriptionAttribute to the Click event,
// place it immediately before the declaration
// of the Click event.
[Description("The Click event of the button")]
public event EventHandler Click;
' To apply CategoryAttribute to the BorderColor
' property, place it before the property declaration.
<Category("Appearance")> Public BorderColor As Color
' To apply DescriptionAttribute to the Click event,
' place it before the event declaration.
<Description("The Click event of the button")> Public Event Click
For information about design-time attributes that associate designers with components and controls, see Extending Design-Time Support.
In addition to using the attribute classes defined in the .NET Framework class library, you can define your own attribute classes. For details, refer to the documentation for your programming language or see Writing Custom Attributes.
See Also
Tasks
How to: Apply Attributes in Windows Forms Controls
Concepts
Attributes and Design-Time Support
Attributes in Windows Forms Controls