9.11 Removing Control Properties Using Metadata Filtering

You want to add a property to a control for use by a custom control designer, or you want to remove a control property from the property browser.

Technique

The ControlDesigner class allows you to add property filters to add or remove properties from the property browser when a control is selected in the forms designer. In either case, create a new class derived from System.Windows.Forms.Design.ControlDesigner . To add a new property, override the PreFilterProperties method. The properties parameter is a IDictionary collection whose keys represent the names of the properties and whose associated values are instances of the corresponding properties values. Before adding to the collection, you must call the base class PreFilterProperties method to initialize the property's collection. You can then call the static method CreateProperty defined in the TypeDescriptor class to add the property to the property browser. The first parameter is a type reference to the class that defines the property, which in most cases is the result from calling GetType() in your control designer. The remaining parameters include a string value representing the name of the new property, the data type of the property, and any attributes that apply to the property. You can apply attributes by creating an array of Attribute values:

 protected override void PreFilterProperties(IDictionary properties) {     // call base first     base.PreFilterProperties (properties);     properties["DrawDesignBorder"] = TypeDescriptor.CreateProperty(         this.GetType(), "DrawDesignBorder", typeof(bool),         new Attribute[] {CategoryAttribute.Design}); } 

To remove properties from the property browser, override the PostFilterProperties method. Just like the PreFilterProperties , this method accepts an IDictionary -based collection representing the collection of control properties. To remove a property, simply call the Remove method defined in the collection, passing the name of the property to remove. You must then call the base class version of PostFilterProperties to make the change within the property browser:

 protected override void PostFilterProperties(IDictionary properties) {     // remove the Visible property     properties.Remove("Visible");     // call base last     base.PostFilterProperties (properties); } 

Comments

In Recipe 9.9, "Utilizing Custom Designers," the OnPaintAdornments method was overridden to display a border around the RandomShapeControl during design time. One caveat with this method is that the border is always drawn even if the user didn't want this behavior to appear. However, by filtering a control's properties, you can add a design-time property to enable this functionality. In the PreFilterProperties method shown earlier, a DrawDesignBorder property is added to the property browser whenever the control is selected by the user in the forms designer. Setting this value to false updates the corresponding property defined in the custom control designer, thereby allowing you to turn off the drawing of the design border. However, one side effect of doing so is the code generation that occurs by the forms designer.

When a property is added to the properties collection and is subsequently changed by the user when designing the control, the added property is added to the InitializeComponent method defined in the original control's class definition. However, this step generates a compiler error because the DrawDesignBorder property is defined in the control designer and not the control itself. To prevent this behavior, create an additional method to turn off serialization for this property. When a property value is changed within the property browser, the forms designer checks whether the property should be serialized. By default, every property is serialized, which means the code to change the property is inserted into the control's class. To turn off serialization for a property, create a method in the control designer class named ShouldSerialize PropertyName , where PropertyName is the name of the property for which you want to turn off serialization. To turn off serialization for the DrawDesignBorder property, for instance, create a ShouldSerializeDrawDesignBorder method and return false :

 public bool ShouldSerializeDrawDesignBorder() {     return false; } 

You can also remove properties from the property browser at design time by implementing the PostFilterProperties method and calling the Remove method defined in the IDictionary collection passed in as the parameter. Doing so removes the associated property from the property browser but does not remove the property from the control itself. In other words, you are still able to access the property within source code, but a user designing a Windows Form that contains the control will not be able to change the property visually. This method is yet another way to control the behavior of a control during design time.