Advanced Hosting Interfaces

Advanced Hosting Interfaces


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.

arrowy.gifICustomDoc Interface

arrowy.gifIDocHostUIHandler Interface

arrowy.gifIDocHostShowUI Interface

ICustomDoc Interface

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

ICustomDoc::SetUIHandler

HRESULT SetUIHandler(
    IDocHostUIHandler *pUIHandler
);

Sets IE4/MSHTML's IDocHostUIHandler.

pUIHandler
Address of the host's IDocHostUIHandler interface.

IE4/MSHTML will release its previous IDocHostUIHandler interface (if one is present) and call pUIHandler's AddRef method.

IDocHostUIHandler Interface

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:
ShowContextMenu
GetHostInfo
ShowUI
HideUI
UpdateUI
EnableModeless
OnDocWindowActivate
OnFrameWindowActivate
ResizeBorder
TranslateAccelerator
GetOptionKeyPath
GetDropTarget
GetExternal
TranslateUrl
FilterDataObject

The following are the structures and enumerations used with the IDocHostUIHandler interface:
DOCHOSTUIINFO
DOCHOSTUIDBLCLK
DOCHOSTUIFLAG

IDocHostUIHandler::EnableModeless

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.

fEnable
Indicates if the host's modeless dialog boxes are enabled or disabled. If this value is nonzero, modeless dialog boxes are enabled. If this value is zero, modeless dialog boxes are disabled.

IDocHostUIHandler::FilterDataObject

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.

pDO
Address of the IDataObject interface supplied by IE4/MSHTML.
ppDORet
Address that receives the IDataObject interface pointer supplied by the host. The contents of this parameter should always be initialized to NULL, even if the method fails.

IDocHostUIHandler::GetDropTarget

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.

pDropTarget
IDropTarget IE4/MSHTML proposes to use.
ppDropTarget
Address of the IDropTarget that receives the IDropTarget interface pointer the host wants to provide.

IDocHostUIHandler::GetExternal

HRESULT GetExternal(
    IDispatch **ppDispatch    
);

Called by IE4/MSHTML to obtain the host's IDispatch interface.

ppDispatch
Address that receives the IDispatch interface pointer of the host application. If the host exposes an automation interface, it can provide a reference to IE4/MSHTML through this parameter. The contents of this parameter should always be initialized to NULL, even if the method fails.

IDocHostUIHandler::GetHostInfo

HRESULT GetHostInfo( 
    DOCHOSTUIINFO FAR *pInfo
);

Retrieves the UI capabilities of the IE4/MSHTML host.

pInfo
Address of a DOCHOSTUIINFO structure that receives the host's UI capabilities.

IDocHostUIHandler::GetOptionKeyPath

HRESULT GetOptionKeyPath( 
    LPOLESTR *pchKey,
    DWORD dwReserved
);

Returns the registry key under which IE4/MSHTML stores user preferences.

pchKey
Address of an LPOLESTR that receives the registry subkey string where the host stores its default options. This subkey will be under the HKEY_CURRENT_USER key. The implementation must allocate this memory using CoTaskMemAlloc. The calling application is responsible for freeing this memory using CoTaskMemFree. Even if the method fails, this parameter should be set to NULL.
dwReserved
Reserved for future use. Not currently used.

If pchKey is null on return from this function, then IE4/MSHTML uses the default location for storing options in the registry.

IDocHostUIHandler::HideUI

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.

IDocHostUIHandler::OnDocWindowActivate

HRESULT OnDocWindowActivate (
    BOOL fActive
);

Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::OnDocWindowActivate.

fActive
Indicates the state of the document window. If this value is nonzero, the window is being activated. If this value is zero, the window is being deactivated.

IDocHostUIHandler::OnFrameWindowActivate

HRESULT OnFrameWindowActivate (
    BOOL fActive
);

Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::OnFrameWindowActivate.

fActive
Indicates the state of the container's top-level frame window. If this value is nonzero, the window is being activated. If this value is zero, the window is being deactivated.

IDocHostUIHandler::ResizeBorder

HRESULT ResizeBorder( 
    LPCRECT prcBorder,
    IOleInPlaceUIWindow FAR *pUIWindow,
    BOOL fFrameWindow
);

Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::ResizeBorder.

prcBorder
New outer rectangle for border space.
pUIWindow
Frame or document window border change.
fFrameWindow
Indicates TRUE if the frame window is calling ResizeBorder, or FALSE otherwise.

IDocHostUIHandler::ShowContextMenu

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.

