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

Creating a Dialog

The openDialog() function is used to open a dialog, and is related to open(). This function differs from open() in several ways. It displays a dialog instead of a window, which implies that it is asking something of the user. It also has subtle differences in the way it works and appears to the user. These differences will vary depending on the platform the application is running on.

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 you wish. 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 is displayed. It's 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 when creating the dialog, then call that 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 ability to construct up to four buttons along the bottom of the dialog forOK,Cancel, and so on. You do not need to include the XUL for each button; however, you do need to supply code to perform the appropriate tasks when the user presses each button. This mechanism is necessary because different platforms have a specific order in which the buttons appear.

Example Dialog

Source View

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

<dialog id="donothing" title="Dialog example"
        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() both return true, which indicates that the dialog should be closed. If the dialog shouldn't be closed, false should be returned instead. This would be used, for example, if an invalid value was entered in a field in the dialog.

Amongst other useful attributes are

• buttonlabelaccept - label to appear on the accept button egSave
• buttonaccesskeyaccept - access key to use for the accept button egS
• defaultButton - button is activated when the Enter key is pressed

Example Dialog with more features

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

<dialog id="myDialog" title="My Dialog"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
        onload="window.sizeToContent();"
        buttons="accept,cancel"
        buttonlabelaccept="Set Favourite"
        buttonaccesskeyaccept="S"
        ondialogaccept="return doSave();"
        buttonlabelcancel="Cancel"
        buttonaccesskeycancel="n"
        ondialogcancel="return doCancel();">

<script>
function doSave(){
 //doSomething()
 return true;
}
function doCancel(){
  return true;
}
</script>

<dialogheader title="My dialog" description="Example dialog"/>
<groupbox flex="1">
  <caption label="Select favourite fruit"/>
  <radio id="orange" label="Oranges because they are fruity"/>
  <radio id="violet" selected="true" label="Strawberries because of their colour"/>
  <radio id="yellow" label="Bananas because they are pre-packaged"/>
</groupbox>

</dialog>

The buttons elements can be accessed with the following javascript

// the accept button
var acceptButt = document.documentElement.getButton("accept")

More examples

More examples in Dialogs and prompts (code snippets).

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