INFO: Accessing the Object Model from Within an ActiveX Control

• Microsoft Internet Explorer (Programming), versions 3.01, 3.02, 4.0
• Internet Client SDK, version 4.01

SUMMARY

When writing an ActiveX control for the Internet, it may often be necessary to access the object model of the HTML page. The object model allows access to various elements within the HTML page.

This article discusses accessing the object model from Visual C++ and from Visual Basic, and covers both Internet Explorer (IE) 3.x and 4.0.

MORE INFORMATION

THE OBJECT MODEL

Documentation for the object model can be found in the ActiveX Software Development Kit (SDK) and the Internet Client SDK for Internet Explorer 3.x and 4.0, respectively. The object model is documented as follows:

   window
      - location
      - frames
      - ...
      - document
         - links
         - forms
            - elements

WHY SHOULD A CONTROL NEED TO ACCESS THE OBJECT MODEL?

A control can access (and in some cases modify) information about the page that it is embedded in. To do so, the control must access the object model. For example, a control can enumerate all of the elements on a page. In the case of dynamic HTML, the control can access almost any HTML element in the page.

ACCESSING THE OBJECT MODEL

The object model is implemented using automation and COM interfaces. Once the control is able to access the top level of the object model, then it can drill down the object model using automation or COM interfaces. This article discusses both steps:

1. Getting to the top level of the object model.

GETTING TO THE TOP LEVEL OF THE OBJECT MODEL (VISUAL C++)

Using IWebBrowserApp (for Internet Explorer 3.x and 4.x)

IWebBrowserApp is an interface that is exposed by the Web Browser control. It has a document property (or get_document method if using vtable interface) that allows access to the automation object of the active document. If the document is an HTML document, then the automation object has a script property that gives the window object of the scripting object model. So, for a control to reach the object model, the following must be done:

• Obtain IWebBrowserApp from its containing HTML page.
• Get the document property of IWebBrowserApp.
• Get the script property of the document.

Obtaining the IWebBrowserApp

Getting the IWebBrowserApp is a two-step process:

1. Use the IOleClientSite pointer to get IServiceProvider. The control has access to the IOleClientSite interface of its container. It can use that pointer to QI for IServiceProvider:

         pClientSite->QueryInterface(IID_IServiceProvider,
                             (void **)&pISP);
   
   

2. Use the IServiceProvider to obtain IWebBrowserApp. Using the IServiceProvider, a QueryService can be done to get the IWebBrowserApp:

         pISP->QueryService(IID_IWebBrowserApp, IID_IWebBrowserApp,
                       (void **)&pIWebBrowserApp));
   
   

Get the Document Property of IWebBrowserApp

IWebBrowserApp is a dual interface. It has a document property and also a get_Document method. Either can be used to get the IDispatch of the active document. Once you have the IDispatch, then the script property can be obtained.

Get the Script Property of the Document

Using the IDispatch obtained above, get the script property using automation. This will give the top level in the scripting object model, or the window object.

GETTING THE TOP LEVEL OF THE OBJECT MODEL (VISUAL C++)

(Internet Explorer 4.0 ONLY)

Internet Explorer 4.0 makes accessing the object model much easier. This is a one-step process:

1. Get the IHTMLDocument2 from the IClientSite.

Obtaining IHTMLDocument2 from IOleClientSite

Every control has access to IClientSite of its container. QI-ing for IHTMLDocument2 from the client site should give the scripting object model.

   IOleContainer* pContainer = NULL;
   IHTMLDocument2* pDoc = NULL;

   pClientSite->GetContainer( &pContainer );
   if ( pContainer != NULL )
      pContainer->QueryInterface( &IID_IHTMLDocument2, &pDoc );

Getting IHTMLDocument2 gives the document object in the scripting object model. Then either automation interfaces or vtable interfaces can be used to drill down the object model.

GETTING THE TOP LEVEL OF OBJECT MODEL (VISUAL BASIC)

The parent property of the UserControl can be used to access the automation object. From the Visual Basic documentation for the parent property, Internet Explorer returns an object whose Script property returns the IOmWindow object.

The example given in Visual Basic documentation is as follows:

   Parent.Script.get_document.bgColor = "Blue"

The above line of code should read as follows:

   Parent.Script.document.bgColor = "Blue"

DRILLING DOWN THE OBJECT MODEL

Drilling down the object model is as simple as calling the properties and methods using automation. For Internet Explorer 3.x, use only automation. For Internet Explorer 4.0, vtable interfaces can be used. For more information refer to the driller sample in the Internet Client SDK.