dwID
Identifier of the context menu to be displayed.
ppt
Screen coordinates for the menu.
pcmdtReserved
The IOleCommandTarget interface used to query command status and execute commands on this object.
pdispReserved
The IDispatch interface of the object at the screen coordinates. This allows a host to differentiate particular objects to provide more specific context.

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

IDocHostUIHandler::ShowUI

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.

dwID
Reserved for future use.
pActiveObject
The IOleInPlaceActiveObject interface of the currently active object.
pCommandTarget
The IOleCommandTarget interface of the object.
pFrame
The IOleInPlaceFrame interface of the object. This is needed for menus and toolbars.
pDoc
The IOleInPlaceUIWindow interface for the object. This is needed for toolbars.

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.

IDocHostUIHandler::TranslateAccelerator

HRESULT TranslateAccelerator( 
    LPMSG lpMsg,
    const GUID FAR *pguidCmdGroup,
    DWORD nCmdID
);

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

lpMsg
Points to the message that might need to be translated.
pguidCmdGroup
Command group identifier.
nCmdID
Command identifier.

IDocHostUIHandler::TranslateUrl

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.

dwTranslate
Reserved for future use.
pchURLIn
Address of a string supplied by IE4/MSHTML that represents the URL to be translated.
ppchURLOut
Address of a string pointer that receives the address of the translated URL. The host allocates the buffer using the task memory allocator. The contents of this parameter should always be initialized to NULL, even if the URL is not translated or the method fails.

IDocHostUIHandler::UpdateUI

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.

IDocHostUIHandler Structures and Enumerations

The following are the structures and enumerations used with the IDocHostUIHandler interface.

DOCHOSTUIINFO
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.

cbSize
Size of this structure, in bytes.
dwFlags
One or more of the DOCHOSTUIFLAG values that specify the UI capabilities of the host.
dwDoubleClick
One of the DOCHOSTUIDBLCLK values that specify the operation that should take place in response to a double-click.
DOCHOSTUIFLAG
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.

DOCHOSTUIFLAG_DIALOG
IE4/MSHTML will not allow selection of the text in the form.
DOCHOSTUIFLAG_DISABLE_HELP_MENU
IE4/MSHTML will not display context menus.
DOCHOSTUIFLAG_NO3DBORDER
IE4/MSHTML does not use 3-D borders.
DOCHOSTUIFLAG_SCROLL_NO
IE4/MSHTML does not have scroll bars.
DOCHOSTUIFLAG_DISABLE_SCRIPT_INACTIVE
IE4/MSHTML will not execute any script when loading pages.
DOCHOSTUIFLAG_OPENNEWWIN
IE4/MSHTML will open a site in a new window when a link is clicked rather than browse to the new site using the same browser window.
DOCHOSTUIFLAG_DISABLE_OFFSCREEN
Not implemented or used.
DOCHOSTUIFLAG_FLAT_SCROLLBAR
IE4/MSHTML will use flat scroll bars for any UI it displays. Not currently supported.
DOCHOSTUIFLAG_DIV_BLOCKDEFAULT
IE4/MSHTML will insert the <DIV> tag if a return is entered in edit mode. Without this flag, IE4/MSHTML will use the <P> tag.
DOCHOSTUIFLAG_ACTIVATE_CLIENTHIT_ONLY
IE4/MSHTML will only become UI-active if the mouse is clicked in the client area of the window. It will not become UI-active if the mouse is clicked on a nonclient area, such as a scroll bar.
DOCHOSTUIDBLCLK
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.

DOCHOSTUIDBLCLK_DEFAULT
Perform the default action.
DOCHOSTUIDBLCLK_SHOWPROPERTIES
Show the item's properties.
DOCHOSTUIDBLCLK_SHOWCODE
Show the page's source.

IDocHostShowUI Interface

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

IDocHostShowUI::ShowHelp

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.

hwnd
Handle to the owner window.
pszHelpFile
Help file name.
uCommand
Type of Help. See the WinHelp function.
dwData
Additional data. See the WinHelp function.
ptMouse
Mouse position in screen coordinates.
pDispatchObjectHit
IDispatch of the object at the screen coordinates.

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.

IDocHostShowUI::ShowMessage

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.

hwnd
Handle to the owner window.
lpstrText
Text for the message box.
lpstrCaption
Caption for the message box.
dwType
Type flags (taken from the MessageBox MB_xxxx constants).
lpstrHelpFile
Help file name.
dwHelpContext
Help context identifier.
plResult
Button clicked by user (taken from the MessageBox IDxxx constants).

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.