prefwindow

A specialized window used for preference dialogs. This element should be used in place of the window tag and should contain one or more prefpane elements. A row of buttons appears across the preference dialog, one for each prefpane. Each pane will usually group together a set of related preferences. If there is only one prefpane, the navigation area will be hidden.

On platforms where the convention is to apply changes immediately, the preferences are adjusted as soon as the user interface element is changed. On other platforms, the preferences are not applied until the dialog is closed.

You can open a preference window using a window's openDialog method as with other dialogs. You can pass the id of a particular pane as the fourth argument to openDialog to open a specific pane by default. You can also set the lastSelected attribute on the prefwindow tag to the id of the pane to start with. Normally, you would not set this attribute as it will be set automatically such that the default pane is the same as the one showing when the preferences dialog was last closed.

More information is available in the Preferences System article.

Important note for XULrunner-based applications: the Preferences System - part of the toolkit - still relies on two browser.* preferences.

  1. The first one is browser.preferences.instantApply, a boolean preference. The preference window will not run correctly if you do not set this preference in your application's defaults (see bug 485150 for more information). A true value for this preference makes the preference window apply immediately the user choices, without waiting for the dialog to close with OK.
  2. The second preference is browser.preferences.animateFadeIn, again a boolean preference. This one can be safely omitted in XULrunner-based applications but you can override the default behavior (true for Mac OS X and false for other platforms) setting it. For animateFadeIn to work properly, contents of prefpanes should be put into overlays.

Note for Mac OS X: a common way of opening modal windows on Mac OS X that are not attached as a sheet to the main window is to use nsIWindowWatcher.openWindow() with a null parentWindow. This does not work with prefwindows, breaking the general behavior of the window and in particular the list of prefpanes. Prefer the classical window.openDialog() with the following window features: "chrome,titlebar,toolbar,centerscreen,dialog=yes".

Attributes
buttonalign, buttondir, buttonorient, buttonpack, buttons, defaultButton, lastSelected, onbeforeaccept, ondialogaccept, ondialogcancel, ondialogdisclosure, ondialoghelp, onload, onunload, title, type
Properties
buttons, currentPane, defaultButton, lastSelected, preferencePanes, type
Methods
acceptDialog, addPane, cancelDialog, centerWindowOnScreen, getButton, openSubDialog, openWindow, showPane

Examples

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>   
<prefwindow xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <prefpane id="saveoptions" label="Backups">
    <preferences>
      <preference id="pref-backup" name="myapp.mybackups" type="bool"/>
      <preference id="pref-backupduration" name="myapp.mybackups.duration" type="int"/>
    </preferences>
    <checkbox label="Automatically Save Backups" preference="pref-backup"/>
    <textbox label="Duration:" preference="pref-backupduration"/>
  </prefpane>
</prefwindow>

Attributes

activetitlebarcolor
Type: color string
Specify background color of the window's titlebar when it is active (foreground). Moreover this hides separator between titlebar and window contents. This only affects Mac OS X.
buttonalign
Type: string
The value of the align attribute for the box containing the buttons.
buttondir
Type: string
The value of the dir attribute for the box containing the buttons.
buttonorient
Type: string
The value of the orient attribute for the box containing the buttons.
buttonpack
Type: string
The value of the pack attribute for the box containing the buttons.
buttons
Type: comma-separated list of the values below
A comma-separated list of buttons to appear in the dialog box. The buttons will be placed in suitable locations for the user's platform and basic event handling will be performed automatically. The following values can be used in the list:
  • accept: The OK button, which will accept the changes when pressed. This button will also be the default button.
  • cancel: The cancel button which will cancel the operation.
  • help: A help button for displaying help about the dialog.
  • disclosure: A button to show more information. This might be a button or a disclosure triangle.
  • extra1: An optional additional button. You can set its label with the buttonlabelextra1 attribute and its command with the ondialogextra1 attribute.
  • extra2: A second optional additional button. You can set its label with the buttonlabelextra2 attribute and its command with the ondialogextra2 attribute.

Note: If you don't want to display any buttons in the dialog box, set the value of this attribute to "," (a single comma).

Warning: If the accept and cancel buttons are actually shown is system dependent and is mainly controlled by the value of the boolean preference browser.preferences.instantApply. If it is set to true any changes to settings are supposed to be applied immediately. The accept button is therefore unnecessary and is hidden. The cancel button might be shown as an additional possibility to close the dialog in this situation (Windows and Linux) or might be hidden, too (Mac OS).
The default setting of browser.preferences.instantApply currently is true on Linux and Mac OS and false on Windows (which however might or might not change soon, see bug 738797 and bug 1037225).
defaultButton
Type: string
Normally this attribute should not be set, but if it is, it specifies the default button in the dialog. Typically, this means that the button will be activated when the Enter key is pressed. This should be set to one of the same values as those for the buttons attribute.
inactivetitlebarcolor
Type: color string
Specify background color of the window's titlebar when it is inactive (background). Moreover this hides separator between titlebar and window contents. This affects only on Mac OS X.
lastSelected
Type: string
Set this to the id of the last selected pane. It will be opened by default the next time the preferences dialog is opened.
onbeforeaccept
Type: script code
The code in this attribute is called when the OK button is pressed or the acceptDialog method is called. Returning false doesn't currently prevent the dialog from closing, but does prevent saving (bug 474527).

 

