ShowHTMLDialogEx function
Creates a trusted dialog box that displays HTML.
Syntax
HRESULT ShowHTMLDialogEx(
_In_ HWND hwndParent,
_In_ IMoniker *pMk,
DWORD dwDialogFlags,
_In_ VARIANT *pvarArgIn,
_In_ LPWSTR pchOptions,
_Out_ VARIANT *pvarArgOut
);
Parameters
hwndParent [in]
A handle to the parent of the dialog box.
pMk [in]
The address of an IMoniker interface from which the HTML source content for the dialog box is loaded.
dwDialogFlags
A DWORD consisting of a bit-wise OR (|) combination of the following flags. Note that some of these flags are logically mutually exclusive.
HTMLDLG_NOUI (0x0010)
Open the dialog box without a user interface. The dialog box is instantiated and can run scripts, and so on, but is not visible to the user.
HTMLDLG_MODAL (0x0020)
Open a modal dialog box.
HTMLDLG_MODELESS (0x0040)
Open a modeless dialog box.
HTMLDLG_PRINT_TEMPLATE (0x0080)
Open the dialog box as a print template, either for printing or print preview. As a print template, the dialog box can use the TemplatePrinter behavior and access content documents on LayoutRect elements.
HTMLDLG_VERIFY (0x0100)
Force the dialog box to appear on a viewable portion of the desktop. Trusted dialog boxes might or might not open on a visible region of the desktop. Unlike untrusted dialog boxes, which are forced to appear on a viewable portion of the desktop, a trusted dialog box can be positioned anywhere, regardless of the size of the desktop. For example, on an 800x600 monitor, you cannot raise an untrusted dialog box at [900,700]. Instead, the untrusted dialog box will be repositioned so that it appears somewhere on the viewable desktop. If the dialog box is trusted, however, it opens successfully but is invisible to the user, because it is located off the lower-left edge of the screen. This flag enables a trusted dialog box to be "view verified" like an untrusted dialog box.
HTMLDLG_ALLOW_UNKNOWN_THREAD (0x0200)
Internet Explorer 7 and later. Permit worker threads to show a dialog. Internet Explorer 7 prevents background tabs from displaying HTML dialogs on top of the active tab. Instead, it suppresses the dialog and blinks the corresponding tab to alert the user. When the user selects the inactive tab, the dialog is displayed. If a thread that is associated with neither the foreground nor an inactive tab (such as a worker thread) attempts to show an HTML dialog, it is silently blocked by default. This flag permits the dialog to be displayed.
Warning Allowing a background tab to show dialogs in the foreground makes an extension vulnerable to UI spoofing exploits. Use this flag with caution.
pvarArgIn [in]
The address of a VARIANT structure that contains the input data for the dialog box. The data passed in this VARIANT is placed in the window object's IHTMLDialog::dialogArguments property. This parameter can be NULL.
pchOptions [in]
The window ornaments for the dialog box. This parameter can be NULL or the address of a string that contains a combination of values separated by semicolons (;). For detailed information, see the description of the features parameter of the IHTMLWindow2::showModalDialog method of the window object.
pvarArgOut [out]
The address of a VARIANT structure that contains the output data for the dialog box. If the dialog box is modal, this VARIANT receives the data that was placed in the window object's IHTMLDialog::returnValue property. If the dialog box is modeless, this parameter receives a VARIANT of type VT_UNKNOWN containing a pointer to the IHTMLWindow2 interface for the dialog box. This parameter can be NULL.
Return value
If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Remarks
At least one of the flags HTMLDLG_MODELESS and HTMLDLG_MODAL must be included in dwDialogFlags. If both are declared, HTMLDLG_MODELESS takes precedence over HTMLDLG_MODAL.
Modal dialog boxes created by this method are synchronous; that is, the call to ShowHTMLDialogEx does not return until the dialog box closes. Modeless dialog boxes created by this method are asynchronous; that is, the dialog box is created in a separate process, and the call to ShowHTMLDialogEx returns before the dialog box closes.
To use ShowHTMLDialogEx, which is implemented in Mshtml.dll, you must dynamically load the DLL and call this function by using the LoadLibrary function and the GetProcAddress function. The proper function type for ShowHTMLDialogEx is defined in Mshtmhst.h in the SHOWHTMLDIALOGEXFN type. The procedure for calling this function is analogous to the procedure for calling ShowHTMLDialog. A full sample that demonstrates the use of ShowHTMLDialog is available on the ShowHTMLDialog Sample Source Page.
Security Warning: Using LoadLibrary incorrectly can compromise the security of your application by loading the wrong DLL. Refer to the LoadLibrary documentation for information on how to correctly load DLLs with different versions of Windows.
Examples
The following example shows the basic steps to load Mshtml.dll, obtain the address of ShowHTMLDialogEx using GetProcAddress, create a URL moniker, and call ShowHTMLDialogEx.
HINSTANCE hinstMSHTML = LoadLibrary(TEXT("MSHTML.DLL"));
if (hinstMSHTML == NULL)
{
// Error loading module -- fail as securely as possible
return;
}
SHOWHTMLDIALOGEXFN* pfnShowHTMLDialogEx;
pfnShowHTMLDialogEx = (SHOWHTMLDIALOGEXFN*)GetProcAddress(hinstMSHTML,
TEXT("ShowHTMLDialogEx"));
if (pfnShowHTMLDialogEx)
{
IMoniker *pURLMoniker;
BSTR bstrURL = SysAllocString(L"http://www.example.com/dialogsource.htm");
CreateURLMoniker(NULL, bstrURL, &pURLMoniker);
if (pURLMoniker)
{
DWORD dwFlags = HTMLDLG_MODELESS | HTMLDLG_VERIFY;
(*pfnShowHTMLDialogEx)(NULL, pURLMoniker, dwFlags, NULL, NULL, NULL);
pURLMoniker->Release();
}
SysFreeString(bstrURL);
}
FreeLibrary(hinstMSHTML);
Requirements
Minimum supported client |
Windows XP |
Minimum supported server |
Windows 2000 Server |
Header |
Mshtmhst.h |
DLL |
Mshtml.dll; Mshtml.dll |