About MSHTML
All interfaces for accessing the Dynamic HTML (DHTML) 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 defined in the Introduction to Dynamic HTML overview and in the object model references included in MSHTML.
The Interfaces and Scripting Objects section of the MSHTML Reference shows how objects within the DHTML 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 are demonstrated in the Colbtn, Driller, and WalkAll samples on the Colbtn Sample Source Page, the Driller Sample Source Page and the WalkAll Sample Source Page.
- Recommendations for Using the Interfaces
- Obtaining the Document Interface
- Obtaining the Document Interface when Hosting MSHTML
- Obtaining the Document Interface when Hosting the WebBrowser Control
- Obtaining the Document Interface from an ActiveX Control
- Using the Document Interface
- Related topics
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 Microsoft Visual C++ code is demonstrated in the Driller and WalkAll samples on the Driller Sample Source Page and the WalkAll Sample Source Page 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, 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 on how your application is being implemented. Each of the following scenarios requires that the document interface be obtained in a different manner.
- When hosting an MSHTML object.
- When hosting an instance of the WebBrowser Control.
- From a Microsoft ActiveX control contained in a page.
Obtaining the Document Interface when Hosting MSHTML
When hosting an MSHTML object, create the object using CoCreateInstance. Once the object is created, you can call its QueryInterface method, requesting IID_IHTMLDocument2. The WalkAll sample on the WalkAll Sample Source Page demonstrates how to do this.
Obtaining the Document Interface when Hosting the WebBrowser Control
When hosting the WebBrowser Control, perform the following steps to obtain the document pointer:
- Call IWebBrowser2::get_Document to obtain the document's IDispatch pointer.
- 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 explains 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::all property, which returns an IHTMLElementCollection interface that contains all the elements in the document. You can then enumerate the elements using the item method. The item method provides you with an IDispatch pointer on which you can call QueryInterface, 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, 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 img element specifically. For a list of the available element-specific interfaces, see the interface listing in Interfaces and Scripting Objects.
Related topics
Conceptual
Introduction to MSHTML Editing