Defining a Property in Windows Forms Controls

  • Article

 

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

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