ShowHTMLDialogEx Function

Creates a trusted dialog box that displays HTML.

Syntax

Copy

HRESULT ShowHTMLDialogEx(
    HWND hwndParent,
    IMoniker *pMk,
    DWORD dwDialogFlags,
    VARIANT *pvarArgIn,
    LPWSTR pchOptions,
    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

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

Open a modal dialog box.

HTMLDLG_MODELESS

Open a modeless dialog box.

HTMLDLG_PRINT_TEMPLATE

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

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

Windows 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

Returns S_OK if successful, or an error value otherwise.

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

Example

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.

Copy

   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);

Function Information

Stock Implementation	mshtml.dll
Custom Implementation	No
Header	mshtmhst.h
Import library	mshtml.dll
Minimum availability	Internet Explorer 4.0
Minimum operating systems	Windows NT 4.0, Windows 95, Windows CE 4.0

See Also

Creating an HTML Resource