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

Properties

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

Methods

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>

Related

prefpane