Visual Basic Concepts

Determining the ActiveX Document's Container Programmatically

The characteristics of your user's target application have a large impact on your ActiveX document design. Consequently, your code should verify which container is being used in order to react appropriately. For example, if you intend your document to be viewed in the Visual Basic Development Environment Tool Window, your code should check the container before accessing extensibility objects (which are unavailable in Internet Explorer).

To determine the container of the ActiveX document, use the TypeName statement with the Parent property of the UserDocument. A simple example of this is shown:

Dim strContainer As String
strContainer = TypeName(UserDocument.Parent)

The following table shows the three possible strings returned by Internet Explorer, Microsoft Binder, and the window created by the CreateToolWindow function in the Visual Basic development environment:

Container	Return String
Internet Explorer	IwebBrowserApp
Microsoft Binder	Section
Window	Window

Defensive Programming

Because you may never know which container the user will actually use to view an ActiveX document, you should prepare for the "wrong" container (a container which lacks the features your ActiveX document needs to function optimally). Although the TypeName function will not return the version of the container, it will at least allow you to determine if the container is unequivocally "wrong." In that case, you may inform the user that some functionality is not available with the container, and that she should use the "right" container to view the document.

Because the Show event occurs when an ActiveX document is sited on the container, it is the best event for determining the container. Be aware, however, that the Show event occurs whenever the document is shown (and this behavior varies according to the container application). To sidestep this problem, declare a module level variable to function as a flag. After verifying the container, the flag is reset. Subsequent Show events will then check the flag, and avoid redundantly checking the container again.

Option Explict
Private mblnSHOWN As Boolean

Private Sub UserDocument_Show()
   If Not mblnSHOWN Then
      Dim strContainer As String
      strContainer = TypeName(UserDocument.Parent)
      ' Use the Select Case statement to test.
      Select Case strContainer
         Case "IwebBrowserApp"
         ' Supported container: continue to open app.
      Case "Section"
         ' Supported container: continue to open app.
      Case Else ' Handle other unknown containers.
         ' Unsupported container: exit gracefully.
         MsgBox "Sorry, please open this " & _
         "document with Internet Explorer " & _
         "3.0 or later."
         End Select
      mblnSHOWN = True ' Reset the flag
   End If
End Sub

Note   You can't use the Initialize event to test the container because when that event fires the document is not yet sited. For an explanation of when the document is sited, see "Key Events in the Life of a UserDocument" in this chapter.