ondialogaccept
Type: script code
The code in this attribute is called when the accept button is pressed, or when the acceptDialog method is called. If the handler returns true, the dialog will indeed go away, but if it returns false it will not.
ondialogcancel
Type: script code
The code in this attribute is called when the "cancel" button is pressed or when the cancelDialog method is called. If the routine returns true, the dialog will indeed go away, but if it returns false it will not.
ondialogdisclosure
Type: script code
The code in this attribute is called when the "disclosure" button is pressed.
ondialoghelp
Type: script code
The code in this attribute is called when the "help" button is pressed.
onunload
Type: script code
This event handler will be called on the prefwindow element when the window is closed.
title
Type: string
The text to appear in the title bar of the window.
type
Type: string
Set this attribute to child for preference dialogs that are child dialogs of a main preferences window. This ensures that the preferences are only saved when the main dialog is closed, if this is the appropriate behaviour for the platform.

Properties

buttons
Type: comma-separated list of the values below
A comma-separated list of buttons to appear on the dialog box. The buttons will be placed in suitable locations for the user's platform and basic event handling will be performed automatically. The following values can be used in the list:
  • accept: The OK button, which will accept the changes when pressed. This button will also be the default button.
  • cancel: The cancel button which will cancel the operation.
  • help: A help button for displaying help about the dialog.
  • disclosure: A button to show more information. This might be a button or a disclosure triangle.
  • extra1: An optional additional button. You can set its label with the buttonlabelextra1 attribute and its command with the ondialogextra1 attribute.
  • extra2: A second optional additional button. You can set its label with the buttonlabelextra2 attribute and its command with the ondialogextra2 attribute.
currentPane
Type: prefpane element
Reference to the currently displayed pane. To change the current pane, use the showPane method.
defaultButton
Type: string
Normally this attribute should not be set, but if it is, it specifies the default button in the dialog. Typically, this means that the button will be activated when the Enter key is pressed. This should be set to one of the same values as those for the buttons attribute.

instantApply (readonly) 
Indicates whether the window is in "instant apply" mode. The value is read from browser.preferences.instantApply boolean user preference. (?? It's declared as a <field>, so you can set the value, however I don't believe it's valid to do that.)

lastSelected
Type: string
Set this to the id of the last selected pane. It will be opened by default the next time the preferences dialog is opened.
preferencePanes
Type: DOM NodeList
Holds a list of all the prefpane elements in the window.
type
Type: string
Gets and sets the value of the type attribute.

Methods

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature(), getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

acceptDialog()
Return type: no return value
Accepts the dialog and closes it, similar to pressing the OK button.
addPane( prefpane )
Return type: no return value
Append a prefpane to a list of panes.

animate(aOldPane, aNewPane)
This probably isn't a public method (?)

cancelDialog()
Return type: no return value
Cancels the dialog and closes it, similar to pressing the Cancel button.
centerWindowOnScreen()
Return type: no return value
Centers the dialog on the screen.
getButton( type )
Return type: button element
Returns the button element in the dialog corresponding to the given type.
openSubDialog( url, features, params )
Return type: window
Opens a child modal dialog. Usually this method would be used to allow the user to configure advanced options. The arguments are similar to the window's openDialog method except that the window name does not need to be supplied. The <var>url</var> should be a XUL file. If the child dialog is also a prefwindow, set its type attribute to child so that preferences will be saved properly when the main dialog is closed.
openWindow( windowtype, url, features, params )
Return type: window
Open a child window. The windowtype is a string specifying a window type. If a window with that type is already open, this method will just switch that window to the front and focus it instead of opening another window. If a window of the type is not open, a new one is opened displaying the supplied url.
showPane( prefpane )
Return type: no return value
Switch to a particular pane.

 

Notes

Usage patterns

Opening/initializing a prefwindow

Note that you can define an initWithParams() function in your sub window - to handle parameters passed using openWindow() in case the window was already open. For example the Permissions Manager UI in Firefox uses the same window for three dialogs: Images, Software installation and Popups. It uses initWithParams() to change the dialog type without closing and re-opening it.

The suggested usage pattern is as follows:

// subwindow.js
function onLoad(ev) {
  // do some initialization...
  initWithParams(window.arguments[0]); // we expect a single parameter to be passed to the window
}
function initWithParams(aParams) {
  // this will also get called when an already open window is activated using openWindow()
}

Closing a prefwindow

Sometimes you need to do things when the prefwindow is closed, such as things that can't (or shouldn't) be handled as preferences, such as saving passwords or updating SQLite data. To do this, you can set the prefwindow's onunload attribute to a function that will be run when the prefwindow is closed.

<prefwindow
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
  id="my-config-dialog"
  title="My application: configuration"
  onunload="onUnload(event.target)">
</prefwindow>
function onUnload(prefwindow) {
  // Do actions there like saving values, password setting (that is not handled as a preference), etc.
  return true;
}

Opening a modal sub dialog

A sub dialog can only be opened via document.documentElement and not via window. Therefore, an example call to openSubDialog() would look like this:

document.documentElement.openSubDialog("chrome://myextension/content/options-sub.xul", "", null)

Issues when using prefpanes in prefwindow

When you wish to put non-<prefpane> elements to prefwindow, you should place them after all of <prefpane>s. If you put other elements before the first <prefpane>, you possibly see strange behaviors about switching panes. This is due to bug 296418.

Should not:

<prefwindow>
  <script src="config.js"/>
  <prefpane label="pane1" src="pane1.xul"/>
  <prefpane label="pane2" src="pane2.xul"/>
</prefwindow>

Should:

<prefwindow>
  <prefpane label="pane1" src="pane1.xul"/>
  <prefpane label="pane2" src="pane2.xul"/>
  <script src="config.js"/>
</prefwindow>

prefpane

Document Tags and Contributors

 Last updated by: jan-kiszka,