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.

Members

The IDocHostUIHandler interface inherits from the IUnknown interface. IDocHostUIHandler also has these types of members:

• Methods

Methods

The IDocHostUIHandler interface has these methods.

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.

// 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).

Requirements

See also

ICustomDoc::SetUIHandler