.NET Building Blocks: Custom User Controls in Practice  : Page 5

Integrating Your Controls with Visual Studio
Now that you have learned the ins and outs of building controls for your own libraries, the next step—perhaps the most important—is to integrate your controls into Visual Studio so they operate as cleanly, intuitively, and professionally as the native .NET framework controls. You achieve this primarily by assigning attributes to your classes, properties, methods, and events.

An attribute is essentially a property, that is, a characteristic of some object. The terms attribute and property are often considered synonymous. In XML, for example, you provide attributes for elements. In .NET, you provide properties for classes. Because you can attach attributes to almost any entity in the .NET framework—including attaching them to properties—you must take care to use the right terminology. Attaching attributes to properties is, in fact, the main technique you will see in this and subsequent sections. To attach an attribute to an element in your code, determine the attribute you want to use along with its arguments, surround it with square brackets (in C#), and place it on the line immediately preceding the element's definition. This code fragment shows four attributes being attached to the ClockForeColor property:

   [Description("Foreground color of the clock")]
   [Category("Clock")]
   [EditorBrowsable(EditorBrowsableState.Always)]
   [Localizable(True)]
   public Color ClockForeColor
   {
   . . .
   }

Attributes behave like other elements in the code editor in two important respects. First, Intellisense will help with auto-completion of your choice of attribute. Second, you must have the appropriate references in your project for the attribute you intend to use; otherwise you will get a compilation error.

See these MSDN documents for more information:

• Design-Time Attributes for Components
• Attributes and Design-Time Support
• How to: Apply Attributes in Windows Forms Controls

The document Attributes in Windows Forms Controls is probably the best reference for attributes relevant to controls. And for purists, I found this (possibly outdated) Attribute Hierarchy that contains a complete list of attributes, including some not applicable to user controls.

Table 5 lists the more universal attributes for integrating your controls into Visual Studio, along with one important aspect of integration (in the final row) that you do with documentation comments instead of attributes.

Attribute	Operates On	Description
Browsable	Property, event	Specifies whether a property or event should be displayed or hidden in the Properties window.
Category	Property, event	Organizes your property into one of the existing categories (e.g. Accessibility, Appearance, Behavior, Data, Design, etc.) in the property grid or a new one of your own choosing. Only relevant when the property grid is set to Categorized mode (as opposed to alphabetic mode).
Description	Property, event	Defines a short block of text that displays at the bottom of the property browser when you select a property or event.
DisplayName	Property, event, method	Specifies an alias for the name of a property, event, or public void method that takes no arguments. This alias is shown in the Properties window instead of the actual name of the property.
EditorBrowsable	Property, event, method	Specifies whether a property or method is revealed via Intellisense in the code editor.
Localizable	Property	Specifies that a property can be localized. Any properties that have this attribute are automatically persisted into the resources file (rather than in the designer-generated portion of code) when a user chooses to localize a form.
PasswordPropertyText	Property	Indicates that an object's text representation is obscured by characters such as asterisks.
ReadOnly	Property	Specifies whether a property is read-only or read/write at design time. If the property has no setter accessor, then this attribute has no effect.
DefaultEvent	Class	Specifies the event that VS initially selects when you view the Events window for a control. Double-clicking the control in the designer generates stub code to handle this event.
DefaultProperty	Class	Specifies the property that VS initially selects when you view the Properties window for a control.
DefaultValue	Property	The .NET framework distinguishes between an initial value of a property and a default value; this attribute does not assign an initial value; it determines only whether the property is serialized in the list of property assignments in your winformapp.Designer.cs file. See MSDN for more details.
Documentation comments	Class, property, event, method	XML documentation comments that you apply to document your classes, methods, properties, and events are automatically incorporated by Visual Studio's Intellisense.

Previous Page

Next Page