|
|
|
IDocHostUIHandler2 Interface |
|
IID_IDocHostUIHandler2 |
{3050F6D0-98B5-11CF-BB82-00AA00BDCE0B} |
|
This custom interface extends IDocHostUIHandler with a method that facilitates Microsoft Internet Explorer registry changes.
On initialization,
MSHTML calls QueryInterface on the host's client site, requesting an
IDocHostUIHandler2 interface. If available, MSHTML will call
IDocHostUIHandler2 methods at appropriate times during the lifetime of
the MSHTML component.
|
|
Methods in VTable order |
|
|
IUnknown Methods |
Description |
|
QueryInterface |
Returns pointers to supported interfaces. |
|
AddRef |
Increments reference count. |
|
Release |
Decrements reference count. |
|
IDocHostUIHandler Members |
Description |
|
ShowContextMenu |
Called by MSHTML to display a shortcut menu. |
|
GetHostInfo |
Called by MSHTML to retrieve the user interface (UI) capabilities of the application that is hosting MSHTML. |
|
ShowUI |
Called by MSHTML to enable the host to replace MSHTML menus and toolbars. |
|
HideUI |
Called when MSHTML removes its menus and toolbars. |
|
UpdateUI |
Called by MSHTML to notify the host that the command state has changed. |
|
EnableModeless |
Called by the MSHTML implementation of IOleInPlaceActiveObject::EnableModeless. Also called when MSHTML displays a modal UI. |
|
OnDocWindowActivate |
Called by the MSHTML implementation of IOleInPlaceActiveObject::OnDocWindowActivate. |
|
OnFrameWindowActivate |
Called by the MSHTML implementation of IOleInPlaceActiveObject::OnFrameWindowActivate. |
|
ResizeBorder |
Called by the MSHTML implementation of IOleInPlaceActiveObject::ResizeBorder. |
|
TranslateAccelerator |
Called by MSHTML when IOleInPlaceActiveObject::TranslateAccelerator or IOleControlSite::TranslateAccelerator is called. |
|
GetOptionKeyPath |
Called by the WebBrowser Control to retrieve a registry subkey path that overrides the default Internet Explorer registry settings. |
|
GetDropTarget |
Called by MSHTML when it is used as a drop target. This method enables the host to supply an alternative IDropTarget interface. |
|
GetExternal |
Called by MSHTML to obtain the host's IDispatch interface. |
|
TranslateUrl |
Called by MSHTML to give the host an opportunity to modify the URL to be loaded. |
|
FilterDataObject |
Called by MSHTML to allow the host to replace the MSHTML data object. |
|
IDocHostUIHandler2 Member |
Description |
|
GetOverrideKeyPath |
Called by the WebBrowser Control to retrieve a registry subkey path that modifies Internet Explorer user preferences. |
|
Sample code to set our custom IDocHostUIHandler2 interface |
' ********************************************************************************************
' DocumentComplete
' Member identifier: &H00000103 (259)
' Fires when a document has been completely loaded and initialized.
' ********************************************************************************************
SUB DWebBrowserEvents2_DocumentComplete (BYVAL pCookie AS DWebBrowserEvents2_IDispatchVtbl PTR, BYREF pdispparams AS DISPPARAMS)
' Retrieve the IDispatch of the control that has fired the event.
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' Pointers to access the parameters.
LOCAL pv AS VARIANT PTR : pv = pdispparams.VariantArgs
LOCAL pvapi AS VARIANTAPI PTR : pvapi = pv
' Get the values of the parameters.
LOCAL pDisp AS DWORD : pDisp = VARIANT#(@pv[1])
LOCAL URL AS VARIANT : URL = @pv[0]
' ======================================================================================
' After the MSHTML document has been loaded we retrieve a reference to his CustomDoc
' interface and give him a pointer to our IDocHostUIHandler interface to allow for
' customization.
' ======================================================================================
LOCAL hr AS LONG
LOCAL ppDoc AS DWORD
LOCAL ppCustomDoc AS DWORD
LOCAL ppDocHostUIHandler AS DWORD
LOCAL IID_ICustomDoc AS GUID
LOCAL IID_IDocHostUIHandler AS GUID
' Get a reference to the active document
ppDoc = IWebBrowser2_GetDocument(pthis)
IF ISFALSE ppDoc THEN EXIT SUB
' Get a reference to the CustomDoc interface
IID_ICustomDoc = GUID$("{3050f3f0-98b5-11cf-bb82-00aa00bdce0b}")
hr = DWebBrowserEvents2_IUnknown_QueryInterface(ppDoc, IID_ICustomDoc, ppCustomDoc)
' Release the IHTMLDocument2 interface (no longer needed)
WbRelease ppDoc
' Exit on QueryInterface failure
IF ISFALSE ppCustomDoc THEN EXIT SUB
' Create an instance of the IDocHostUIHandler interface
ppDocHostUIHandler = IDocHostUIHandler2_BuildVtbl(pthis)
' Set our IDocHostUIHandler interface for MSHTML
' MSHTML will call AddRef for the new interface and Release for the old (if any).
' Also, Release will be also called when you will close the application, so don't
' release here ppDocHostUIHandler or your application will crash.
IF ppDocHostUIHandler THEN ICustomDoc_SetUIHandler ppCustomDoc, ppDocHostUIHandler
' Release the CustomDoc interface (no longer needed)
DWebBrowserEvents2_IUnknown_Release ppCustomDoc
' ======================================================================================
END SUB
' ********************************************************************************************
|
|
IDocHostUIHandler2 interface implementation |
' ****************************************************************************************
' IDocHostUIHandler2 interface
' This custom interface extends IDocHostUIHandler with a method that facilitates Microsoft
' Internet Explorer registry changes.
' ****************************************************************************************
$IID_IDocHostUIHandler2 = GUID$("{3050F6D0-98B5-11CF-BB82-00AA00BDCE0B}")
' ****************************************************************************************
' enum DOCHOSTUITYPE
' ****************************************************************************************
%DOCHOSTUITYPE_BROWSE = 0
%DOCHOSTUITYPE_AUTHOR = 1
' ****************************************************************************************
' enum DOCHOSTUIDBLCLK
' ****************************************************************************************
%DOCHOSTUIDBLCLK_DEFAULT = 0
%DOCHOSTUIDBLCLK_SHOWPROPERTIES = 1
%DOCHOSTUIDBLCLK_SHOWCODE = 2
' ****************************************************************************************
' enum DOCHOSTUIFLAG
' ****************************************************************************************
%DOCHOSTUIFLAG_DIALOG = &H1
%DOCHOSTUIFLAG_DISABLE_HELP_MENU = &H2
%DOCHOSTUIFLAG_NO3DBORDER = &H4
%DOCHOSTUIFLAG_SCROLL_NO = &H8
%DOCHOSTUIFLAG_DISABLE_SCRIPT_INACTIVE = &H10
%DOCHOSTUIFLAG_OPENNEWWIN = &H20
%DOCHOSTUIFLAG_DISABLE_OFFSCREEN = &H40
%DOCHOSTUIFLAG_FLAT_SCROLLBAR = &H80
%DOCHOSTUIFLAG_DIV_BLOCKDEFAULT = &H100
%DOCHOSTUIFLAG_ACTIVATE_CLIENTHIT_ONLY = &H200
%DOCHOSTUIFLAG_OVERRIDEBEHAVIORFACTORY = &H400
%DOCHOSTUIFLAG_CODEPAGELINKEDFONTS = &H800
%DOCHOSTUIFLAG_URL_ENCODING_DISABLE_UTF8 = &H1000
%DOCHOSTUIFLAG_URL_ENCODING_ENABLE_UTF8 = &H2000
%DOCHOSTUIFLAG_ENABLE_FORMS_AUTOCOMPLETE = &H4000
%DOCHOSTUIFLAG_ENABLE_INPLACE_NAVIGATION = &H10000
%DOCHOSTUIFLAG_IME_ENABLE_RECONVERSION = &H20000
%DOCHOSTUIFLAG_THEME = &H40000
%DOCHOSTUIFLAG_NOTHEME = &H80000
%DOCHOSTUIFLAG_NOPICS = &H100000
%DOCHOSTUIFLAG_NO3DOUTERBORDER = &H200000
%DOCHOSTUIFLAG_DISABLE_EDIT_NS_FIXUP = &H400000
%DOCHOSTUIFLAG_LOCAL_MACHINE_ACCESS_CHECK = &H800000
%DOCHOSTUIFLAG_DISABLE_UNTRUSTEDPROTOCOL = &H1000000
' ****************************************************************************************
' DOCHOSTUIINFO Structure
' Used by the IDocHostUIHandler2::GetHostInfo method to allow MSHTML to retrieve information
' about the host's UI requirements.
' ****************************************************************************************
' Members
' cbSize
' ULONG containing the 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.
' pchHostCss
' Pointer to a set of Cascading Style Sheets (CSS) rules sent down by the host.
' These CSS rules affect the page containing them.
' pchHostNS
' Pointer to a semicolon-delimited namespace list. This list allows the host to
' supply a namespace declaration for custom tags on the page.
' ****************************************************************************************
TYPE DOCHOSTUIINFO
cbSize AS DWORD
dwFlags AS DWORD
dwDoubleClick AS DWORD
pchHostCss AS DWORD
pchHostNS AS DWORD
END TYPE
' ****************************************************************************************
' ****************************************************************************************
' IDocHostUIHandler2 virtual table
' ****************************************************************************************
TYPE IDocHostUIHandler2Vtbl
' IUnknown methods
pQueryInterface AS DWORD ' QueryInterface method
pAddRef AS DWORD ' AddRef method
pRelease AS DWORD ' Release method
' IDocHostUIHandler methods
pShowContextMenu AS DWORD ' ShowContextMenu method
pGetHostInfo AS DWORD ' GetHostInfo method
pShowUI AS DWORD ' ShowUI method
pHideUI AS DWORD ' HideUI method
pUpdateUI AS DWORD ' UpdateUI method
pEnableModeless AS DWORD ' EnableModeless method
pOnDocWindowActivate AS DWORD ' OnDocWindowActivate method
pOnFrameWindowActivate AS DWORD ' OnFrameWindowActivate method
pResizeBorder AS DWORD ' ResizeBorder method
pTranslateAccelerator AS DWORD ' TranslateAccelerator method
pGetOptionKeyPath AS DWORD ' GetOptionKeyPath method
pGetDropTarget AS DWORD ' GetDropTarget method
pGetExternal AS DWORD ' GetExternal method
pTranslateUrl AS DWORD ' TranslateUrl method
pFilterDataObject AS DWORD ' FilterDataObject method
' IDocHostUIHandler2 method
pGetOverrideKeyPath AS DWORD ' GetOverrideKeyPath method
' Custom data
pVtblAddr AS DWORD ' Address of the virtual table
cRef AS DWORD ' Reference counter
pthis AS DWORD ' IUnknown of the control that fires the events
END TYPE
' ****************************************************************************************
' ****************************************************************************************
' Builds the IDocHostUIHandler2 events virtual table
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_BuildVtbl (BYVAL pthis AS DWORD) AS DWORD
LOCAL pVtbl AS IDocHostUIHandler2Vtbl PTR
LOCAL pUnk AS IDocHostUIHandler2Vtbl PTR
pVtbl = HeapAlloc(GetProcessHeap(), %HEAP_ZERO_MEMORY, SIZEOF(@pVtbl))
IF pVtbl = 0 THEN EXIT FUNCTION
@pVtbl.pQueryInterface = CODEPTR(IDocHostUIHandler2_QueryInterface)
@pVtbl.pAddRef = CODEPTR(IDocHostUIHandler2_AddRef)
@pVtbl.pRelease = CODEPTR(IDocHostUIHandler2_Release)
@pVtbl.pShowContextMenu = CODEPTR(IDocHostUIHandler2_ShowContextMenu)
@pVtbl.pGetHostInfo = CODEPTR(IDocHostUIHandler2_GetHostInfo)
@pVtbl.pShowUI = CODEPTR(IDocHostUIHandler2_ShowUI)
@pVtbl.pHideUI = CODEPTR(IDocHostUIHandler2_HideUI)
@pVtbl.pUpdateUI = CODEPTR(IDocHostUIHandler2_UpdateUI)
@pVtbl.pEnableModeless = CODEPTR(IDocHostUIHandler2_EnableModeless)
@pVtbl.pOnDocWindowActivate = CODEPTR(IDocHostUIHandler2_OnDocWindowActivate)
@pVtbl.pOnFrameWindowActivate = CODEPTR(IDocHostUIHandler2_OnFrameWindowActivate)
@pVtbl.pResizeBorder = CODEPTR(IDocHostUIHandler2_ResizeBorder)
@pVtbl.pTranslateAccelerator = CODEPTR(IDocHostUIHandler2_TranslateAccelerator)
@pVtbl.pGetOptionKeyPath = CODEPTR(IDocHostUIHandler2_GetOptionKeyPath)
@pVtbl.pGetDropTarget = CODEPTR(IDocHostUIHandler2_GetDropTarget)
@pVtbl.pGetExternal = CODEPTR(IDocHostUIHandler2_GetExternal)
@pVtbl.pTranslateUrl = CODEPTR(IDocHostUIHandler2_TranslateUrl)
@pVtbl.pFilterDataObject = CODEPTR(IDocHostUIHandler2_FilterDataObject)
@pVtbl.pGetOverrideKeyPath = CODEPTR(IDocHostUIHandler2_GetOverrideKeyPath)
@pVtbl.pVtblAddr = pVtbl
@pVtbl.pthis = pthis
pUnk = VARPTR(@pVtbl.pVtblAddr)
FUNCTION = pUnk
END FUNCTION
' ****************************************************************************************
' **********************************************************************************************
' UI4 AddRef()
' **********************************************************************************************
FUNCTION IDocHostUIHandler2_AddRef (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR) AS DWORD
INCR @@pCookie.cRef
FUNCTION = @@pCookie.cRef
END FUNCTION
' **********************************************************************************************
' **********************************************************************************************
' HRESULT QueryInterface([in] *GUID riid, [out] **VOID ppvObj)
' **********************************************************************************************
FUNCTION IDocHostUIHandler2_QueryInterface (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYREF riid AS GUID, BYREF ppvObj AS DWORD) AS LONG
IF riid = $IID_IDocHostUIHandler2 THEN
ppvObj = pCookie
IDocHostUIHandler2_AddRef pCookie
FUNCTION = %S_OK
ELSE
FUNCTION = %E_NOTIMPL
END IF
END FUNCTION
' **********************************************************************************************
' **********************************************************************************************
' UI4 Release()
' **********************************************************************************************
FUNCTION IDocHostUIHandler2_Release (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR) AS DWORD
LOCAL pVtblAddr AS DWORD
IF @@pCookie.cRef = 1 THEN
pVtblAddr = @@pCookie.pVtblAddr
IF ISTRUE HeapFree(GetProcessHeap(), 0, BYVAL pVtblAddr) THEN
FUNCTION = 0
EXIT FUNCTION
ELSE
FUNCTION = @@pCookie.cRef
EXIT FUNCTION
END IF
END IF
DECR @@pCookie.cRef
FUNCTION = @@pCookie.cRef
END FUNCTION
' **********************************************************************************************
' ****************************************************************************************
' ShowContextMenu method
' ****************************************************************************************
' Called by MSHTML to display a shortcut menu.
' Parameters
' dwID
' [in] DWORD that specifies the identifier of the shortcut menu to be displayed.
' This identifier is a bitwise shift of the value 0x1 by the shortcut menu
' values (e.g., CONTEXT_MENU_DEFAULT) defined in Mshtmhst.h.
' 0x2
' value of (0x1 << CONTEXT_MENU_DEFAULT)
' 0x4
' value of (0x1 << CONTEXT_MENU_CONTROL)
' 0x8
' value of (0x1 << CONTEXT_MENU_TABLE)
' 0x10
' value of (0x1 << CONTEXT_MENU_TEXTSELECT)
' 0x30
' value of (0x1 << CONTEXT_MENU_ANCHOR)
' 0x20
' value of (0x1 << CONTEXT_MENU_UNKNOWN)
' ppt
' [in] Pointer to a POINT structure containing the screen coordinates for the menu.
' pcmdtReserved
' [in] Pointer to the IUnknown of an IOleCommandTarget interface used to query
' command status and execute commands on this object.
' pdispReserved
' [in] Pointer to an IDispatch interface of the object at the screen coordinates
' specified in ppt. This allows a host to differentiate particular objects to
' provide more specific context.
' Return Value
' Returns one of the following values:
' %S_OK Host displayed its own user interface (UI). MSHTML will not
' attempt to display its UI.
' %S_FALSE Host did not display any UI. MSHTML will display its UI.
' %DOCHOST_E_UNKNOWN Menu identifier is unknown. MSHTML may attempt an alternative
' identifier from a previous version.
' Remarks
' In Microsoft Internet Explorer 4.0 the pdispReserved parameter supplied no information,
' but in Internet Explorer 5 and later the parameter contains the pointer to an IDispatch
' interface.
' Example
' The following code example shows how the pdispReserved parameter is used.
'
' IHTMLElement *pElem;
' HRESULT hr;
' hr = pdispReserved->QueryInterface(IID_IHTMLElement, (void**)pElem);
' if(SUCCEEDED (hr)) {
' BSTR bstr;
' pElem->get_tagName(bstr);
' USES_CONVERSION;
' ATLTRACE("TagName:%s\n", OLE2T(bstr));
' SysFreeString(bstr);
' pElem->Release();
' }
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *ShowContextMenu )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ DWORD dwID,
' /* [in] */ POINT __RPC_FAR *ppt,
' /* [in] */ IUnknown __RPC_FAR *pcmdtReserved,
' /* [in] */ IDispatch __RPC_FAR *pdispReserved);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_ShowContextMenu (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYVAL dwID AS DWORD, BYVAL ppt AS DWORD PTR, BYVAL pcmdtReserved AS DWORD PTR, BYVAL pdispReserved AS DWORD PTR) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
' =======================================================================================
' This event notifies that the user has clicked the right mouse button to show the
' context menu. We can cancel it returning %S_OK and show our context menu.
' =======================================================================================
' Do not allow to show the context menu
' MSGBOX "Sorry! Context menu disabled"
' FUNCTION = %S_OK
FUNCTION = %S_FALSE
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' GetHostInfo method
' ****************************************************************************************
' Called by MSHTML to retrieve the user interface (UI) capabilities of the application
' that is hosting MSHTML.
' Syntax
' HRESULT GetHostInfo(
' DOCHOSTUIINFO *pInfo
' );
' Parameters
' pInfo
' [in, out] Pointer to a DOCHOSTUIINFO structure that receives the host's UI
' capabilities.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *GetHostInfo )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [out][in] */ DOCHOSTUIINFO __RPC_FAR *pInfo);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_GetHostInfo (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYREF pInfo AS DOCHOSTUIINFO) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
' Here we can modify the host's UI capabilities filling the DOCHOSTUIINFO structure
' with the appropiate values and flags. For example:
IF VARPTR(pInfo) THEN
pInfo.cbSize = SIZEOF(DOCHOSTUIINFO)
pInfo.dwFlags = %DOCHOSTUIFLAG_NO3DBORDER OR %DOCHOSTUIFLAG_THEME
pInfo.dwDoubleClick = %DOCHOSTUIDBLCLK_DEFAULT
pInfo.pchHostCss = %NULL
pInfo.pchHostNS = %NULL
END IF
FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' ShowUI method
' ****************************************************************************************
' Called by MSHTML to enable the host to replace MSHTML menus and toolbars.
' Parameters
' dwID
' [in] DWORD that receives a DOCHOSTUITYPE value indicating the type of user
' interface (UI).
' pActiveObject
' [in] Pointer to an IOleInPlaceActiveObject interface for the active object.
' pCommandTarget
' [in] Pointer to an IOleCommandTarget interface for the object.
' pFrame
' [in] Pointer to an IOleInPlaceFrame interface for the object. Menus and toolbars
' must use this parameter.
' pDoc
' [in] Pointer to an IOleInPlaceUIWindow interface for the object. Toolbars must
' use this parameter.
' Return Value
' Returns one of the following values:
' %S_OK Host displayed its own UI. MSHTML will not display its UI.
' %S_FALSE Host did not display its own UI. MSHTML will display its UI.
' %DOCHOST_E_UNKNOWN Host did not recognize the UI identifier. MSHTML will either try
' an alternative identifier for compatibility with a previous
' version or display its own UI.
' Remarks
' If the host uses any of the interfaces handed to it as part of this function, the host
' should call the interface's AddRef method to save the interface for later use. If the host
' calls the interface's AddRef method, the host must also call the interface's Release
' method when the interface is no longer required.
' A host can disable modeless UI on MSHTML by calling IOleCommandTarget::Exec with
' %IDM_DISABLEMODELESS and %IDM_ENABLEMODELESS.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *ShowUI )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ DWORD dwID,
' /* [in] */ IOleInPlaceActiveObject __RPC_FAR *pActiveObject,
' /* [in] */ IOleCommandTarget __RPC_FAR *pCommandTarget,
' /* [in] */ IOleInPlaceFrame __RPC_FAR *pFrame,
' /* [in] */ IOleInPlaceUIWindow __RPC_FAR *pDoc);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_ShowUI (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYVAL dwID AS DWORD, BYVAL pActiveObject AS DWORD PTR, BYVAL pCommandTarget AS DWORD PTR, BYVAL pFrame AS DWORD PTR, BYVAL pDoc AS DWORD PTR) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
FUNCTION = %S_FALSE
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' Called when MSHTML removes its menus and toolbars.
' ****************************************************************************************
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' Remarks
' If a host displayed menus and toolbars during the call to IDocHostUIHandler2::ShowUI,
' the host should remove them when this method is called. This method is called
' regardless of the return value from the IDocHostUIHandler2::ShowUI method.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *HideUI )(
' IDocHostUIHandler2 __RPC_FAR * This);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_HideUI (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' UpdateUI method
' ****************************************************************************************
' Called by MSHTML to notify the host that the command state has changed.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' Remarks
' The host should update the state of toolbar buttons in an implementation of this
' method. This method is called regardless of the return value from the
' IDocHostUIHandler2::ShowUI method.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *UpdateUI )(
' IDocHostUIHandler2 __RPC_FAR * This);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_UpdateUI (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' EnableModeless method
' ****************************************************************************************
' Called by the MSHTML implementation of IOleInPlaceActiveObject::EnableModeless. Also
' called when MSHTML displays a modal UI.
' Parameters
' fEnable
' [in] BOOL that indicates if the host's modeless dialog boxes are enabled or disabled.
' %TRUE
' Modeless dialog boxes are enabled.
' %FALSE
' Modeless dialog boxes are disabled.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *EnableModeless )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ BOOL fEnable);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_EnableModeless (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYVAL fEnable AS INTEGER) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' OnDocWindowActivate method
' ****************************************************************************************
' Called by the MSHTML implementation of IOleInPlaceActiveObject::OnDocWindowActivate.
' Parameters
' fActivate
' [in] BOOL value that indicates the state of the document window.
' %TRUE
' The window is being activated.
' %FALSE
' The window is being deactivated.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *OnDocWindowActivate )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ BOOL fActivate);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_OnDocWindowActivate (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYVAL fActivate AS INTEGER) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' OnFrameWindowActivate method
' ****************************************************************************************
' Called by the MSHTML implementation of IOleInPlaceActiveObject::OnFrameWindowActivate.
' Parameters
' fActivate
' [in] BOOL value that indicates the state of the container's top-level frame window.
' %TRUE
' The frame window is being activated.
' %FALSE
' The frame window is being deactivated.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *OnFrameWindowActivate )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ BOOL fActivate);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_OnFrameWindowActivate (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYVAL fActivate AS INTEGER) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' ResizeBorder method
' ****************************************************************************************
' Called by the MSHTML implementation of IOleInPlaceActiveObject::ResizeBorder.
' Parameters
' prcBorder
' [in] Constant pointer to a RECT for the new outer rectangle of the border.
' pUIWindow
' [in] Pointer to an IOleInPlaceUIWindow interface for the frame or document window
' whose border is to be changed.
' fFrameWindow
' [in] BOOL that is %TRUE if the frame window is calling IDocHostUIHandler2::ResizeBorder,
' or %FALSE otherwise.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *ResizeBorder )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ LPCRECT prcBorder,
' /* [in] */ IOleInPlaceUIWindow __RPC_FAR *pUIWindow,
' /* [in] */ BOOL fRameWindow);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_ResizeBorder (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYREF prcBorder AS RECT, BYVAL pUIWindow AS DWORD PTR, BYVAL fRameWindow AS INTEGER) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
FUNCTION = %S_OK
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' TranslateAccelerator method
' ****************************************************************************************
' Called by MSHTML when IOleInPlaceActiveObject::TranslateAccelerator or
' IOleControlSite::TranslateAccelerator is called.
' Parameters
' lpMsg
' [in] Pointer to a MSG structure that specifies the message to be translated.
' pguidCmdGroup
' [in] Pointer to a GUID for the command group identifier.
' nCmdID
' [in] DWORD that specifies a command identifier.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' Remarks
' When you use accelerator keys such as TAB, you may need to override the default host
' behavior. The example shows how to do this.
' Example
' This example shows how to override the default host behavior that occurs when a user
' tabs out of the first or last element.
'
' CYourControlSite::TranslateAccelerator(MSG *pMsg, DWORD dwFlags)
' {
' if (pMsg && pMsg->message == WM_KEYDOWN && pMsg->wParam == VK_TAB) {
' return S_FALSE;
' }
' }
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *TranslateAccelerator )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ LPMSG lpMsg,
' /* [in] */ const GUID __RPC_FAR *pguidCmdGroup,
' /* [in] */ DWORD nCmdID);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_TranslateAccelerator (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, lpMsg AS tagMSG, BYREF pguidCmdGroup AS GUID, BYVAL nCmdID AS DWORD) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
' Sample code to retrieve the text that the user has copied or cut with Ctrl+C/Ctrl+X
' LOCAL ppDoc AS DWORD ' // IHTMLDocument2 interface
' LOCAL ppSel AS DWORD ' // IHTMLSelectionObject interface
' LOCAL ppRange AS DWORD ' // IHTMLTxtRange interface
' LOCAL selText AS STRING ' // Selected text
' LOCAL iKeyState AS INTEGER ' // Key state
' IF lpMsg.message = %WM_KEYDOWN THEN
' iKeyState = GetAsyncKeyState(%VK_CONTROL)
' IF (lpMsg.wParam = %VK_C OR lpMsg.wParam = %VK_X) AND ISTRUE(BIT(iKeyState, 15)) THEN
' ' Retrieve a reference to the IHTMLDocument interface
' ppDoc = IWebBrowser2_GetDocument(pthis)
' ' Retrieve a reference to the IHTMLSelectionObject interface
' ppSel = IHTMLDocument2_GetSelection(ppDoc)
' ' Retrieve a reference to the IHTMLtxtRange interface
' ppRange = IHTMLSelectionObject_CreateRange(ppSel)
' ' Retrieve the selected text
' selText = IHTMLTxtRange_GetText(ppRange)
' ' Release the no longer eneded interfaces
' WbRelease ppRange
' WbRelease ppSel
' WbRelease ppDoc
' ' Show the selected text
' MSGBOX selText
' END IF
' END IF
FUNCTION = %S_FALSE
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' GetOptionKeyPath method
' ****************************************************************************************
' Called by the WebBrowser Control to retrieve a registry subkey path that overrides the
' default Microsoft Internet Explorer registry settings.
' Parameters
' pchKey
' [out] Pointer to an LPOLESTR that receives the registry subkey string where the
' host stores its registry settings.
' dw
' [in] Reserved. Must be set to %NULL.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' Remarks
' A WebBrowser Control instance calls GetOptionKeyPath on the host at initialization so
' that the host can specify a registry location containing settings that override the
' default Internet Explorer registry settings. If the host returns %S_FALSE for this
' method, or if the registry key path returned to the WebBrowser Control in pchKey is
' %NULL or empty, the WebBrowser Control reverts to the default Internet Explorer
' registry settings.
' GetOptionKeyPath and IDocHostUIHandler22::GetOverrideKeyPath provide two alternate
' mechanisms for a WebBrowser Control host to make changes in the registry settings for
' the WebBrowser Control. With GetOptionKeyPath, a WebBrowser Control instance defaults
' to its original settings before registry changes are applied from the registry path
' specified by the method. With GetOptionKeyPath, a WebBrowser Control instance
' preserves registry settings for the current user. Any registry changes located at the
' registry path specified by this method override those located in
' HKEY_CURRENT_USER/Software/Microsoft/Internet Explorer.
' For example, assume that the user has changed the Internet Explorer default text size
' to the largest font. Implementing IDocHostUIHandler22::GetOverrideKeyPath preserves
' that change--unless the size has been specifically overridden in the registry settings
' located at the registry path specified by the implementation of GetOptionKeyPath.
' Implementing GetOptionKeyPath would not preserve the user's text size change. Instead,
' the WebBrowser Control defaults back to its original medium-size font before applying
' registry settings from the registry path specified by the GetOptionKeyPath
' implementation.
' An implementation of GetOptionKeyPath must allocate memory for pchKey using
' CoTaskMemAlloc. (The WebBrowser Control is responsible for freeing this memory using
' CoTaskMemFree). Even if this method is unimplemented, the parameter should be set to
' %NULL.
' The key specified by this method must be a subkey of the HKEY_CURRENT_USER key.
' Example
' This example points the WebBrowser Control to a registry key located at
' HKEY_CURRENT_USER/Software/YourCompany/YourApp for Internet Explorer registry
' overrides. Of course, you need to set registry keys at this location in the registry
' for the WebBrowser Control to use them.
'
' HRESULT CBrowserHost::GetOptionKeyPath(LPOLESTR *pchKey, DWORD dwReserved)
' {
' HRESULT hr;
' WCHAR* szKey = L"Software\\MyCompany\\MyApp";
' // cbLength is the length of szKey in bytes.
' size_t cbLength;
' hr = StringCbLengthW(szKey, 1280, &cbLength);
' // TODO: Add error handling code here.
' if (pchKey)
' {
' *pchKey = (LPOLESTR)CoTaskMemAlloc(cbLength + sizeof(WCHAR));
' if (*pchKey)
' hr = StringCbCopyW(*pchKey, cbLength + sizeof(WCHAR), szKey);
' }
' else
' hr = E_INVALIDARG;
' return hr;
' }
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *GetOptionKeyPath )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [out] */ LPOLESTR __RPC_FAR *pchKey,
' /* [in] */ DWORD dw);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_GetOptionKeyPath (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYREF pchKey AS DWORD, BYVAL DW AS DWORD) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
pchKey = 0
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' GetDropTarget method
' ****************************************************************************************
' Called by MSHTML when it is used as a drop target. This method enables the host to
' supply an alternative IDropTarget interface.
' Parameters
' pDropTarget
' [in] Pointer to an IDropTarget interface for the current drop target object
' supplied by MSHTML.
' ppDropTarget
' [out] Address of a pointer variable that receives an IDropTarget interface pointer
' for the alternative drop target object supplied by the host.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' Remarks
' If the host does not supply an alternative drop target, this method should return a
' failure code, such as %E_NOTIMPL or %E_FAIL.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *GetDropTarget )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ IDropTarget __RPC_FAR *pDropTarget,
' /* [out] */ IDropTarget __RPC_FAR *__RPC_FAR *ppDropTarget);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_GetDropTarget (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYVAL pDropTarget AS DWORD PTR, BYREF ppDropTarget AS DWORD) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
pDropTarget = 0
FUNCTION = %E_NOTIMPL
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' GetExternal method
' ****************************************************************************************
' Called by MSHTML to obtain the host's IDispatch interface.
' Parameters
' ppDispatch
' [out] Address of a pointer to a variable that receives an IDispatch interface
' pointer for the host application.
' Return Value
' Returns %S_OK if successful, or an error value otherwise.
' Remarks
' If the host exposes an automation interface, it can provide a reference to MSHTML
' through ppDispatch.
' If the method implementation does not supply an IDispatch, ppDispatch should be set
' to %NULL, even if the method fails or returns %S_FALSE.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *GetExternal )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [out] */ IDispatch __RPC_FAR *__RPC_FAR *ppDispatch);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_GetExternal (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYREF ppDispatch AS DWORD) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
ppDispatch = 0
FUNCTION = %S_FALSE
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' TranslateUrl method
' ****************************************************************************************
' Called by MSHTML to give the host an opportunity to modify the URL to be loaded.
' Parameters
' dwTranslate
' [in] Reserved. Must be set to %NULL.
' pchURLIn
' [in] Pointer to an OLECHAR that specifies the current URL for navigation.
' ppchURLOut
' [out] Address of a pointer variable that receives an OLECHAR pointer containing
' the new URL.
' Return Value
' Returns %S_OK if the URL was translated, or %S_FALSE if the URL was not translated.
' Remarks
' The host allocates the buffer ppchURLOut using CoTaskMemAlloc.
' If the implementation of this method does not supply a URL, ppchURLOut should be set
' to %NULL, even if the method fails or returns %S_FALSE.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *TranslateUrl )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ DWORD dwTranslate,
' /* [in] */ OLECHAR __RPC_FAR *pchURLIn,
' /* [out] */ OLECHAR __RPC_FAR *__RPC_FAR *ppchURLOut);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_TranslateUrl (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYVAL dwTranslate AS DWORD, BYVAL pchURLIn AS DWORD, BYREF ppchURLOut AS DWORD) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
ppchURLOut = 0
FUNCTION = %S_FALSE
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' FilterDataObject method
' ****************************************************************************************
' Called by MSHTML to allow the host to replace the MSHTML data object.
' Parameters
' pDO
' [in] Pointer to an IDataObject interface supplied by MSHTML.
' ppDORet
' [out] Address of a pointer variable that receives an IDataObject interface pointer
' supplied by the host.
' Return Value
' Returns %S_OK if the data object is replaced, or %S_FALSE if it's not replaced.
' Remarks
' This method enables the host to block certain clipboard formats or support additional
' clipboard formats.
' If the implementation of this method does not supply its own IDataObject, ppDORet
' should be set to %NULL, even if the method fails or returns %S_FALSE.
' ****************************************************************************************
' HRESULT ( STDMETHODCALLTYPE __RPC_FAR *FilterDataObject )(
' IDocHostUIHandler2 __RPC_FAR * This,
' /* [in] */ IDataObject __RPC_FAR *pDO,
' /* [out] */ IDataObject __RPC_FAR *__RPC_FAR *ppDORet);
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_FilterDataObject (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYVAL pDO AS DWORD PTR, BYREF ppDORet AS DWORD) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
ppDORet = 0
FUNCTION = %S_FALSE
END FUNCTION
' ****************************************************************************************
' ****************************************************************************************
' Called by the WebBrowser Control to retrieve a registry subkey path that modifies
' Microsoft Internet Explorer user preferences.
' Parameters
' pchKey
' [out] Pointer to a variable of type LPOLESTR that receives the registry subkey string where the host stores its registry settings.
' dw
' [in] Reserved. Must be set to NULL.
' Return Value
' Returns S_OK if successful, or an error value otherwise.
' Remarks
' A WebBrowser Control instance calls IDocHostUIHandler2::GetOverrideKeyPath on the host
' at initialization so that the host can specify a registry location containing settings
' that modify the Internet Explorer registry settings for the current user. If the host
' returns S_FALSE for this method, or if the registry key path returned to the WebBrowser
' Control in pchKey is NULL or empty, the WebBrowser Control reverts to the registry
' settings for the current user.
' IDocHostUIHandler2::GetOverrideKeyPath provides an alternate mechanism to
' IDocHostUIHandler::GetOptionKeyPath for a WebBrowser Control host to make changes in
' the registry settings for the WebBrowser Control. With IDocHostUIHandler2::GetOverrideKeyPath,
' your WebBrowser Control instance preserves registry settings for the current user. Any
' registry changes located at the registry path specified by this method override those
' located in HKEY_CURRENT_USER/Software/Microsoft/Internet Explorer. Compare this to
' IDocHostUIHandler::GetOptionKeyPath, which causes a WebBrowser Control instance to
' default to its original settings before registry changes are applied from the registry
' path specified by the method.
' For example, assume the user has changed the Internet Explorer default text size to
' the largest font. Implementing IDocHostUIHandler2::GetOverrideKeyPath will preserve
' that change--unless the size has been specifically overridden in the registry settings
' located at the registry path specified by the implementation of
' IDocHostUIHandler2::GetOverrideKeyPath. Implementing IDocHostUIHandler::GetOptionKeyPath
' would not preserve the user's text size change. Instead, the WebBrowser Control defaults
' back to its original medium-size font before applying registry settings from the
' registry path specified by the IDocHostUIHandler::GetOptionKeyPath implementation.
' An implementation of IDocHostUIHandler2::GetOverrideKeyPath must allocate memory for
' pchKey using CoTaskMemAlloc. (The WebBrowser Control will be responsible for freeing
' this memory using CoTaskMemFree). Even if this method is unimplemented, this parameter
' should be set to NULL.
' The key specified by this method must be a subkey of the HKEY_CURRENT_USER key.
' Example
' This example points the WebBrowser Control to a registry key located at
' HKEY_CURRENT_USER/Software/YourCompany/YourApp for user preference overrides. Of
' course, you need to set registry keys at this location in the registry for the
' WebBrowser Control to use them.
'
' HRESULT CBrowserHost::GetOverrideKeyPath(LPOLESTR *pchKey, DWORD dwReserved)
' {
' HRESULT hr;
' WCHAR* szKey = L"Software\\MyCompany\\MyApp";
' // cbLength is the length of szKey in bytes.
' size_t cbLength;
' hr = StringCbLengthW(szKey, 1280, &cbLength);
' // TODO: Add error handling code here.
' if (pchKey)
' {
' *pchKey = (LPOLESTR)CoTaskMemAlloc(cbLength + sizeof(WCHAR));
' if (*pchKey)
' hr = StringCbCopyW(*pchKey, cbLength + sizeof(WCHAR), szKey);
' }
' else
' hr = E_INVALIDARG;
' return hr;
' }
' ****************************************************************************************
' HRESULT GetOverrideKeyPath(
' LPOLESTR *pchKey,
' DWORD dw
' );
' ****************************************************************************************
FUNCTION IDocHostUIHandler2_GetOverrideKeyPath (BYVAL pCookie AS IDocHostUIHandler2Vtbl PTR, BYREF pchKey AS DWORD, BYVAL dw AS DWORD) AS LONG
' =======================================================================================
' Retrieve the IDispatch reference of the control that has fired the event.
' =======================================================================================
LOCAL pthis AS DWORD : pthis = @@pCookie.pthis
' =======================================================================================
FUNCTION = %S_FALSE
END FUNCTION
' ****************************************************************************************
|
Page last updated on Monday, 03 April 2006 19:44:53 +0200
Article (old buth still useful):