Defining Default Values with the ShouldSerialize and Reset Methods

 

ShouldSerialize and Reset are optional methods that you can provide for a property, if the property does not a have simple default value. If the property has a simple default value, you should apply the DefaultValueAttribute and supply the default value to the attribute class constructor instead. Either of these mechanisms enables the following features in the designer:

• The property provides visual indication in the property browser if it has been modified from its default value.

• The user can right-click on the property and choose Reset to restore the property to its default value.

• The designer generates more efficient code.

  Note

  Either apply the DefaultValueAttribute or provide ResetPropertyName and ShouldSerializePropertyName methods. Do not use both.

The ResetPropertyName method sets a property to its default value, as shown in the following code fragment.

Public Sub ResetMyFont()  
   MyFont = Nothing  
End Sub  

public void ResetMyFont() {  
   MyFont = null;  
}  

Note

If a property does not have a Reset method, is not marked with a DefaultValueAttribute, and does not have a default value supplied in its declaration, the Reset option for that property is disabled in the shortcut menu of the Properties window of the Windows Forms Designer in Visual Studio.

Designers such as Visual Studio use the ShouldSerializePropertyName method to check whether a property has changed from its default value and write code into the form only if a property is changed, thus allowing for more efficient code generation. For example:

'Returns true if the font has changed; otherwise, returns false.  
' The designer writes code to the form only if true is returned.  
Public Function ShouldSerializeMyFont() As Boolean  
   Return Not (thefont Is Nothing)  
End Function  

// Returns true if the font has changed; otherwise, returns false.  
// The designer writes code to the form only if true is returned.  
public bool ShouldSerializeMyFont() {  
   return thefont != null;  
}  

A complete code example follows.

Option Explicit  
Option Strict  
  
Imports System  
Imports System.Windows.Forms  
Imports System.Drawing  
  
Public Class MyControl  
   Inherits Control  
  
   ' Declare an instance of the Font class  
   ' and set its default value to Nothing.  
   Private thefont As Font = Nothing  
  
   ' The MyFont property.   
   Public Property MyFont() As Font  
      ' Note that the Font property never  
      ' returns null.  
      Get  
         If Not (thefont Is Nothing) Then  
            Return thefont  
         End If  
         If Not (Parent Is Nothing) Then  
            Return Parent.Font  
         End If  
         Return Control.DefaultFont  
      End Get  
      Set  
         thefont = value  
      End Set  
   End Property  
  
   Public Function ShouldSerializeMyFont() As Boolean  
      Return Not (thefont Is Nothing)  
   End Function  
  
   Public Sub ResetMyFont()  
      MyFont = Nothing  
   End Sub  
End Class  

using System;  
using System.Windows.Forms;  
using System.Drawing;  
  
public class MyControl : Control {  
   // Declare an instance of the Font class  
   // and set its default value to null.  
   private Font thefont = null;  
  
   // The MyFont property.      
   public Font MyFont {  
      // Note that the MyFont property never  
      // returns null.  
      get {  
         if (thefont != null) return thefont;  
         if (Parent != null) return Parent.Font;  
         return Control.DefaultFont;  
      }  
      set {  
         thefont = value;  
      }  
   }  
  
   public bool ShouldSerializeMyFont() {  
      return thefont != null;  
   }  
  
   public void ResetMyFont() {  
      MyFont = null;  
   }  
}  

In this case, even when the value of the private variable accessed by the MyFont property is null, the property browser does not display null; instead, it displays the Font property of the parent, if it is not null, or the default Font value defined in Control. Thus the default value for MyFont cannot be simply set, and a DefaultValueAttribute cannot be applied to this property. Instead, the ShouldSerialize and Reset methods must be implemented for the MyFont property.

See Also

Properties in Windows Forms Controls
Defining a Property
Property-Changed Events