Preferences system

  • Revision slug: Mozilla/Preferences/Preferences_system
  • Revision title: Preferences system
  • Revision id: 94028
  • Created:
  • Creator: Mgjbot
  • Is current revision? No
  • Comment robot Adding: ja

Revision Content

This document describes the Aviary Toolkit's new 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).

Note: the Preferences System is only available starting with Firefox/Thunderbird 1.5 (including their alpha and beta releases). You can't use it in Firefox 1.0-based applications and extensions.

The new system is implemented through a few XUL elements and attributes. Reference information about them is available, just click on one of links below:

{{template.Preferences_System_TOC()}}

Use

this will eventually be moved from here

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 opening a preferences dialog from a XULRunner application, be sure to check the following:

  • The boolean preferences browser.preferences.animateFadeIn and browser.preferences.instantApply should be defined in the default preferences (see {{template.Bug(302509)}}). Example:
pref("browser.preferences.animateFadeIn", false);
pref("browser.preferences.instantApply", true);
  • When calling openDialog() to open a preferences dialog, "toolbar" should be included in the features string. 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)

{{ wiki.languages( { "fr": "fr/Syst\u00e8me_de_pr\u00e9f\u00e9rences", "ja": "ja/Preferences_System" } ) }}

Revision Source

<p>
</p><p>This document describes the Aviary Toolkit's new 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).
</p><p><b>Note:</b> the Preferences System is only available starting with Firefox/Thunderbird 1.5 (including their alpha and beta releases). You can't use it in Firefox 1.0-based applications and extensions.
</p><p>The new system is implemented through a few <a href="en/XUL">XUL</a> elements and attributes. Reference information about them is available, just click on one of links below:
</p><p>{{template.Preferences_System_TOC()}}
</p>
<h3 name="Use"> Use </h3>
<p><span class="comment">this will eventually be moved from here</span>
</p><p>Code for a typical preferences window may look like this:
</p>
<pre>&lt;prefwindow id="appPreferences"
            xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
  &lt;prefpane id="pane1" label="&amp;pane1.title;"&gt;
    &lt;preferences&gt;
      &lt;preference id="pref1" name="pref.name" type="bool"/&gt;
    &lt;/preferences&gt;
     
   .. UI elements that refer to the preferences above, e.g.:
    &lt;checkbox id="check1" preference="pref1"
              label="&amp;check1.label;" accesskey="&amp;check1.accesskey;"/&gt;
  &lt;/prefpane&gt;

  &lt;prefpane id="pane2" label="&amp;pane2.title;" src="chrome://uri/to/pane.xul"/&gt;
&lt;/prefwindow&gt;
</pre>
<p>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).
</p>
<h3 name="Usage_in_XULRunner_applications"> Usage in XULRunner applications </h3>
<p>When opening a preferences dialog from a XULRunner application, be sure to check the following:
</p>
<ul><li> The boolean preferences browser.preferences.animateFadeIn and browser.preferences.instantApply should be defined in the default preferences (see {{template.Bug(302509)}}). Example:
</li></ul>
<pre class="eval">pref("browser.preferences.animateFadeIn", false);
pref("browser.preferences.instantApply", true);
</pre>
<ul><li> When calling openDialog() to open a preferences dialog, "toolbar" should be included in the features string. Example:
</li></ul>
<pre class="eval">var features = "chrome,titlebar,toolbar,centerscreen,modal";
window.openDialog(url, "Preferences", features);
</pre>
<h3 name="Bugzilla"> Bugzilla </h3>
<p>The component for bugs in the Preferences bindings (but not in Firefox/Thunderbird Options UI) is Toolkit:Preferences (<a class="external" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Toolkit">file a bug</a> <a class="external" href="https://bugzilla.mozilla.org/buglist.cgi?query_format=advanced&amp;product=Toolkit&amp;component=Preferences&amp;resolution=---&amp;chfieldto=Now">list open bugs</a>)
</p>{{ wiki.languages( { "fr": "fr/Syst\u00e8me_de_pr\u00e9f\u00e9rences", "ja": "ja/Preferences_System" } ) }}
Revert to this revision