Visual Basic Concepts

  • Article

Key Events in the Life of an ActiveX Document

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:

  • The Initialize event occurs every time an instance of your document is created or re-created. It is always the first event in an ActiveX document’s lifetime.

  • The InitProperties event occurs only as long as none of the ActiveX document properties have been saved using the PropertyBag. Once a property value has been saved, this event will be replaced by the ReadProperties event.

  • The ReadProperties event occurs instead of the InitProperties event only after a property has been saved using the PropertyBag. You must add code to actually read the property.

  • The EnterFocus event occurs when any object, including the ActiveX document, receives focus.

  • The ExitFocus event occurs when no object on the ActiveX document, including the document itself, has focus any longer.

  • The Resize event occurs every time a container is resized.

  • The Scroll event occurs whenever the user clicks on the container's scrollbar or the scrolling region of the container, or if the user drags the scrollbar. Note: Scrollbars appear on the container only when the container's Viewport is sized smaller than the MinWidth or MinHeight of the UserDocument.

  • The WriteProperties event occurs immediately before the Terminate event, when, during the life of the ActiveX document, at least one property value has changed. To notify the container that a property has changed, use the PropertyChanged statement. This is covered in greater detail in "Persisting ActiveX Document Data" in this chapter.

  • The Terminate event occurs when the ActiveX document is about to be destroyed. You can use the Termination event to clean up any object references by setting all global object references to Nothing.

    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.

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:

  • The Show event occurs whenever the user navigates to the document (in a browser). You can use this event to check for global object references set by other ActiveX documents.

  • The Show event occurs after the ActiveX document is fully sited in the container (unlike the Initialize property). Because you can't count on the InitProperties event to always occur, the Show event can be used as another event to verify the container. See "Determining the ActiveX Document's Container Programmatically" in this chapter for an example.

  • The Hide event occurs whenever the user navigates off the document (in a browser). The event also occurs immediately before the Terminate event. Use the event to destroy any global object references before navigating to another document.

    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.