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:
- 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
Minimum supported client |
Windows XP |
Minimum supported server |
Windows 2000 Server |
Header |
Mshtmhst.h |
IDL |
Mshtmhst.idl |