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
The window object is at the top level of this hierarchy. The window has a
document property, which in turn has its own set of properties. Please
consult the appropriate SDK for further details.
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:
- Getting to the top level of the object model.
- Drilling down into 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.
This will put you at the top level (window object) in the object model.
Then use automation to drill down further.
Obtaining the IWebBrowserApp
Getting the IWebBrowserApp is a two-step process:
- Use the IOleClientSite pointer to get IServiceProvider. In an ATL
control, this pointer can be obtained by accessing the m_spClientSite
member of the control. In an MFC control, this pointer can be obtained
by calling COleControl::GetClientSite(). 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);
- Use the IServiceProvider to obtain IWebBrowserApp. Using the
IServiceProvider, a QueryService can be done to get the IWebBrowserApp:
pISP->QueryService(SID_SWebBrowserApp, IID_IWebBrowserApp,
(void **)&pIWebBrowserApp));
Also, if you are programming for Internet Explorer 4 or later, you can
obtain a pointer to the IWebBrowser2 interface of the container with this
code:
pISP->QueryService(IID_IWebBrowserApp, IID_IWebBrowser2,
(void **)&pIWebBrowser2));
QueryService is different from QueryInterface in that it does not have to
follow the identity rule in COM. So, if the object itself does not
implement IWebBrowserApp, it can delegate to the containing object and
QueryService it for a IWebBrowserApp.
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:
- 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 );
Check the return value from the above call. If the control is not embedded
within an HTML page, or if the container is not Internet Explorer 4.0, then
the above call will fail.
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 Parent property gets to the automation object. Then the script property
gives us the window object of the scripting object model. Then the
different properties and methods can be accessed just like any other
automation object.
The above line of code should read as follows:
Parent.Script.document.bgColor = "Blue"
Even though using get_document is correct in Internet Explorer 3.x, it will
not work in Internet Explorer 4.0. The correct method is to use the
document property. This will work both in Internet Explorer 3.x and 4.0.
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.