Reusing MSHTMLReusing MSHTML*
*



Contents  *



Index  *Topic Contents
*Previous Topic: RefreshConstants
*Next Topic: Advanced Hosting Interfaces

Reusing MSHTML

IE4/MSHTML is a rendering engine and parser for HTML. It is the main HTML component of the IE4 Web browser and can be reused in other applications. It hosts ActiveX™ Controls and supports the OC96 specification for windowless controls. Controls that use the OC96 interfaces can gain in performance, and they can be transparent and have an irregular shape.

IE4/MSHTML itself is an Active Document, so it may be hosted by implementing the Active Document interfaces in an application. IE4/MSHTML can also be customized by aggregation to create a special-purpose HTML Active Document. Applications that contain IE4/MSHTML supply their own toolbars and menu UI. The container can also override the default context menus.

It is also possible to use IE4/MSHTML without UI activation to make use of IE4/MSHTML's ability to parse HTML. By loading HTML, you can use the object model to access the underlying HTML and modify any elements. COM objects hosted by IE4/MSHTML (such as ActiveX Controls) also have the ability to access the Dynamic HTML object model and, as a result, closely integrate with the IE4/MSHTML container to affect the host.

For many purposes, it is more appropriate to host the WebBrowser control to integrate browsing into an application. The WebBrowser control implements support for in-place linking and navigation in addition to IE4/MSHTML. For additional information on the WebBrowser control, see Reusing the WebBrowser and MSHTML.

arrowy.gifContaining IE4/MSHTML

arrowy.gifReplacing IE4/MSHTML's User Interface

arrowy.gifSubstituting User Preferences

arrowy.gifLoading HTML and Referenced Data

arrowy.gifAutomating IE4/MSHTML

arrowy.gifScripts within IE4/MSHTML

arrowy.gifSending and Receiving Commands

arrowy.gifTerminology

Containing IE4/MSHTML

IE4/MSHTML can be hosted to form an integral part of an application. There are two ways that this can be done.

  1. Host IE4/MSHTML as an Active Document. IE4/MSHTML is an Active Document and can be hosted in an application that implements the Active Document Hosting interfaces. In this mode of operation, IE4/MSHTML supplies its own UI for context menus to the containing application, although the container can replace the UI, if required, by implementing additional interfaces.
  2. Aggregate IE4/MSHTML to create an Active Document. If a host needs to provide extra services and functionality, but it still needs to be an Active Document for use within another application, it can do so by aggregating IE4/MSHTML. This allows the host to take advantage of IE4/MSHTML's implementation of Active Document server interfaces without having to re-implement them. This still allows the host to wrap IE4/MSHTML to provide additional functionality and its own UI.

Hosting IE4/MSHTML as an Active Document

As an Active Document, IE4/MSHTML follows the standard OLE mechanisms for negotiating with the container for menu merging and displaying its toolbars. IE4/MSHTML supports only the single view implementation of Active Documents. Commands can be sent and received using the IOleCommandTarget interface that is also part of the Active Document specification. The standard NULL command set is supported as well as a set of extended commands specific to IE4/MSHTML.

A host of IE4/MSHTML can turn off IE4/MSHTML's menus and toolbars and supply its own UI. The host may also intercept any of IE4/MSHTML's UI, such as context menus and message boxes. For more information about intercepting UI, see Replacing IE4/MSHTML's User Interface. For more information about implementing an Active Document host, see Programming an Active Document Container.

Aggregating IE4/MSHTML

If your application is using IE4/MSHTML to implement an Active Document that customizes IE4/MSHTML's behavior, a host may aggregate with IE4/MSHTML to create a new class. IE4/MSHTML is designed to support aggregation. Overriding a small number of interfaces can customize much of IE4/MSHTML's behavior.

Creating a new Active Document

The minimum interfaces that need to be supplied by an aggregator are IOleObject and the IPersist* interfaces.

These interfaces supply the object's ClassID and UserType (through IOleObject::GetUserClassID, IOleObject::GetUserType, and IPersist::GetClassID methods). The aggregator should supply its own implementations to differentiate the new object from IE4/MSHTML.

Some common functionality that can be customized by aggregation includes:

Other customization can be done by supplying services to IE4/MSHTML.

Supplying services and ambient properties when aggregating

IE4/MSHTML provides or uses interfaces that allow an aggregator to supply ambient properties to it without having to implement a full client site for hosting IE4/MSHTML. The site object normally supplies ambient properties, but a site object has a number of other interfaces that are not trivial to implement. Using this technique, the aggregator can let the container's client site pass through to IE4/MSHTML while the aggregator still supplies ambient properties.

Replacing IE4/MSHTML's User Interface

