The design of an ActiveX document depends greatly on the application(s) you are targeting. All containers are not created equal, and this is especially evident when considering events. However, before examining the events, read the two following notes, which affect the availability and behavior of key events.
Like an ActiveX control, an ActiveX document cannot exist by itself. It must be placed in a container. The process of hooking an ActiveX document up to its container is called siting — that is, assigning the ActiveX document a site in the container.
It's only after an ActiveX document has been sited that the properties of the container become available to it. For example, the UserDocument object's Parent property (which returns a reference to the container) is not available until the ActiveX document is sited. The Hyperlink object is also unavailable until the document has been sited.
For More Information Because of the similarity of ActiveX document creation to ActiveX control creation, you may wish to peruse "Control Creation Terminology" in "Building ActiveX Controls."
If a container application supports the PropertyBag, you can easily save and retrieve data to a file — whether it saves to the .vbd file or not depends upon the application. For example, Internet Explorer saves data to the .vbd file, but Office Binder saves all data to the .obd (Office Binder Data) file. However, once data has been saved, the InitProperties will not occur; instead, the ReadProperties event will replace it. Similarly, the WriteProperties event will not occur until the user saves a property.
For More Information To find out how to save properties with the PropertyBag, see "Persisting ActiveX Document Data" in this chapter.
The meanings of the key events in the life of a UserDocument object are as follows:
Note In Internet Explorer 4.0, the ActiveX document will be terminated as soon as the user navigates away from the document. In Internet Explorer 3.0, an ActiveX document is stored in a cache of four documents. When the user loads or navigates to a fifth document, the ActiveX document will be terminated.
When the user opens an ActiveX document on which no properties have been saved, the following events will occur.
Event | What Gets Done |
Initialize | Document created but not sited in container yet. |
InitProperties | Default values for properties are set. |
Show | The document is shown in the container. The document has been sited in the container, therefore container properties become available. |
EnterFocus | The document gets focus. |
If the user has saved any property, the ReadProperties event will occur instead of the InitProperties event.
Event | What Gets Done |
Initialize | Document created but not sited in container yet. |
ReadProperties | Properties are read through the PropertyBag object's ReadProperties method. |
Show | The document is shown in the container. |
EnterFocus | The document gets focus. |
Possibly, the two most important events for an ActiveX document are the Show and Hide events.
These events are especially important for these reasons:
Note In Internet Explorer 3.0, an ActiveX document is stored in a cache of four documents. When the user loads or navigates to a fifth document, the ActiveX document will be terminated. The Hide event will occur when the user navigates off the ActiveX document to another document, or when Internet Explorer 3.0 is terminated while the document is being viewed or is still within the cache of active documents.
For More Information The topic "Life Cycle of a UserDocument," one of the step by step procedures in "Creating an ActiveX Document" demonstrates the key events in the life of an ActiveX document.