Visual Basic Concepts

  • Article

Targeting an ActiveX Document Container

ActiveX documents, like ActiveX controls, cannot be used alone. ActiveX documents must exist in a container, which is itself an object. Most ActiveX documents, however, will be viewed in an application that provides an object that is the actual container of the ActiveX document. Throughout this document, we will therefore refer to these applications as container applications, or applications that can contain an ActiveX document.

Here are three containers, and their advantages:

  • Microsoft Internet Explorer (version 3.0 or later) — Using Internet Explorer, an ActiveX document can be a familiar version of an existing application with added Internet capabilities. For example, an existing application can be enhanced with Web links (using the Hyperlink object). You can also deploy the ActiveX document over the Internet, allowing users to get the latest version of your application.

    Note   The deployment of ActiveX documents differs slightly depending on the version of Internet Explorer that you are targeting. For more information on deploying ActiveX documents, see "Manually Deploying ActiveX Components" in Building Internet Applications.

  • Microsoft Office Binder 1.0 (or later) — The Microsoft Binder is an electronic "paper clip" that can hold several disparate documents, such as Word and Excel documents. Use an ActiveX document to add database programming or multimedia display capabilities to binders. For example, a repair manual assembled as a binder of Word documents could be enhanced by the addition of a Visual Basic ActiveX document that displayed video clips of repair procedures.

  • Visual Basic Development Environment Tool Window — The Visual Basic Environment Tool Window is an object created by the CreateToolWindow function. Using this function, you can create a dockable window in the Visual Basic development environment. This window can then contain ActiveX documents that provide additional user interface capabilities to the development environment. For instance, you could create a resource editor or menu editor using the Visual Basic Extensibility Object Model.

Issues for Containers

Because the capabilities of an ActiveX document can depend on the host application, you should consider the following questions:

  • Will this document depend on the features of a particular host application?

    For example, if you are creating an ActiveX document that will run in Internet Explorer, you may want to exploit its ability to show an ActiveX document in one frame, and HTML documents in another.

  • Will I be creating a suite of documents that work together?

    For example, if the document is a simple calculator, it will probably not demand more than a single ActiveX document, and the answer is "no."

If the answer to either of these is "yes," then you will need to investigate the capabilities of the target application(s). Specifically, you will want to know how to navigate from one ActiveX document to another (if you are creating a suite of documents), or how to access the features of the host application. Other than documentation from the creator of the container application, the only way to discover the object model is by using the Object Browser.

One Example: One Goal, Two Containers

To illustrate this, let's examine a multi-document scenario. Imagine you have created two ActiveX documents, and want to open the second by clicking on a button on the first.

If the host application is Internet Explorer, you must use the Hyperlink object's NavigateTo method to get from one document to another, as shown in the following code:

Private Sub cmdGoTo_Click()
   ' Assuming the name of the
   ' destination is AxDoc2.vbd.
   UserDocument.HyperLink.NavigateTo _
      "file://c:\docs\AxDoc2.vbd"
End Sub

On the other hand, Microsoft Binder operates on an entirely different metaphor. Instead of navigating to another document, you must add a section to the Binder. An example of the code is shown in the following:

Private Sub cmdAddSection_Click()
   ' Use the same document: AxDoc2.
   UserDocument.Parent.Parent.Sections. _
      Add , "c:\docs\AxDoc2.vbd"
End Sub

Looking Into the Target Application's Object Model

From the preceding two different methods shown, it becomes apparent that you cannot count on one method to get from one ActiveX document to another in every container. The question then becomes, "How do I discover the method for a target host application?"

One way (besides documentation) to discover an application's methods is to use the Object Browser. For example, to explore the object model of Microsoft Binder, follow these steps:

To discover the objects and methods of Microsoft Binder

Note   You must have Microsoft Office Binder 1.0 or later, which can be installed with Microsoft Office.

  1. On the Project menu, click References.

  2. In the scrolling list of available references, click OLE Automation Binder 1.0 Type Library (or Microsoft Binder 8.0 Object Library for Office ’97).

  3. Click OK.

  4. Press F2 to open the Object Browser.

  5. Click the Project/Library Box, and then click Office Binder.

  6. In the Classes List, click Sections.

  7. In the Members of List, click Add. You will now see the syntax of the Add method, which you can use to add the ActiveX document to the Sections collection.

You may have noticed that the Object Browser hasn't given you a complete guide to the object model. Compare the code:

UserDocument.Parent.Parent.Sections.Add _
, "c:\docs\AxDoc2.vbd"

with the information found in the Object Browser. The difference lies in the addition of "UserDocument.Parent.Parent" to the code.

The discrepancy arises because the ActiveX document is itself "buried" lower within the object model. To Office Binder, the ActiveX document is just one more Section object in a Sections collection. Thus the code TypeName(UserDocument.Parent) returns "Section," while TypeName(UserDocument.Parent.Parent) returns "Binder."

In order to navigate through the hierarchy to the top of the object model, the code uses the reference returned by the Parent property. However the code must navigate one final level — again using the Parent property. This results in the Parent.Parent code. The code then navigates back down to the Sections collection, culminating in the Add method.

For More Information   To learn about the Object Browser, see "Finding Out About Objects," in "Programming With Objects," of the Programmer's Guide. For details about navigating through the Object Model, see "Navigating Object Models" in "Programming with Components," of the Programmer's Guide.