If IE4/MSHTML is tightly integrated into an application, it may be desirable to have the application supply its own menus, toolbars and other UI. To do this, the host can supply optional services to IE4/MSHTML that allow the host to hook into and replace IE4/MSHTML's UI. In implementing these interfaces, a host knows that IE4/MSHTML is the component being hosted and has knowledge of IE4/MSHTML's command set.

When replacing IE4/MSHTML's UI, the host turns off IE4/MSHTML's menus and toolbars and can replace them. This does not involve any negotiation. A host of IE4/MSHTML can display message boxes, Help UI, and all in-place active UI on behalf of IE4/MSHTML by implementing two interfaces, IDocHostUIHandler and IDocHostShowUI.

To replace the menus, toolbars, and other UI for IE4/MSHTML, the host should implement the IDocHostUIHandler interface. IE4/MSHTML will obtain this interface by calling the host's client site QueryInterface, requesting IID_IDocHostUIHandler. If the host does not implement a client site, it can QueryInterface IE4/MSHTML for the ICustomDoc interface and call the ICustomDoc::SetUIHandler method to set IE4/MSHTML's UI handler.

When IDocHostUIHandler is present, IE4/MSHTML delegates a number of IOleInPlaceObject and IOleInPlaceActiveObject methods directly to it, allowing a host to hook into methods such as IOleInPlaceActiveObject::TranslateAccelerator and IOleInPlaceActiveObject::ResizeBorder. Returning S_OK on the IDocHostUIHandler::ShowUI method called by IE4/MSHTML will cause IE4/MSHTML to hide its menus and toolbars and not call the IOleInPlaceFrame methods for menu merging and border space negotiation.

To supply message boxes and Help UI, the host should implement the IDocHostShowUI interface. IE4/MSHTML will obtain this interface by calling the host's client site QueryInterface, requesting IID_IDocHostShowUI. The site object implements both IOleDocumentSite and IOleClientSite.

Substituting User Preferences

As IE4/MSHTML may be used in a number of different host environments, there is a requirement that each host environment be able to set different default user preferences in the registry. IE4/MSHTML allows its host to specify a special registry key under which to store the default preferences.

IE4/MSHTML calls IDocHostUIHandler::GetOptionKeyPath on the host at initialization to allow the host to specify the registry location for the preference settings. IE4/MSHTML then uses this registry key to store and get the settings for its preference property pages. If the host returns S_FALSE for this method, or the returned registry key path is NULL or empty, then IE4/MSHTML will revert to its own default set of options.

Loading HTML and Referenced Data

There are three situations where IE4/MSHTML needs to resolve URLs or load data:

  1. When an HTML page is loaded into IE4/MSHTML. IE4/MSHTML is capable of loading pages from URLs (or any other asynchronous moniker) or from files.
  2. When data (for example, an <IMG> tag) is referred to on the HTML page. A host can optionally supply a service to IE4/MSHTML to assist in resolving these references.
  3. When a hyperlink needs to be followed. IE4/MSHTML invokes the standard hyperlinking API. A host may optionally provide the hyperlinking support so that IE4/MSHTML can link to the new object within the host frame.

Loading an HTML page

For a host to get IE4/MSHTML to load and display the page at a specific URL, the host constructs a moniker using the CreateURLMoniker API call. Then it calls IPersistMoniker::Load on IE4/MSHTML. IE4/MSHTML's implementation of IPersistMoniker is specifically designed to support the loading of data asynchronously over slow links.

More information about these interfaces can be found in the Asynchronous and URL Monikers Overview section of the Internet Client SDK.

IE4/MSHTML is also capable of simple synchronous loading and saving of HTML through IPersistStreamInit or asynchronous loading from a file through IPersistFile.

Resolving Hyperlinks

If a user clicks on a link within an HTML page viewed in IE4/MSHTML, IE4/MSHTML will call the HlinkNavigate API (after having set up an IHlink object). If the host does not implement IHlinkFrame, this API launches a separate application to follow the hyperlink.

Hosts that wish to act as browsers (and navigate within the same frame) can implement IHlinkFrame on the FRAME object. The HlinkNavigate API calls IHlinkFrame::Navigate, allowing a browser application to hide the previous instance of IE4/MSHTML and create, load, and show a new instance of IE4/MSHTML (or other Active Document) to display the new page.

For more information on hyperlinking, see Hyperlinks.

Because the WebBrowser control has built-in support for hyperlinking, hosting the WebBrowser control is the preferred solution here.

Automating IE4/MSHTML

IE4/MSHTML can be automated using IDispatch and IConnectionPointContainer-style automation interfaces. These interfaces allow a host to automate IE4/MSHTML through the object model.

Scripts within IE4/MSHTML

IE4/MSHTML is responsible for loading and running scripts that appear within HTML. Because scripting is done by using the ActiveX Scripting interfaces, any ActiveX script engine can be hosted by IE4/MSHTML.

For more information about ActiveX scripting engines and hosts, see ActiveX Scripting.

