IDocHostUIHandler Interface

Enables an application that is hosting the WebBrowser Control or automating Windows Internet Explorer to replace the menus, toolbars, and context menus used by MSHTML.

IDocHostUIHandler Members

EnableModeless	Called by the MSHTML implementation of IOleInPlaceActiveObject::EnableModeless. Also called when MSHTML displays a modal UI.
FilterDataObject	Enables the host to replace the MSHTML data object.
GetDropTarget	Enables the host to supply an alternative IDropTarget interface.
GetExternal	Gets the host's IDispatch interface.
GetHostInfo	Gets the UI capabilities of the application that is hosting MSHTML.
GetOptionKeyPath	Gets a registry subkey path that overrides the default Internet Explorer registry settings.
HideUI	Enables the host to remove its menus and toolbars.
OnDocWindowActivate	Called by the MSHTML implementation of IOleInPlaceActiveObject::OnDocWindowActivate.
OnFrameWindowActivate	Called by the MSHTML implementation of IOleInPlaceActiveObject::OnFrameWindowActivate.
ResizeBorder	Called by the MSHTML implementation of IOleInPlaceActiveObject::ResizeBorder.
ShowContextMenu	Enables MSHTML to display a shortcut menu.
ShowUI	Enables the host to replace MSHTML menus and toolbars.
TranslateAccelerator	Called by MSHTML when IOleInPlaceActiveObject::TranslateAccelerator or IOleControlSite::TranslateAccelerator is called.
TranslateUrl	Enables the host to modify the URL to be loaded.
UpdateUI	Notifies the host that the command state has changed.

Remarks

The IID for this interface is BD3F23C0-D43E-11CF-893B-00AA00BDCE1A.

On initialization, MSHTML calls QueryInterface on the host's client site, and requests an IDocHostUIHandler interface. If available, MSHTML calls the IDocHostUIHandler methods at appropriate times during the lifetime of the MSHTML component.

MSHTML implements IDocHostUIHandler to communicate with the host about its user interface status. The host can also implement this interface to extend, replace, or disable the default UI elements, such as menus, context menus, and toolbars. When replacing or disabling elements, the host merely returns S_OK, S_FALSE, or E_NOTIMPL from most methods. When extending the user interface, the host should delegate as necessary to the default MSHTML implementation.

The following C++ with Active Template Library (ATL) example demonstrates how to retrieve the default implementation and replace it with a custom UI handler.

Copy

// If this is an HTML document...
ComPtr<IDispatch> spDocument;
hr = spWebBrowser2->get_Document(&spDocument);
if (SUCCEEDED(hr) && (spDocument != nullptr))
{
    // Request default handler from MSHTML client site
    ComPtr<IOleObject> spOleObject;
    if (SUCCEEDED(spDocument.As(&spOleObject)))
    {
        ComPtr<IOleClientSite> spClientSite;
        hr = spOleObject->GetClientSite(&spClientSite);
        if (SUCCEEDED(hr) && spClientSite)
        {
            // Save pointer for delegation to default 
            m_spDefaultDocHostUIHandler = spClientSite;
        }
    }
    
    // Set the new custom IDocHostUIHandler
    ComPtr<ICustomDoc> spCustomDoc;
    if (SUCCEEDED(spDocument.As(&spCustomDoc)))
    {
        // NOTE: spHandler is user-defined class
        spCustomDoc->SetUIHandler(spHandler.Get());
    }
} 

The ICustomDoc interface is designed for applications that host MSHTML directly. It is not intended to replace an existing IDocHostUIHandler that is provided by Internet Explorer or the WebBrowser control. If you try to replace that interface from a Browser Helper Object (BHO) using ICustomDoc, you may experience unexpected behavior such as memory leaks.

To avoid a memory leak:

• Always forward the IDocHostUIHandler::ShowUI and IDocHostUIHandler::HideUI methods to the original handler.
• Release the pointer to the original UI handler when your object is called with IObjectWithSite::SetSite(NULL).

Interface Information

Stock Implementation	None
Custom Implementation	Yes
Inherits from	IUnknown
Header and IDL files	mshtmhst.h, mshtmhst.idl
Minimum availability	Internet Explorer 4.0
Minimum operating systems	Windows 95, Windows NT 4.0, Windows CE 2.12

See Also

ICustomDoc::SetUIHandler