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
Calling the PropertyChanged Method to Trigger WriteProperties
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 event, 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 (see Listing 13.8). 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 stored 'in Private variable m_Celsius = sValue
'invoke UserControl's PropertyChanged method 'so it knows to trigger WriteProperties and 'store new value PropertyChanged ("Celsius")
'perform other housekeeping specific to this application
Sliderl.Value = m_Celsius RecalcFahrenheitFromCelsius sValue DisplayTempsFromSlider End If End Property
Was this article helpful?