Creating Dialogs

A XUL application will often require dialogs to be displayed. This section describes how one might construct them.

Creating a Dialog

The open function is used to open a window. A related function is openDialog. This function has several main differences. It will display a dialog instead of a window which implies that it is asking something of the user. It may have subtle differences in the way it works and appears to the user. These differences will vary on each platform.

In addition, the openDialog function can take additional arguments beyond the first three. These arguments are passed to the new dialog and placed in an array stored in the new window's arguments property. You can pass as many arguments as necessary. This is a convenient way to supply default values to the fields in the dialog.

var somefile=document.getElementById('enterfile').value;

window.openDialog("chrome://findfile/content/showdetails.xul","showmore",
                  "chrome",somefile);

In this example the dialog 'showdetails.xul' will be displayed. It will be passed one argument, 'somefile', which was taken from the value of an element with the id enterfile. In a script used by the dialog, we can then refer to the argument using the window's arguments property. For example:

var fl=window.arguments[0];

document.getElementById('thefile').value=fl;

This is an effective way to pass values to the new window. You can pass values back from the opened window to the original window in one of two ways. First, you could use the window.opener property which holds the window that opened the dialog. Second, you could pass a function or object as one of the arguments, and then call the function or modify the object in the opened dialog.

The Dialog Element

The dialog element should be used in place of the window element when creating a dialog. It provides the useful capability to construct up to four buttons along the bottom of the dialog for OK, Cancel and so on. You do not need to include the XUL for each button but you do need to supply code to handle when the user presses each button. This mechanism is necessary because different platforms have a specific order in which the buttons appear.

<?xml version="1.0"?>

<?xml-stylesheet href="chrome://global/skin/global.css" type="text/css"?>

<dialog id="donothing" title="Do Nothing"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
        buttons="accept,cancel"
        ondialogaccept="return doOK();"
        ondialogcancel="return doCancel();">

<script>
function doOK()
{
  alert("You pressed OK!");
  return true;
}

function doCancel()
{
  alert("You pressed Cancel!");
  return true;
}
</script>

<description value="Select a button"/>

</dialog>

You may place any elements that you wish in a dialog. The dialog element has some additional attributes that windows do not have. The buttons attribute is used to specify which buttons should appear in the dialog. The following values may be used, seperated by commas:

• accept - an OK button
• cancel - a Cancel button
• help - a Help button
• disclosure - a disclosure button, which is used for showing more information.

You can set code to execute when the buttons are pressed using the ondialogaccept, ondialogcancel, ondialoghelp and ondialogdisclosure attributes. If you try the example above, you will find that the doOK function is called when the OK button is pressed and the doCancel function is called when the Cancel button is pressed.

The two functions doOK and doCancel return true which indicate that the dialog should be closed. If false was returned, the dialog would stay open. This would be used if an invalid value was entered in a field in the dialog.

(Next) Next, we'll see how to open file dialogs.

Examples: 12.2.1