OverviewOverview*
*



Contents  *



Index  *Topic Contents
*Previous Topic: Programming the Document Object Model from C/C++
*Next Topic: ICSSFilter

Overview


All interfaces for accessing the dynamic HTML object model are based on IDispatch and are the basis of access to the object model that is also used by scripts. It is therefore important that anyone using the interfaces to manipulate the object model also be familiar with the structure and functionality as defined in the Dynamic HTML overviews and Object Model references.

The Interfaces and Scripting Objects section shows how objects within the Dynamic HTML object model map to the interfaces. For example, using this map, you can see that the IHTMLDocument2 interface maps to the document object. Further examination of the interface shows how the properties of the document object are available through get_ and put_ methods. The object's methods map to methods available in the interface, and events can be hooked up using standard OLE Automation connection points.

Examples of how to use the object model interfaces can be seen in the following samples in the Internet Client SDK:

Recommendations for Using the Interfaces

Usually, anything that can be done using script within the document can also be performed using the interfaces to manipulate the object model. It is therefore recommended that before writing code to use the object model interfaces, developers should prototype the functionality using script within an HTML document.

The following HTML example shows how to navigate the all collection of the document and obtain the tag name of each element in the document using script. The equivalent C++ code is demonstrated in the Driller and WalkAll samples of the Internet Client SDK using the object model interfaces. 

<HTML>
<HEAD>
    <TITLE>Page Title</TITLE>
</HEAD>

<SCRIPT LANGUAGE="JavaScript">
    function Loaded()
        {
        var c = document.all.length;
        var i;
        for(i=0; i < c; i++)
            {
            spanTAGS.innerHTML = spanTAGS.innerHTML + document.all.item(i).tagName + "<BR>"; 
            } 
        }
</SCRIPT>

<BODY onload="Loaded()">

    <SPAN id="spanTAGS"></SPAN>

</BODY>
</HTML>

Obtaining the Document Interface

To start using the object model interfaces, you need to obtain the IHTMLDocument2 interface for the document. Once you have this interface, you can access all the elements within the document. How the document interface is obtained depends upon how your application is being implemented. Each scenario listed below requires that the document interface be obtained in a different manner.

Obtaining the document interface when hosting MSHTML

When hosting an MSHTML object, you create the object using CoCreateInstance. Once the object is created, you can call its QueryInterface method, requesting IID_IHTMLDocument2. The WalkAll sample in the Internet Client SDK demonstrates how to do this.

Obtaining the document interface when hosting the WebBrowser control

When hosting the WebBrowser control, you perform the following steps to obtain the document pointer:

  1. Call IWebBrowser2::get_Document to obtain the document's IDispatch pointer.
  2. Call QueryInterface on the IDispatch pointer obtained in the previous step, requesting IID_IHTMLDocument2.

Obtaining the document interface from an ActiveX control

The Accessing Dynamic HTML section of the ActiveX Controls documentation details how to obtain the document interface from an ActiveX control.

Using the Document Interface

Once you have obtained the document interface, you can use any of the IHTMLDocument2 interfaces to obtain or modify the document's properties. This will most commonly involve getting some of the IHTMLElementCollection interfaces for the different element collections contained in the document.

A very common collection is the all collection. The all collection is obtained using the IHTMLDocument2::get_all method. This method returns an IHTMLElementCollection interface that contains all the elements in the document. You can then enumerate the elements using the IHTMLElementCollection::item method. The IHTMLElementCollection::item method supplies you with an IDispatch pointer that you can call QueryInterface on, requesting IID_IHTMLElement. This will give you an IHTMLElement interface pointer that you can use to obtain or set information for the individual element.

Most elements provide an interface for working with that specific element. These element-specific interface names take the format of IHTMLXXXXElement, where XXXX is the name of the element. To obtain the element-specific interface, you simply call QueryInterface on the IHTMLElement interface, requesting the element-specific interface that is desired. For example, the IMG element provides an IHTMLImgElement interface that can be used to work with the image element specifically. For a list of the element-specific interfaces that are available, see the interface listing in Programming the Document Object Model from C/C++.

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.