Key Events in the Life of an ActiveX Document

See Also

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.

A Note on Siting

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."

A Note on Saving Properties

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.

Key UserDocument Events

The meanings of the key events in the life of a UserDocument object are as follows:

Opening an ActiveX Document Before Saving Properties

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.

Opening an ActiveX Document After Saving Properties

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.

Show and Hide Events

Possibly, the two most important events for an ActiveX document are the Show and Hide events.

These events are especially important for these reasons:

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.