HTMLDialog

The HTMLDialog class is MSHTML’s most public representation of an HTML dialog box or property sheet.

IDL Declaration

The following is reproduced from MSHTML.IDL in the Windows SDK.

[
    noncreatable,
    uuid (3050F28A-98B5-11CF-BB82-00AA00BDCE0B)
]
coclass HTMLDialog
{
    [default] interface IHTMLDialog;
};

Interfaces

The internal class in which MSHTML implements HTMLDialog is named CHTMLDlg. It has the following interfaces:

• IDispatchEx and its base IDispatch
• IHTMLDialog
• IHTMLDialog2
• IObjectIdentity
• IPropertyPage2 and its base IPropertyPage
• IProvideMultipleClassInfo and its bases IProvideClassInfo2 and IProvideClassInfo
• IUnknown

The class’s implementation of QueryInterface also accepts CLSID_HTMLDialog as a fake IID to provide MSHTML with an easy (if dubious) means of determining whether a given interface pointer that is supposed to belong to an HTMLDialog instance actually does.

Access

An HTML dialog box is a window created by MSHTML to look and behave very much like a Windows dialog box, but taking its contents from an HTML page. As with Windows dialog boxes, an MSHTML dialog box may be modal or modeless. The call to create a modal dialog box does not return until the dialog box is closed. A modeless dialog box is essentially a modal dialog box that MSHTML runs in a second thread, so that the calling thread is free to do other work while the other thread waits for the dialog box to close.

These are many ways to get MSHTML to create a modal HTML dialog box. The following allow more or less arbitrary content:

• call the exported function ShowHTMLDialog or its equivalent ShowModalDialog;
• call the exported function ShowHTMLDialogEx with suitable flags;
• call the showModalDialog method of an IHTMLWindow2 interface;
• call the ShowHTMLDialog method of an IHostDialogHelper interface;
• execute the IDM_RUNURLSCRIPT command in the CGID_MSHTML command group.

MSHTML can also be directed to show a modal dialog box but with MSHTML setting the content. The most notable cases are when MSHTML handles the following commands in the CGID_MSHTML command group:

• IDM_REPLACE;
• IDM_VIEWSOURCE or IDM_VIEWPRETRANSFORMSOURCE;
• any from IDM_MENUEXT_FIRST__ to IDM_MENUEXT_LAST__ inclusive

There seem to be fewer ways to get MSHTML to create a modeless HTML dialog box:

• call the exported function ShowModelessHTMLDialog;
• call the exported function ShowHTMLDialogEx with suitable flags;
• call the showModelessDialog method of an IHTMLWindow3 interface;

There seem to be the following ways to get MSHTML to create a property sheet:

• call the exported function CreateHTMLPropertyPage;
• create an instance of a property sheet class.

The property sheet classes are supported by MSHTML through its exported function DllGetClassObject but are determined by whatever module implements the DocHostUIHandler class. In Windows Vista, this is IEFRAME.DLL and the classes are

• CAnchorBrowsePropertyPage, taking its HTML from “anchrppg.ppg” in the IEFRAME resources;
• CDocBrowsePropertyPage, taking its HTML from “docppg.ppg” in the IEFRAME resources;
• CImageBrowsePropertyPage, taking its HTML from “imageppg.ppg” in the IEFRAME resources.

Scripting

The table below lists the interface members that the CHTMLDlg class exposes as properties (methods, etc) through its string table. Note the many attributes that are not directly scriptable as properties. They become meaningful in a string that can be passed as an argument to various of the functions and interfaces that create an HTML dialog box, specifically to provide options. This string is parsed as CSS text.

The HTML and DHTML Reference blends the dialog-box properties into its documentation of the window object. This matches one way that script running in the dialog box can access the properties, but the access actually goes through the external object. The attributes, being meaningful only for script that creates a dialog box, are documented with the window object’s showModalDialog and showModelessDialog methods. Any that are omitted there are highlighted in the list below.

Note that although the CHTMLDlg class implements the IHTMLDialog2 interface, which supports two read/write properties, resizable and status, neither is supported in the class’s string table and therefore neither is scriptable.