showModalDialog Method

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

Syntax

vReturnValue = window.showModalDialog(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. String that specifies the window ornaments for the dialog box, using one or more of the following semicolon-delimited values: dialogHeight:iHeight Sets the height of the dialog window (see Remarks for default unit of measure). dialogLeft:iXPos Sets the left position of the dialog window relative to the upper-left corner of the desktop. dialogTop:iYPos Sets the top position of the dialog window relative to the upper-left corner of the desktop. dialogWidth:iWidth Sets the width of the dialog window (see Remarks for default unit of measure). center:{ yes | no | 1 | 0 } Specifies whether to center the dialog window within the desktop. The default is yes. help:{ yes | no | 1 | 0 } Specifies whether the dialog window displays the context-sensitive Help icon. The default is yes. resizable:{ yes | no | 1 | 0 } Specifies whether the dialog window has set dimensions. The default for both trusted and untrusted dialog windows is no. status:{ yes | no | 1 | 0 } Specifies whether the dialog window displays a status bar. The default is yes for untrusted dialog windows and no for trusted dialog windows.

Return Value

Variant. Returns the value of the returnValue property as set by the window of the document specified in sURL.

Remarks

A modal dialog box retains the input focus while open. The user cannot switch windows until the dialog box is closed.

Because a modal 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.

As of Microsoft® Internet Explorer 4.0, you can eliminate scroll bars on dialog boxes. To turn off the scroll bar, set the SCROLL attribute to false in the BODY element for the dialog window, or call the modal dialog box from a trusted application.

Internet Explorer 5 allows further control over modal dialog boxes through the status and resizable values in the sFeatures parameter of the showModalDialog method. Turn off the status bar by calling the dialog box from a trusted application, such as Microsoft® Visual Basic® or an HTML Application (HTA), or from a trusted window, such as a trusted modal dialog box. These applications are considered to be trusted because they use Internet Explorer interfaces instead of the browser. Any dialog box generated from a trusted source has the status bar turned off by default. Resizing is turned off by default, but you can turn it on by specifying resizable=yes in the sFeatures string of the showModalDialog method.

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.

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

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

Example

This example uses the showModalDialog method to open a customized dialog box.

Sample Code

<SCRIPT>
function fnRandom(iModifier){
   return parseInt(Math.random()*iModifier);
}
function fnSetValues(){
   var iHeight=oForm.oHeight.options[
      oForm.oHeight.selectedIndex].text;
   if(iHeight.indexOf("Random")>-1){
      iHeight=fnRandom(document.body.clientHeight);
   }
   var sFeatures="dialogHeight: " + iHeight + "px;";
   return sFeatures;
}
function fnOpen(){
   var sFeatures=fnSetValues();
   window.showModalDialog("showModalDialog_target.htm", "", 
      sFeatures)
}
</SCRIPT>

<FORM NAME=oForm>
Dialog Height <SELECT NAME="oHeight">
   <OPTION>-- Random --
   <OPTION>150
   <OPTION>200
   <OPTION>250
   <OPTION>300
</SELECT>

Create Modal Dialog Box
<INPUT TYPE="button" VALUE="Push To Create" 
   onclick="fnOpen()">
</FORM>

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

Applies To

[ Object Name ] Platform Version Win16: Win32: Mac: Unix: WinCE: Version data is listed when the mouse hovers over a link, or the link has focus.	window

Back to top

Did you find this topic useful? Suggestions for other topics? write us!

© 1999 microsoft corporation. all rights reserved. terms of use.