Partager via


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.

Method Description
IDocHostUIHandler::EnableModeless

Called by the MSHTML implementation of IOleInPlaceActiveObject::EnableModeless. Also called when MSHTML displays a modal UI.

IDocHostUIHandler::FilterDataObject

Enables the host to replace the MSHTML data object.

IDocHostUIHandler::GetDropTarget

Enables the host to supply an alternative IDropTarget interface.

IDocHostUIHandler::GetExternal

Gets the host's IDispatch interface.

IDocHostUIHandler::GetHostInfo

Gets the UI capabilities of the application that is hosting MSHTML.

IDocHostUIHandler::GetOptionKeyPath

Gets a registry subkey path that overrides the default Internet Explorer registry settings.

IDocHostUIHandler::HideUI

Enables the host to remove its menus and toolbars.

IDocHostUIHandler::OnDocWindowActivate

Called by the MSHTML implementation of IOleInPlaceActiveObject::OnDocWindowActivate.

IDocHostUIHandler::OnFrameWindowActivate

Called by the MSHTML implementation of IOleInPlaceActiveObject::OnFrameWindowActivate.

IDocHostUIHandler::ResizeBorder

Called by the MSHTML implementation of IOleInPlaceActiveObject::ResizeBorder.

IDocHostUIHandler::ShowContextMenu

Enables MSHTML to display a shortcut menu.

IDocHostUIHandler::ShowUI

Enables the host to replace MSHTML menus and toolbars.

IDocHostUIHandler::TranslateAccelerator

Called by MSHTML when IOleInPlaceActiveObject::TranslateAccelerator or IOleControlSite::TranslateAccelerator is called.

IDocHostUIHandler::TranslateUrl

Enables the host to modify the URL to be loaded.

IDocHostUIHandler::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.

// 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:

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows 2000 Server

Header

Mshtmhst.h

IDL

Mshtmhst.idl

See also

ICustomDoc::SetUIHandler