showModelessDialog method

  • Article

[This documentation is preliminary and is subject to change.]

Creates a modeless dialog box that displays the specified HTML document.

This method is not supported for Metro style apps using JavaScript.

Syntax

IHTMLWindow2 retVal = object.showModelessDialog(url, varArgIn, options);

Standards information

There are no standards that apply here.

Parameters

url [in]

Type: BSTR

BSTR that specifies the URL of the document to load and display.

varArgIn [in, optional]

Type: VARIANT

Pointer to a VARIANT that specifies the arguments to use when displaying the document. Use this parameter to pass a value of any type, including an array of values. The dialog box can extract the values passed by the caller from the IHTMLDialog::dialogArguments property of the window object.

options [in, optional]

Type: VARIANT

Pointer to a VARIANT of type BSTR that specifies the window ornaments for the dialog box, using one or more of the following semicolon-delimited values:

dialogHeight:sHeight

Sets the height of the dialog window (see Remarks for default unit of measure).

dialogLeft:sXPos

Sets the left position of the dialog window relative to the upper-left corner of the desktop.

dialogTop:sYPos

Sets the top position of the dialog window relative to the upper-left corner of the desktop.

dialogWidth:sWidth

Sets the width of the dialog window (see Remarks for default unit of measure).

center:{ yes | no | 1 | 0 | on | off }

Specifies whether to center the dialog window within the desktop. The default is yes.

dialogHide:{ yes | no | 1 | 0 | on | off }

Specifies whether the dialog window is hidden when printing or using print preview. This feature is only available when a dialog box is opened from a trusted application. The default is no.

edge:{ sunken | raised }

Specifies the edge style of the dialog window. The default is raised.

help:{ yes | no | 1 | 0 | on | off }

Internet Explorer 7 and later. This parameter value is no longer supported. In earlier versions, this value indicates whether or not the dialog window displays the context-sensitive Help icon. The default value is yes.

resizable:{ yes | no | 1 | 0 | on | off }

Specifies whether the dialog window has fixed dimensions. The default is no.

scroll:{ yes | no | 1 | 0 | on | off }

Specifies whether the dialog window displays scrollbars. The default is yes.

status:{ yes | no | 1 | 0 | on | off }

Specifies whether the dialog window displays a status bar. The default is yes for untrusted dialog windows and no for trusted dialog windows.

unadorned:{ yes | no | 1 | 0 | on | off }

Specifies whether the dialog window displays the border window chrome. This feature is only available when a dialog box is opened from a trusted application. The default is no.

Remarks

The modeless dialog box displays even when the user switches input focus to the window.

The IHTMLWindow3::showModelessDialog method is useful for menus and Help systems. When you invoke this method, a dialog box appears, layered in front of the browser window or HTML Application (HTA).

Because a modeless dialog box can include a URL to a resource in a different domain, do not pass information through the varArgIn parameter that the user might consider private. The varArgIn parameter can be referenced within the modeless dialog box using the IHTMLDialog::dialogArguments property of the window object. If the varArgIn parameter is defined as a string, the maximum string length that can be passed to the modeless dialog box is 4096 characters; longer strings are truncated.

By convention, modeless dialog boxes can differ from an application window in that they do not have scroll bar, status bar, or resize capabilities. To create this type of dialog box, implement the following steps:

  • Turn off the scroll bar. Use the IHTMLBodyElement::scroll attribute by including the scroll="no" value in the body tag for the dialog window.
  • Turn off the status bar. Set the value of status to no in the options parameter of the IHTMLWindow3::showModelessDialog call. A second option is to call the dialog window from a trusted application, such as Microsoft Visual Basic or an HTA, or from a trusted window, such as a trusted dialog box. These are considered trusted because they use Windows Internet Explorer interfaces instead of the browser. The status bar of any dialog box generated from a trusted source is set to off by default.
  • Do not allow resizing. Resizing is set to off by default.

To create a return value for IHTMLWindow3::showModelessDialog, set the varArgIn parameter to a callback function or an object in the IHTMLWindow3::showModelessDialog call. In the modeless dialog box, you can reference this function or object through the IHTMLDialog::dialogArguments property of the window object. The same arguments are valid for the IHTMLWindow3::showModelessDialog and IHTMLWindow2::showModalDialog methods.

You can set the default font settings the same way you set Cascading Style Sheets (CSS) attributes (for example, "font:3; font-size:4"). To define multiple font values, use multiple font attributes.

To override center, even though the default for center is yes, you can specify either dialogLeft and/or dialogTop.

This method must use a user-initiated action, such as clicking a link or tabbing to a link and pressing ENTER, to open a pop-up window.

When Windows Internet Explorer opens a window from a modal or modeless HTML dialog box by using the IHTMLWindow2::showModalDialog method or by using the IHTMLWindow3::showModelessDialog method, Internet Explorer uses Component Object Model (COM) to create a new instance of the window. Typically, the window is opened by using the first instance of an existing Internet Explorer process. When Internet Explorer opens the window in a new process, all the memory cookies are no longer available, including the session ID. This process is different from the process that Internet Explorer uses to open a new window by using the IHTMLWindow2::open method.

For Internet Explorer 7, dialogHeight and dialogWidth return the height and width of the content area and no longer includes the height and width of the frame.

Internet Explorer 7. Although a user can manually adjust the height of a dialog box to a smaller value —provided the dialog box is resizable— the minimum dialogHeight you can specify is 100 pixels, and the minimum dialogWidth you can define is 250 pixels. In versions earlier than Internet Explorer 7 the minimum value of the dialogWidth that can be specified is 100 pixels.

The Pop-up Blocker feature in Microsoft Internet Explorer 6 blocks windows that are opened without being initiated by the user.

The default unit of measure for dialogHeight and dialogWidth in Microsoft Internet Explorer 5 and later is the pixel. The value can be an integer or floating-point number, followed by an absolute units designator (cm, mm, in, pt, or pc) or a relative units designator (em, ex, or px). For consistent results, specify the dialogHeight and dialogWidth in pixels when designing modeless dialog boxes.

See also

Reference

IHTMLWindow2::showModalDialog

Conceptual

About the Pop-up Blocker

 

 

Build date: 6/12/2012