
This document describes the interfaces used for customizing the behavior of IE4/MSHTML objects. In addition to the interfaces described here, IE4/MSHTML can be customized through a number of interfaces that match IE4/MSHTML's Object Model. For a more general overview of IE4/MSHTML's hosting and extensibility mechanisms, see Reusing MSHTML.
The ICustomDoc interface is implemented by IE4/MSHTML to allow a host to set IE4/MSHTML's IDocHostUIHandler interface. Normally, IE4/MSHTML will call the host client site's QueryInterface method to obtain the IDocHostUIHandler interface. IE4/MSHTML implements ICustomDoc so that a host that does not implement a client site can still use IE4/MSHTML's UI customization features.
ICustomDoc is derived from IUnknown. The following is the ICustomDoc specific method:
| SetUIHandler |
HRESULT SetUIHandler(
IDocHostUIHandler *pUIHandler
);
Sets IE4/MSHTML's IDocHostUIHandler.
IE4/MSHTML will release its previous IDocHostUIHandler interface (if one is present) and call pUIHandler's AddRef method.
A host can replace the menus, toolbars, and context menus used by IE4/MSHTML by implementing the IDocHostUIHandler interface. IE4/MSHTML will obtain this interface by calling the host's client site QueryInterface, requesting IID_IDocHostUIHandler. This interface has methods that allow IE4/MSHTML to communicate with the host about its UI status.
IDocHostUIHandler is derived from IUnknown. The following are the methods specific to IDocHostUIHandler:
The following are the structures and enumerations used with the IDocHostUIHandler interface:
| DOCHOSTUIINFO |
| DOCHOSTUIDBLCLK |
| DOCHOSTUIFLAG |
HRESULT EnableModeless(
BOOL fEnable
);
Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::EnableModeless. Also called when IE4/MSHTML displays modal UI. The host should enable or disable its modeless UI as appropriate.
HRESULT FilterDataObject(
IDataObject *pDO,
IDataObject **ppDORet
);
Called on the host by IE4/MSHTML to allow the host to replace IE4/MSHTML's data object. This allows the host to block certain clipboard formats or support additional clipboard formats.
HRESULT GetDropTarget(
IDropTarget *pDropTarget,
IDropTarget **ppDropTarget
);
Called by IE4/MSHTML when it is being used as a drop target to allow the host to supply an alternative IDropTarget.
| S_OK | The host wants to replace the IDropTarget with the one specified in ppDropTarget. |
| S_FALSE | The host does not want to replace the IDropTarget. |
| E_NOTIMPLE | The host has not implemented this method. |
HRESULT GetExternal(
IDispatch **ppDispatch
);
Called by IE4/MSHTML to obtain the host's IDispatch interface.
HRESULT GetHostInfo(
DOCHOSTUIINFO FAR *pInfo
);
Retrieves the UI capabilities of the IE4/MSHTML host.
HRESULT GetOptionKeyPath(
LPOLESTR *pchKey,
DWORD dwReserved
);
Returns the registry key under which IE4/MSHTML stores user preferences.
If pchKey is null on return from this function, then IE4/MSHTML uses the default location for storing options in the registry.
HRESULT HideUI(void);
Called when IE4/MSHTML removes its menus and toolbars.
If a host displayed menus and toolbars during the call to IDocHostUIHandler::ShowUI, the host should remove them when this method is called. This method is called regardless of the return value from the ShowUI method.
HRESULT OnDocWindowActivate (
BOOL fActive
);
Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::OnDocWindowActivate.
HRESULT OnFrameWindowActivate (
BOOL fActive
);
Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::OnFrameWindowActivate.
HRESULT ResizeBorder(
LPCRECT prcBorder,
IOleInPlaceUIWindow FAR *pUIWindow,
BOOL fFrameWindow
);
Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::ResizeBorder.
HRESULT ShowContextMenu(
DWORD dwID,
POINT FAR *ppt,
IUnknown FAR *pcmdtReserved,
IDispatch FAR *pdispReserved
);
Called from IE4/MSHTML when it is about to show its context menu.
| S_OK | Host displayed its own UI. IE4/MSHTML will not attempt to display its UI. |
| S_FALSE | Host did not display any UI. IE4/MSHTML will display its UI. |
| DOCHOST_E_UNKNOWN | Menu identifier is unknown. IE4/MSHTML may attempt an alternative identifier from a previous version. |
The following menu identifiers are currently used. Note: These identifiers are likely to change and are not currently exposed in a header file as part of the IE4/MSHTML SDK.
| #define CONTEXT_MENU_DEFAULT 0 |
| #define CONTEXT_MENU_IMAGE 1 |
| #define CONTEXT_MENU_CONTROL 2 |
| #define CONTEXT_MENU_TABLE 3 |
| #define CONTEXT_MENU_DEBUG 4 |
| #define CONTEXT_MENU_1DSELECT 5 |
| #define CONTEXT_MENU_ANCHOR 6 |
| #define CONTEXT_MENU_IMGDYNSRC 7 |
HRESULT ShowUI(
DWORD dwID,
IOleInPlaceActiveObject FAR *pActiveObject,
IOleCommandTarget FAR *pCommandTarget,
IOleInPlaceFrame FAR *pFrame,
IOleInPlaceUIWindow FAR *pDoc
);
Allows the host to replace the IE4/MSHTML menus and toolbars.
| S_OK | Host displayed its own UI. IE4/MSHTML will not display its UI. |
| S_FALSE | Host did not display its own UI. IE4/MSHTML will display its UI. |
| DOCHOST_E_UNKNOWN | Host did not recognize the UI identifier. IE4/MSHTML will either try an alternative identifier for compatibility with a previous version or display its own UI. |
This method is called just before IE4/MSHTML displays its menus and toolbars. If the host returns S_FALSE from this method, IE4/MSHTML does not display its UI and assumes that the host is handling the UI.
If the host makes use of any of the interfaces handed to it as part of this function, it should call the interface's AddRef method if it is to be saved for later use. If the host calls the interface's AddRef method, it must also call the interface's Release method when the interface is no longer required.
A host can disable modeless UI on IE4/MSHTML by calling IOleCommandTarget::Exec with IDM_DISABLEMODELESS and IDM_ENABLEMODELESS.
HRESULT TranslateAccelerator(
LPMSG lpMsg,
const GUID FAR *pguidCmdGroup,
DWORD nCmdID
);
Called by IE4/MSHTML when IOleInPlaceActiveObject::TranslateAccelerator or IOleControlSite::TranslateAccelerator is called.
HRESULT TranslateUrl(
DWORD dwTranslate,
OLECHAR *pchURLIn,
OLECHAR **ppchURLOut
);
Called by IE4/MSHTML to allow the host an opportunity to modify the URL to be loaded.
HRESULT UpdateUI(void);
Notifies the host that the command state has changed.
The host should update the state of toolbar buttons. This method is called regardless of the return value from the ShowUI method.
The following are the structures and enumerations used with the IDocHostUIHandler interface.
typedef struct _DOCHOSTUIINFO{
ULONG cbSize;
DWORD dwFlags;
DWORD dwDoubleClick;
}DOCHOSTUIINFO;
Used by the IDocHostUIHandler::GetHostInfo method to allow IE4/MSHTML to retrieve information about the host's UI requirements.
typedef enum tagDOCHOSTUIFLAG{
DOCHOSTUIFLAG_DIALOG = 1,
DOCHOSTUIFLAG_DISABLE_HELP_MENU = 2,
DOCHOSTUIFLAG_NO3DBORDER = 4,
DOCHOSTUIFLAG_SCROLL_NO = 8,
DOCHOSTUIFLAG_DISABLE_SCRIPT_INACTIVE = 16,
DOCHOSTUIFLAG_OPENNEWWIN = 32,
DOCHOSTUIFLAG_DISABLE_OFFSCREEN = 64,
DOCHOSTUIFLAG_FLAT_SCROLLBAR = 128
DOCHOSTUIFLAG_DIV_BLOCKDEFAULT = 256,
DOCHOSTUIFLAG_ACTIVATE_CLIENTHIT_ONLY = 512
}DOCHOSTUIFLAG;
Defines a set of flags that indicate the capabilities of a IDocHostUIHandler implementation.
typedef enum tagDOCHOSTUIDBLCLK{
DOCHOSTUIDBLCLK_DEFAULT = 0,
DOCHOSTUIDBLCLK_SHOWPROPERTIES = 1,
DOCHOSTUIDBLCLK_SHOWCODE = 2
}DOCHOSTUIDBLCLK;
Defines values used to indicate the proper action on a double-click event.
A host can supply mechanisms for message boxes and Help to be shown by implementing the IDocHostShowUI interface. IE4/MSHTML will obtain this interface by calling the host's client site QueryInterface, requesting IID_IDocHostShowUI. The site is the object that implements the IOleDocumentSite and IOleClientSite interfaces.
IDocHostShowUI is derived from IUnknown. The following are the methods specific to IDocHostShowUI.
| ShowHelp |
| ShowMessage |
HRESULT STDMETHODCALLTYPE ShowHelp(
HWND hwnd,
LPOLESTR pszHelpFile,
UINT uCommand,
DWORD dwData,
POINT ptMouse,
IDispatch *pDispatchObjectHit
);
Called by IE4/MSHTML when it needs to show Help.
| S_OK | Host displayed Help. IE4/MSHTML will not display its Help. |
| S_FALSE | Host did not display Help. IE4/MSHTML will display its Help. |
The first four parameters are the same as those passed to the WinHelp function. The ptMouse parameter gives the screen coordinates, and the pDispatchObjectHit parameter allows the host to differentiate the object at the screen coordinates to a greater degree than IE4/MSHTML.
HRESULT ShowMessage(
HWND hwnd,
LPOLESTR lpstrText,
LPOLESTR lpstrCaption,
DWORD dwType,
LPOLESTR lpstrHelpFile,
DWORD dwHelpContext,
LRESULT *plResult
);
Called by IE4/MSHTML when it needs to display a message box.
| S_OK | Host displayed its UI. IE4/MSHTML will not display its message box. |
| S_FALSE | Host did not display its UI. IE4/MSHTML will display its message box. |
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.