Visual Basic: Saving Custom Control Persistant Properties

For more on this subject Google Search on VB Initproperties

You may wonder why we need the InitProperties event since the UserControl property already has an Initialize event in common with Class modules and other objects, such as forms.

The reason that we need InitProperties to initialize default values is that the Initialize event happens too often, that is, every time an instance or your control "wakes up." You only want the default property values to be assigned when the developers first sites a new copy of your control on a container. After that, you want the developer to be able to define persistent property values.

WARNING – Don’t Use the Initialize Event to Set an ActiveX Control’s Default Property Values : If you put code to initialize properties to their default values in your custom ActiveX control’s Initialize event instead of in the InitProperties event, then you will have some very frustrated developers on your hands. Your default values will override the values the developer has assigned at design time every time the developer runs an application using your control.

—

The Property Bag is a persistent UserControl object containing the values of your control’s custom, extender, and delegated properties. In fact, the Property Bag is so persistent that it doesn’t get destroyed with the instances of the UserControl. This means you can store property values in the Property Bag just before an instance of the UserControl is destroyed and then retrieve the stored values when a new instance of the UserControl "wakes up" in another part of the development life cycle.

The Property Bag has two methods to store and retrieve values respectively:

• The WriteProperty method

• The ReadProperty method

You must know how to manipulate the Property Bag in the following situations that we discuss in the sections immediately following this one:

• You store property values into the PropertyBag by calling its WriteProperty method in the WriteProperties event procedure.

• You retrieve property values from the PropertyBag by calling its ReadProperty method in the ReadProperties event procedure.

• You ensure that the WriteProperties event will fire by calling the PropertyChanged method. You’ll usually do this in the Property Let procedures of your custom properties or at other appropriate places in your code where the storage value of a property changes.

—-

The operating environment fires a UserControl‘s ReadProperties and WriteProperties events whenever it thinks that the instantiated object’s properties need to be re-initialized (ReadProperties event fires) or stored for safekeeping (WriteProperties event fires).

This arrangement makes it much easier for you, the control author, to manage these properties since you don’t have to think about all the possible occasions when property values might need reading or writing. You simply need to put code for reading and writing property values in two centralized places: the ReadProperties and WriteProperties event procedures.

Both the ReadProperties and WriteProperties event procedures receive a single parameter named PropBag. This PropBag parameter obviously represents the Property Bag object that holds the UserControl‘s property values.

The PropertyBag object represented by the PropBag parameter has one method for reading properties (ReadProperty) and another for writing properties (WriteProperty).

Usually, the only code you need to write in the ReadProperties event procedure will be a series of calls to the ReadProperty method so you can retrieve persistent values for individual properties.

Conversely, the only code you usually need to write in the WriteProperties event procedure will be a series of calls to the WriteProperty method so you can store persistent values of individual properties.

—

Visual Basic fires the UserControl‘s WriteProperties event just before it fires the UserControl’s Terminate event provided that at least one property value has changed. In other words, the WriteProperties event fires whenever the current instance of the control is about to be destroyed and any property values that you want to persist have changed and, therefore, need to be saved.

As its name implies, you use the WriteProperties event procedure to save persistent property values. The specific mechanism you use to save property values is to call the WriteProperty method of the Property Bag for each property whose value you wish to save. The Property Bag is available in the event procedure of the WriteProperties event as a parameter named PropBag. The example code in Listing 13.7 shows how you would call the Property Bag‘s WriteProperty method to save individual property values. Notice that we use whatever repository has been storing the property value as the source for the current value: at times this might be a private memory variable, and at other times it might be a property of a constituent control (as in the final line before the End Sub).

USING THE WRITEPROPERTIES EVENT PROCEDURE TO SAVE PROPERTY VALUES TO THE PROPERTY BAG

Private Sub UserControl_WriteProperties (PropBag As PropertyBag)          ‘—Store the values of the custom properties to the Property Bag
      PropBag.WriteProperty  "BackColor", BackColor
      PropBag.WriteProperty  "Celsius", m_Celsius
      PropBag.WriteProperty  "Fahrenheit", m_Fahrenheit
      PropBag.WriteProperty  "TemperatureDate", m_TemperatureDate
      PropBag.WriteProperty  "Caption", lblCaption.Caption
End Sub

—

The system automatically fires the WriteProperties and ReadProperties events whenever it thinks you may need their services. To ensure that the system knows a property has changed, you have to call the PropertyChanged method. An example of this would be when you change the value of a Private variable that implements the value of a property. The system will have no way of knowing that this variable is connected with a property, and therefore it will not fire the WriteProperties event based solely on the change you have made.

In such cases, you can call the PropertyChanged method. This method informs the system that a particular property has changed and so ensures that the WriteProperties event will fire before the current instance of the control is destroyed. If you’ve written the appropriate code in the WriteProperties xvent, then your property values will be stored in the Property Bag.

You should call the UserControl‘s PropertyChanged method whenever you do something in code that will cause a change to a property whose value you wish to persist. The most typical place for you to call the PropertyChanged method would be in a Property Let or Property Set procedure. Note that we check the CanPropertyChange method that we discuss in "Calling the CanPropertyChange Method Before Allowing a Property Value to Change."

CALLING THE PropertyChanged METHOD TO ENSURE THAT WRITEPROPERTIES WILL FIRE

Property Let Celsius(sValue As Single)
   If CanPropertyChange("Celsius") Then                   ‘—assign incoming value to be stores in Private variable
      m_Celsius = sValue     
      PropertyChanged ("Celsius")                                  ‘—invoke UserControl’s PropertyChanged method so it knows to trigger WriteProperties and store new value     
      Slider1.Value = m_Celsius                                      ‘—perform other housekeeping specific to this application
      RecalcFahrenheitFromCelsius sValue
      DisplayTempsFromSlider
   End If
End Property

 

—

The ReadProperties event fires when a custom control is reinstantiated at some point in the development cycle (the Project where it resides has been retrieved and its container has been instantiated, the developer has just entered run mode from the design mode, or the developer has just returned to design mode from run mode).

Notice that we said that ReadProperties fires when the custom control is re-instantiated. We used this phrasing to purposely exclude the case when the developer places an instance of the control on its container for the first time from the Toolbox. For such first-time instantiation, the ReadProperties event doesn’t fire. Instead, the InitProperties event fires (see "Using the InitProperties Event to Set Default Starting Property Values"). The ReadProperties event, as its name implies, is the event that you will use to restore the values of properties that have been kept in the Property Bag. The Property Bag appears in the ReadProperties event procedure as a parameter named PropBag. You call PropBag’s ReadProperty method for each property whose value you wish to restore.

Notice that the ReadProperty method takes two arguments: the name of the property as a string and then a default value for the property (in case the property’s value has not been initialized in the Property Bag).

We store the results of each call to ReadProperties in the appropriate variable or control property that implements the property within this control.

USING THE READPROPERTIES EVENT PROCEDURE TO RESTORE PERSISTENT PROPERTY VALUES FROM THE PROPERTY BAG

Private Sub UserControl_ReadProperties (PropBag As PropertyBag)
      m_Celsius = PropBag.ReadProperty("Celsius", 30)
      m_TemperatureDate = PropBag.ReadProperty _
      ("TemperatureDate", DateSerial(1997, 1, 1))
      m_caption = PropBag.ReadProperty ("Caption", Extender.Name)
      BackColor = PropBag.ReadProperty  ("BackColor", Ambient.BackColor)      
      lblCaption.Caption = m_caption                                        
End Sub

—