 | JavaScript | |||
|---|---|---|---|---|
| Prev | Home | Up | Next |
| Availability: |
| |||
| Property/method value type: | User defined | |||
| JavaScript syntax: | IE | myWindow.showModalDialog(aURL, someArguments) | ||
| IE | myWindow.showModalDialog(aURL, someArguments, someFeatures) | |||
| IE | showModalDialog(aURL, someArguments) | |||
| IE | showModalDialog(aURL, someArguments, someFeatures) | |||
| Argument list: | aURL | A URL to load into the modal dialog | ||
| someArguments | Aggregated arguments to pass to the modal dialog | |||
| someFeatures | Window adornment features | |||
The MSIE browser supports a special window that behaves like a normal window, except that it does not permit any other action until it is dismissed.
To present a modal dialog, you call this method which does not return until the window is dismissed. When the window is dismissed, whatever the returnValue property of that window was set to will be returned as the result of this method call.
You must specify a URL to be loaded into the window and you can also pass arguments to it to control the behavior of any content with some scripts that get loaded with the page. It is that script code which will ultimately store something in the returnValue property of the window before calling window.close() to dismiss the window. The arguments are passed by aggregating them into an array or object which is then 'unpacked' inside the modal dialog's context.
This is only supported on MSIE but you can simulate most of its functionality quite easily in Netscape Navigator. Passing values in and out becomes somewhat tricky but you can accomplish that by passing property values via calls to scripts in other windows or by setting properties belonging to objects that you know will persist long enough for them to be retrieved. However, note that you may not be able to simulate the interlocking modality quite as easily.
A third optional argument can be specified in a similar way to the feature list of a window.open() method. You might put values such as this in the third argument to control the size of the new dialog:
"dialogWidth:5cm; dialogHeight:10cm; dialogTop:0cm; dialogLeft:0cm"
Note that they are a number and a measurement unit in the manner of the CSS positioning style controls. If you don't specify a measurement unit, then MSIE 4 assumes you are measuring in ems and MSIE 5 assumes pixels.
Here is a list of the features that can be applied to a modal dialog window as it is opened:
| Feature | Range | Default | Description |
|---|---|---|---|
| center: | yes, no, 1, 0, on, off | yes | Controls dialog window centering within the desktop. |
| dialogHeight: | height value | none | Sets the dialog window height |
| dialogHide: | yes, no, 1, 0, on, off | no | Controls the dialog window visibility when printing or using print preview. This feature is only available when a dialog box is opened from a trusted application. |
| dialogLeft: | left position | none | Sets the left edge coordinate of the dialog window relative to the upper-left corner of the desktop. |
| dialogTop: | top position | none | Sets the top edge coordinate of the dialog window relative to the upper-left corner of the desktop. |
| dialogWidth: | width value | none | Sets the dialog window width |
| edge: | sunken, raised | raised | Defines the dialog window edge style |
| help: | yes, no, 1, 0, on, off | yes | Controls the context-sensitive Help icon. |
| resizable: | yes, no, 1, 0, on, off | no | Controls the resize box. |
| scroll: | yes, no, 1, 0, on, off | yes | Defines whether the dialog window has scrollbars. |
| status: | yes, no, 1, 0, on, off | Varies | Defines whether the dialog window has a status bar. The default is yes for dialog windows that aren't trusted and no for trusted dialog windows. |
| unadorned: | yes, no, 1, 0, on, off | no | Controls the border window chrome. This feature is only available when a dialog box is opened from a trusted application. |
The result of this method call is the value stored in the returnValue property of the modal window before it is dismissed.
The example demonstrates how to pass some argument values in an array and how to return a value entered by the user.
Note that the feature list for a modal dialog is different to the feature list used in a window.open() method.
The Macintosh version of MSIE does not appear to support the dialog sizing controls although you can write and then read back values in the properties that control size and position.
On the Macintosh variant of MSIE version 5, a modal dialog is displayed but if its contents are scrolled, they can degenerate the off-screen buffer resulting in weird tearing effects in the image data. This may be due to having an <IFRAME> in the window or it may be caused by a timing problem with multiple clicks on the scroll bar in rapid succession.
<!-- Save this in demo.html -->
<HTML>
<HEAD>
</HEAD>
<BODY>
<SCRIPT>
myArray = new Array(100, 200, "XXX", "YYY");
myReturnValue = showModalDialog("./page.html", myArray);
alert("Value returned from window is "+myReturnValue);
</SCRIPT>
</BODY>
</HTML>
---------------------------------------------------------------
<!-- Save this in page.html in the same folder -->
<HTML>
<HEAD>
</HEAD>
<BODY>
Hi there!!
<HR>
Input values are:<BR><BR>
<SCRIPT>
for(myEnum=0; myEnum<dialogArguments.length; myEnum++)
{
document.write(myEnum);
document.write(" - ");
document.write(dialogArguments[myEnum]);
document.write("<BR>");
}
returnValue = prompt("What do you want to send back");
</SCRIPT>
</BODY>
</HTML>| Prev | Home | Next |
| Window.showHelp() | Up | Window.showModelessDialog() |
JavaScript Programmer's Reference, Cliff Wootton Wrox Press (www.wrox.com) Join the Wrox JavaScript forum at p2p.wrox.com Please report problems to support@wrox.com © 2001 Wrox Press. All Rights Reserved. Terms and conditions. | ||