Preferences system

  • Revision slug: Mozilla/Preferences/Preferences_system
  • Revision title: Preferences system
  • Revision id: 94035
  • Created:
  • Creator: reverendlinux
  • Is current revision? No
  • Comment 17 words added

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:

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

{{ languages( { "de": "de/Preferences_System", "es": "es/Sistema_de_preferencias", "fr": "fr/Syst\u00e8me_de_pr\u00e9f\u00e9rences", "ja": "ja/Preferences_System", "pl": "pl/System_preferencji" } ) }}

Revision Source

<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><strong>Note:</strong> 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" title="en/XUL">XUL</a> elements and attributes. Reference information about them is available, just click on one of links below:</p>
<p>{{ Preferences_System_TOC() }}</p>
<h3 id="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 <a class=" external" href="http://en.wikipedia.org/wiki/Human_interface_guidelines" title="http://en.wikipedia.org/wiki/Human_interface_guidelines">HIGs</a> 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 id="Usage_in_XULRunner_applications" name="Usage_in_XULRunner_applications">Usage in XULRunner applications</h3>
<p>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.</p>
<p>Example:</p>
<pre class="eval">var features = "chrome,titlebar,toolbar,centerscreen,modal";
window.openDialog(url, "Preferences", features);
</pre>
<h3 id="Bugzilla">Bugzilla</h3>
<p>The component for bugs in the Preferences bindings (but not in Firefox/Thunderbird Options UI) is Toolkit:Preferences (<a class="link-https" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Toolkit">file a bug</a> <a class="link-https" 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>
<p>{{ languages( { "de": "de/Preferences_System", "es": "es/Sistema_de_preferencias", "fr": "fr/Syst\u00e8me_de_pr\u00e9f\u00e9rences", "ja": "ja/Preferences_System", "pl": "pl/System_preferencji" } ) }}</p>
Revert to this revision