Recipe 14.3. Describing User Control Properties

Problem

You've added an extra property to your user control, and although it appears in the Properties panel when the control is added to a form, no description appears for that property.

Solution

Sample code folder: Chapter 14\UserControlProperties

Add a < DescriptionAttribute> attribute to the property, and use it to supply any descriptive text you want as metadata attached to the property.

Discussion

Create a new Windows Forms project, and add a new user control to the project through the Project Add User Control menu command. (See Recipe 14.2 for details on designing new user controls.) Name the new control Access the source code for the user control and add the following code to the class:

 Private hiddenData As String Public Property ExtraData( ) As String    Get       Return hiddenData    End Get    Set(ByVal value As String)       hiddenData = value    End Set End Property 

This code adds a simple property, ExtraData, to the control, storing the actual value in the private hiddenData member. The control is complete; build it using the Build Build WindowsApplication1 menu command.

Return to the form designer for Form1. Locate the new SimpleControl control in the Toolbox and add it to the form. If you look in the Properties panel, you will see the ExTRaData property, but it won't have any description (see Figure 14-4).

To add the description, return to the source code for the user control. Add the following line to the top of the SimpleControl.vb source-code file:

 Imports System.ComponentModel 

Figure 14-4. The ExtraData property, with no description

Just before the Public Property ExtraData line in the SimpleControl class, add this new code line:

 <DescriptionAttribute( _    "Extra details related to this control.")> _ 

so that the start of the property looks like this:

 <DescriptionAttribute( _    "Extra details related to this control.")> _ Public Property ExtraData( ) As String 

Rebuild the project, return to Form1, and select the user control you added to the form earlier. When selected, the ExTRaData property should now include a description, as shown in Figure 14-5.

Figure 14-5. The ExtraData property with its new description

The System.ComponentModel namespace exposes several attributes that, when used, enhance the elements included in the Properties panel. One of these attributes, <DescriptionAttribute>, identifies the text that appears in the description portion of the Properties panel when the matching property is selected. This attribute is stored as metadata attached to the SimpleControl.ExtraData property, and it is referenced by the control that implements the Properties panel.

See Also

Recipe 14.2 discusses the implementation of user controls.