Persisting ActiveX Document Data

See Also

Data persistence is the ability of a component to store and retrieve data. How an ActiveX document persists data depends greatly on the container application in which the document appears. Some applications allow you to persist data by writing to an interface of the application. For example, the Internet Explorer 3.0 (and higher) and Microsoft Office Binder allows you to write to a file using the PropertyBag. Other applications, however, do not provide any such intrinsic method of storing data. In those cases, you must use another method, such as writing data to files. Let's start with the PropertyBag.

The PropertyBag

The PropertyBag is an object that allows you to save data to a file. The file can be either the .vbd, .obd, or some other kind of file — it depends on the application. The PropertyBag has two methods, the WriteProperty method, and the ReadProperty method. The PropertyBag object is exposed as part of the WriteProperties and ReadProperties event declaration.

Saving Data with the WriteProperty Method

The process of saving data is outlined:

1. In an event that occurs when a property has changed, invoke the PropertyChanged method. The method notifies the container that a property has changed.
   
   
2. In response to the PropertyChanged method, the container is "dirtied." And before the container terminates, the WriteProperties event occurs.
   
   
3. In the WriteProperties event, use the WriteProperty method to save the property to the .vbd file.

The following code shows a simple illustration of this process:

Private Sub Text1_Change()
   PropertyChanged "Text" ' Notify container a 
                           ' property has changed.
End Sub

Private Sub UserDocument_WriteProperties _
   (PropBag As VB.PropertyBag)
   ' Write the Property to the Property Bag.
   UserDocument.WriteProperty "Text1", Text1.Text, _
      "Hello"
End Sub

Reading Properties

The next time the ActiveX document is opened, the ReadProperties event occurs. The PropertyBag is available in the event, and you can retrieve the persisted data using the ReadProperty method. The following code retrieves the data stored in the preceding code:

Private Sub UserDocument_ReadProperties _
   (PropBag As VB.PropertyBag)
   ' Read the property back into the TextBox control.
   Text1.Text = ReadProperty("Text1", "Hello")
End Sub

Saving a Default Value

You may have noticed that two code samples included an extra argument: the default value "Hello." Why provide a default when saving the property value? Before saving the value, the WriteProperty method compares the property value with this default. If they are the same, the property value doesn’t have to be saved, because default values will be set automatically when the control is reloaded. This keeps the data file from being cluttered with hundreds of default entries.

Saving Binary Data

It's also possible to write and read binary data to the PropertyBag. This becomes useful if you have data that is stored in binary form. For example, you may have a graphics file that is stored in a custom format.

The process of saving binary data differs slightly from that of saving control properties:

1. Declare a module-level byte array.
   
   
2. In an appropriate event, use the ReDim statement, and store the binary data in the array.
   
   
3. Invoke the PropertyChanged method.
   
   
4. In the WriteProperties event, save the byte array using the WriteProperty method.

These steps are shown in the following simple implementation:

Private mbytMyData() As Byte ' Declare byte array.

Private Sub cmdSavePic_Click()
   ReDim mbytMyData(1 to 5000)
   ' Code to move data into byte array not shown.
   PropertyChanged
End Sub

Private Sub UserDocument_WriteProperties(PropBag As _
   VB.PropertyBag)
   PropBag.WriteProperties "myPic", mbytMyData
End Sub

Persisting Data Using the Open Statement

If you are using a container that does not support the PropertyBag, or if you are saving User Defined Type (UDT) data, use the Open statement to read and write the data to disk. Instructions on using the Open statement can be found in "Using Sequential File Access" in "Processing Drives, Folders, and Files" of the Programmer's Guide.

For More Information   To learn the do's and don'ts of adding properties to a components, see "Adding Properties And Methods to Classes," in "General Principles of Component Design."