Life Cycle of a UserDocument

See Also

The life of an ordinary Visual Basic form is marked by certain key events, such as Initialize, Load, QueryUnload, and Unload. In order to create well-behaved applications, it’s important to know when these events occur in the life cycle of a form.

Although ActiveX documents look like forms, they behave differently, primarily because they are contained by another application. When programming an ActiveX document, some attention must be given to the ephemeral nature of an ActiveX document. This is especially true when the container application is a Web browser, such as Internet Explorer.

Key events in the life cycle of a UserDocument object include Initialize, InitProperties, Show, Hide, and Terminate. The following procedure demonstrates these events.

Note   This topic is part of a series that walks you through creating a sample ActiveX control. It begins with the topic Creating an ActiveX Document.

To observe the key events of the FirstDoc UserDocument

1. In the Project Explorer window, double-click FirstDoc to bring its designer forward.
   
   
2. Double-click the designer to open a Code window for the UserDocument object, and enter code in the following event procedures:

   Private Sub UserDocument_Initialize()
      Debug.Print "Initialize"
   End Sub
   
   Private Sub UserDocument_InitProperties()
      Debug.Print "InitProperties" 
   End Sub
   
   Private Sub UserDocument_Show()
      Static intCount As Integer
      intCount = intCount + 1
      Debug.Print "Show " & intCount
   End Sub
   
   Private Sub UserDocument_Hide()
      Static intCount As Integer
      intCount = intCount + 1
      Debug.Print "Hide " & intCount
   End Sub
   
   Private Sub UserDocument_Terminate()
      Debug.Print "Terminate"
   End Sub
   

3. Run the project by pressing f5.
   
   
4. In Internet Explorer, view the ActiveX document by navigating to the URL of the FirstDoc.vbd file, or by clicking the arrow next to the Address box and selecting FirstDoc.vbd from the list.
   
   
5. Press ALT+TAB to bring Visual Basic back to the front of your window. Notice in the Immediate window that three events — Initialize, InitProperties, and Show — have been printed to the window. As with the UserControl object, the Intialize event precedes InitProperties.

   Note   You will notice that Show is followed by a 1, indicating that the ActiveX document has been shown once by Internet Explorer. As long as a reference to the ActiveX document exists in the Internet Explorer cache, this number will increment once each time you navigate to the ActiveX document from another URL.

6. Press ALT+TAB to return to Internet Explorer. Navigate another  URL, either by typing a valid URL into the Address box of Internet Explorer, or using your list of Favorites. It does not matter which HTML page you navigate to.
   
   
7. After navigating to the new URL, press ALT+TAB to switch back to Visual Basic. In the Immediate window you will notice that the Hide and Terminate events have occurred.
   
   
8. Press ALT+TAB to return to Internet Explorer. Click Back until the FirstDoc ActiveX document is once again in view.
   
   
9. Press ALT+TAB again to switch back to Visual Basic. Notice in the Immediate window that the Initialize, InitProperties, and Show events have been fired.

The Initialize and InitProperties Events

The Initialize and InitProperties events have some similarities, but you should be aware of how they differ. In brief, the Initialize event always occurs when the ActiveX document is loaded, while InitProperties will only occur every time until the document is saved. After that event has fired, the ReadProperties and WriteProperties events will fire. To see an example of this:

1. If Internet Explorer is still running, close it.
   
   
2. If the ActXDoc project is still running, stop it. This is necessary in order to see the InitProperties event occur.
   
   
3. Restart the ActXDoc project.
   
   
4. In Internet Explorer type the path of the FirstDoc.vbd file in the Address box , or select it from the drop-down URL history list.
   
   
5. Type something distinctive into the TextBox (txtFirstDoc) control.
   
   
6. Close Internet Explorer. You will be prompted to save your changes. Click Yes.
   
   
7. Restart Internet Explorer. (Do not stop the ActXDoc project.)
   
   
8. Press ALT+TAB to return to Visual Basic.
   
   
9. Note in the Immediate window that InitProperties occurred only once: the first time that the FirstDoc document was viewed in Internet Explorer. The second time you viewed the FirstDoc document the Initialize event occurred, but not the InitProperties; instead, the ReadProperties event occurred.

   You should note this behavior, as it impacts where you place your code. Needless to say, if you always want a procedure to run on startup, you should put it into the Initialize event. If you want a procedure to run only the first time a user views your ActiveX document, place it in the InitProperties event.

   You should be cautious, however, about the limitations of using the Initialize event. In brief, any procedures that require knowledge of the container (such as the Parent property) are unavailable when the Initialize event occurs. An alternate event that occurs after the ActiveX document has been sited in the container is the Show event.