Defining a Property in Windows Forms Controls

For an overview of properties, see Properties Overview. There are a few important considerations when defining a property:

• You must apply attributes to the properties you define. Attributes specify how the designer should display a property. For details, see Design-Time Attributes for Components.

• If changing the property affects the visual display of the control, call the Invalidate method (that your control inherits from Control) from the set accessor. Invalidate in turn calls the OnPaint method, which redraws the control. Multiple calls to Invalidate result in a single call to OnPaint for efficiency.

• The .NET Framework class library provides type converters for common data types such as integers, decimal numbers, Boolean values, and others. The purpose of a type converter is generally to provide string-to-value conversion (from string data to other data types). Common data types are associated with default type converters that convert values into strings and strings into the appropriate data types. If you define a property that is a custom (that is, nonstandard) data type, you will have to apply an attribute that specifies the type converter to associate with that property. You can also use an attribute to associate a custom UI type editor with a property. A UI type editor provides a user interface for editing a property or data type. A color picker is an example of a UI type editor. Examples of attributes are given at the end of this topic.

  Note
  If a type converter or a UI type editor is not available for your custom property, you can implement one as described in Extending Design-Time Support.

The following code fragment defines a custom property named EndColor for the custom control FlashTrackBar.

Public Class FlashTrackBar
   Inherits Control
   ...
   ' Private data member that backs the EndColor property.
   Private _endColor As Color = Color.LimeGreen

   ' The Category attribute tells the designer to display
   ' it in the Flash grouping. 
   ' The Description attribute provides a description of
   ' the property. 
   <Category("Flash"), _
   Description("The ending color of the bar.")>  _
   Public Property EndColor() As Color
      ' The public property EndColor accesses _endColor.
      Get
         Return _endColor
      End Get
      Set
         _endColor = value
         If Not (baseBackground Is Nothing) And showGradient Then
            baseBackground.Dispose()
            baseBackground = Nothing
         End If
         ' The Invalidate method calls the OnPaint method, which redraws  
         ' the control.
         Invalidate()
      End Set
   End Property
   ...
End Class

public class FlashTrackBar : Control {
   ...
   // Private data member that backs the EndColor property.
   private Color endColor = Color.LimeGreen;
   // The Category attribute tells the designer to display
   // it in the Flash grouping. 
   // The Description attribute provides a description of
   // the property. 
   [
   Category("Flash"),
   Description("The ending color of the bar.")
   ]
   // The public property EndColor accesses endColor.
   public Color EndColor {
      get {
         return endColor;
      }
      set {
         endColor = value;
         if (baseBackground != null && showGradient) {
            baseBackground.Dispose();
            baseBackground = null;
         }
         // The Invalidate method calls the OnPaint method, which redraws 
         // the control.
         Invalidate();
      }
   }
   ...
}

The following code fragment associates a type converter and a UI type editor with the property Value. In this case Value is an integer and has a default type converter, but the TypeConverterAttribute attribute applies a custom type converter (FlashTrackBarValueConverter) that enables the designer to display it as a percentage. The UI type editor, FlashTrackBarValueEditor, allows the percentage to be displayed visually. This example also shows that the type converter or editor specified by the TypeConverterAttribute or EditorAttribute attribute overrides the default converter.

<Category("Flash"), _
TypeConverter(GetType(FlashTrackBarValueConverter)), _
Editor(GetType(FlashTrackBarValueEditor), _
GetType(UITypeEditor)), _
Description("The current value of the track bar.  You can enter an actual value or a percentage.")>  _
Public ReadOnly Property Value() As Integer
...
End Property

[
Category("Flash"), 
TypeConverter(typeof(FlashTrackBarValueConverter)),
Editor(typeof(FlashTrackBarValueEditor), typeof(UITypeEditor)),
Description("The current value of the track bar.  You can enter an actual value or a percentage.")
]
public int Value {
...
}

See Also

Concepts

Defining Default Values with the ShouldSerialize and Reset Methods
Property-Changed Events
Attributes in Windows Forms Controls

Other Resources

Properties in Windows Forms Controls