showModelessDialog Method

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

Syntax

vReturnValue = window.showModelessDialog(sURL [, vArguments] [, sFeatures])

Parameters

sURL Required. String that specifies the URL of the document to load and display.
vArguments Optional. 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 dialogArguments property of the window object.
sFeatures Optional. Variant of type String 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 } Specifies whether the dialog window displays the context-sensitive Help icon. The default 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.

Return Value

Variant that returns a reference to the new window object. Use this reference to script properties and methods on the new window.

Remarks

The modeless dialog box displays even when the user switches input focus to the window.
The 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 vArguments parameter that the user might consider private. The vArguments parameter can be referenced within the modeless dialog box using the dialogArguments property of the window object. If the vArguments 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 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 sFeatures parameter of the 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 Microsoft 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 showModelessDialog, set the vArguments parameter to a callback function or an object in the showModelessDialog call. In the modeless dialog box, you can reference this function or object through the dialogArguments property of the window object. The same arguments are valid for the showModelessDialog and 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.
The default unit of measure for dialogHeight and dialogWidth in Internet Explorer 4.0 is the em; in Internet Explorer 5 it is the pixel. The value can be an integer or floating-point number, followed by an absolute units designator (cm, mm, in, pt, pc, or px) or a relative units designator (em or ex). For consistent results, specify the dialogHeight and dialogWidth in pixels when designing modal dialog boxes.
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.

Examples

This example uses the showModelessDialog method to create a return value. It also shows how to handle user actions in the modeless dialog box. Two sample documents are displayed below. The first one (showModelessDialogEX.htm) uses the showModelessDialog method to acccess the Dynamic HTML (DHTML) code found in the second sample document called myDialog.htm. This creates a modeless dialog box that prompts the user for a name, which can then be displayed in the parent window.

<HEAD>
<HTML>
<HEAD>
<TITLE>showModelessDialogEX.htm</TITLE>
<SCRIPT>
var sUserName="";
/*------------------------------------------------------------
Supplying the window object as a parameter allows for declaring the global
variable, sUserName, and using it to return information from the modeless
dialog box.
------------------------------------------------------------- */
function fnCallDialog()
{
showModelessDialog("myDialog.htm",window,"status:false;dialogWidth:300px;dialogHeight:300px");
}
/*-------------------------------------------------------------
The fnUpdate function takes the value passed into sUserName in myDialog.htm
to update the span text on this page. This function is called in both
fnGetInfo and fnCancel functions in myDialog.htm.
-------------------------------------------------------------*/
function fnUpdate()
{
oName.innerText = sUserName;
}
</SCRIPT>
</HEAD>
<BODY>
<P>Enter your first name: <SPAN ID="oName"
STYLE="color:red;font-size:24">Joan</SPAN></P> <INPUT TYPE="button"
VALUE="Display Modeless Dialog" onclick="fnCallDialog()">
</BODY>
</HTML>

Here is the code for "myDialog.htm".

<HTML>
<HEAD>
<TITLE>myDialog.htm</TITLE>
<SCRIPT>
/* -------------------------------------------------------------
This function makes use of the dialogArguments property of the
window object. dialogArguments allows the global variable sUserName
to feed the value supplied to the input in this dialog box back to
the window that called it.
---------------------------------------------------------------- */
function fnGetInfo()
{
var sData = dialogArguments;
sData.sUserName = oEnterName.value;
sData.fnUpdate();
}
/* -------------------------------------------------------------
This function cleans up in case the user has clicked the
Apply button before canceling.
---------------------------------------------------------------- */
function fnCancel()
{
var sData = dialogArguments;
sData.sUserName = "Joan";
sData.fnUpdate();
}
</SCRIPT>
</HEAD>
<BODY>
<LABEL FOR="oEnterName" ACCESSKEY="f">Enter your
<SPAN STYLE="text-decoration:underline">F</SPAN>irst Name</LABEL>
<INPUT ID=oEnterName><BR><BR>
<INPUT VALUE="Apply" TYPE=button onclick="fnGetInfo();">
<INPUT VALUE="Ok" TYPE=button onclick="fnGetInfo();window.close();">
<INPUT VALUE="Cancel" TYPE=button onclick="fnCancel();window.close();">
</BODY>
</HTML>

This feature requires Microsoft® Internet Explorer 5 or later. Click the following icon to install the latest version. Then reload this page to view the sample.

The following example demonstrates many of the features available for creating a custom modeless dialog box.

This feature requires Microsoft® Internet Explorer 4.0 or later. Click the following icon to install the latest version. Then reload this page to view the sample.

Standards Information

There is no public standard that applies to this method.

Applies To

window