Preferences system

This document describes Toolkit's preferences system. Using this system it is possible to create preferences windows that display and operate appropriately on various platforms (Windows, MacOS X and GNOME).

The system is implemented through a few XUL elements and attributes. Reference information about them is available below:

Use

Code for a typical preferences window may look like this:

<prefwindow id="appPreferences"
            xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <prefpane id="pane1" label="&pane1.title;">
    <preferences>
      <preference id="pref1" name="pref.name" type="bool"/>
    </preferences>
   .. UI elements that refer to the preferences above, e.g.:
    <checkbox id="check1" preference="pref1"
              label="&check1.label;" accesskey="&check1.accesskey;"/>
  </prefpane>
  <prefpane id="pane2" label="&pane2.title;" src="chrome://uri/to/pane.xul"/>
</prefwindow>

Pane content can be specified inline or an external chrome URI supplied for pane content to be loaded in via a dynamic overlay. You should be careful to read the HIGs for the platforms you are targeting and use the XUL preprocessor if necessary to set different window titles as appropriate. You should also be careful to specify the width of the window (in em) as appropriate using the preprocessor for each targeted platform, as well as the height (in em) for platforms where the window size does not change as the selected panel is changed (e.g. Windows).

Usage in XULRunner applications

When calling openDialog() to open a preferences dialog, "toolbar" should be included in the features string.  Not using "toolbar" will cause the preferences dialog to only display one preference pane.

Example:

var features = "chrome,titlebar,toolbar,centerscreen,modal";
window.openDialog(url, "Preferences", features);

Bugzilla

The component for bugs in the Preferences bindings (but not in Firefox/Thunderbird Options UI) is Toolkit:Preferences (file a bug list open bugs)