Sending and Receiving Commands

Because IE4/MSHTML is an Active Document, it communicates with its host using the IOleCommandTarget interface. With this interface, the following details are communicated to the hosting frame.

In addition to the standard command group, IE4/MSHTML supports a group of IE4/MSHTML-specific commands that provide simple access to a number of IE4/MSHTML-specific features. For more information, see the OLECMDID enumeration.

Terminology

ActiveX™ Control – Also known as an OLE Control. An ActiveX Control is a contained mini-application. It can (optionally) maintain state, draw itself, persist itself, have its own window, respond to automation methods, throw events, take keyboard focus, respond to mouse and keyboard input, and show merged menu and toolbar UI. Most of the control interfaces are documented in MSDN. The OC96 and OLE Controls/COM Objects for the Internet specifications introduce a number of new interfaces for controls to improve their performance and make them suitable for the Internet. Further extensions supported by IE4/MSHTML are discussed later in this section.

Active Document – Also known as an OLE Document Object or Doc Object. An Active Document is a contained object; the container provides the frame and some basic UI. In such containers, the Active Document may be interchanged with other Active Documents while the containing frame and its UI remain constant. Examples of Active Document containers include the Office Binder and Internet Explorer 3.0x, where the Active Document could change to Microsoft® Word or Excel while maintaining the same outer frame application. An Active Document is similar to an OLE Embedding scenario or an ActiveX Control, but its interfaces are designed to support an object that is at the top level and takes up the entire content area of the frame. There are specific interfaces required to support Active Document functionality. For more information, see Active Documents.

ActiveX Scripting – A standard set of interfaces that allows for language-independent script integration to applications. Any script engine (VBScript, JScript, or a third party scripting language, for example) that supports the standard interfaces can be integrated with an ActiveX script host such as IE4/MSHTML.

IE4/MSHTML – An Active Document that is capable of rendering HTML and laying out contained ActiveX Controls. In this document, it refers to an instance of the IE4/MSHTML COM object that implements IOleObject, IOleDocument, IOleDocumentView, and many other interfaces.

Aggregation – A kind of run-time inheritance. By aggregating, an object can extend and enhance the functionality of another object but still take advantage of the functionality and interfaces of the aggregated object. Objects can be designed to be aggregated or not. IE4/MSHTML is designed to be aggregated.

Site – The object supplied by a container to a contained object through IOleObject::SetClientSite. Containers of an ActiveX object must supply a site before doing anything else. IE4/MSHTML gets much of its information about its geometry, activation, ambient properties, and so on, from its container site. (In this specification, there's no distinction between IE4/MSHTML's container document site and its view site.) IE4/MSHTML also supplies a site for each ActiveX Control it hosts.

Container – The ActiveX object that owns the site obtained through IOleClientSite::GetContainer (may be null). From the container, the contained objects may be enumerated through IOleContainer::EnumObjects. This concept of containment should not be confused with the concept of containment used for scripting and supplied by automation interfaces. Some contained automation objects are not contained ActiveX objects, and some contained ActiveX objects cannot be automated.

Frame – The outer application frame, with menu and toolbar space, supplied to an ActiveX object through IOleInPlaceSite::GetWindowContext. This is the object with which IE4/MSHTML negotiates for menu and toolbar space and also for hyperlinks.

Document Window – The document window, with toolbar space, supplied to an ActiveX object through IOleInPlaceSite::GetWindowContext. (In MDI it is the document window, and in SDI it is NULL.) IE4/MSHTML currently ignores the document window.

Command – A simple action sent to an ActiveX object through the IOleCommandTarget interface. Commands usually correspond to user-level commands, like the commands on menus, and can be enabled or disabled by the command target. A command can be sent to the frame, the container site, IE4/MSHTML, or a control.

Automation – A set of standards to allow an object to be programmed by scripts. Every object that can be automated can have methods and properties that can be used by a script, as well as events that can trigger scripts to be run.

Dispatch Interface – An interface inheriting from IDispatch that is used to access named automation properties and methods of an object from a script.

Event Interface – A callback interface attached to an object using IConnectionPointContainer. Used by script engines to get notification of events thrown by objects.

Type Info – A structure used to specify properties, methods, and events (automatable or otherwise). Can be obtained from a dispatch interface through IDispatch or an object that supplies IProvideClassInfo*.

X Object – An object that IE4/MSHTML wraps around each hosted control to supply common, per-control, container-owned properties and events. IE4/MSHTML aggregates the X object to the control, if possible, and merges types with the control.

Service – A service supplied by the host to an ActiveX object through the IServiceProvider interface on the container site. Each service is identified by a service identifier (SID), allowing access to interfaces and methods.

Ambient – A property owned by the container and supplied to an ActiveX object through the IDispatch interface on its hosting site.

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