This is now out of date in places, do not rely on it!
There is a wiki page covering this on DevMo:
http://developer-test.mozilla.org/en/do ... ces_System
PrefWindowV
Firefox 1.1 (and Deer Park Developer Preview) will include an updated preferences window, dubbed PrefWindowV. The noticable change was the reorganisation of the user interface, but the more interesting changes are architectural.
PrefWindowV gives two main developer-friendly advantages over previous versions:
- Instant-apply support (enabled by default on Linux and MacOS).
- JavaScript is unnecessary.
What do I need in order to use these?
Firstly, you'll have to grab a stable trunk build that has PrefWindowV, but that shouldn't be too hard as the code has been checked in for a couple of months now.
Secondly, you should build an extension to the point where you double-click on the extension's entry in the Extension Manager and an options window is opened. Doing so is already well documented by other guides, so is not covered here.
Example XUL
This is a mock-up example that you can use as a template when creating your own extension preferences window.
Code: Select all
<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<prefwindow id="myExtensionOptions"
type="prefwindow"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
buttons="accept, cancel"
title="myExtension Options">
<prefpane id="myPane">
<preferences>
<preference id="myBool"
name="extensions.myExtension.myBool"
type="bool"/>
<preference id="myInt"
name="extensions.myExtension.myInt"
type="int"/>
</preferences>
<vbox>
<radiogroup id="radio_myBool"
preference="myBool">
<vbox>
<radio id="default"
label="Default"
value="true"/>
<radio id="custom"
label="Custom"
value="false"/>
</vbox>
</radiogroup>
<textbox id="text_myInt"
preference="myInt"/>
</vbox>
</prefpane>
</prefwindow>
Notes
XUL input elements contained within a <code><prefwindow></code> can now modify preferences without interaction from JavaScript. To do this, you must create a <code><preferences></code> element as a child of <code><prefwindow></code> and place one or more <code><preference></code> elements inside it.
If the preference <code>browser.preferences.instantApply</code> is set to true (the default on Linux/MacOS), then the "Cancel" and "Apply" buttons will be hidden. Changes within that window will instantly update the corresponding preferences.
<code><prefwindow></code>
The <code>prefwindow</code> element can contain <code><prefpane></code> elements. It's attributes are similar to that of <code><dialog></code> with the addition of <code>type</code>, which should be set to <code>prefwindow</code>.
<code><prefpane></code>
This element can either directly contain <code><preferences></code> elements and other XUL as children, or can link to an external document using a <code>src</code> attribute. An example of this can be found by opening up the source of [url]chrome://browser/content/preferences/preferences.xul[/url] in a trunk nightly.
<code><preferences></code>
Contains one or more <code><preference></code> elements.
<code><preference></code>
<code>id</code>: A unique way of referring to that preference from an input element.
<code>name</code>: The preference it controls.
<code>type</code>: Possible values <code>int</code>, <code>bool</code>, <code>string</code> (for non-unicode strings), <code>wstring</code> (like nsIPrefLocalizedString), <code>unichar</code> (unicode string), <code>file</code> (nsIFile).
New attributes
XUL input elements now have new attributes. Again, there's no official documentation to confirm which elements these apply to, so I'll assume that all common input elements are covered.
<code>preference</code>: The <code>id</code> value of the <code><preference></code> you wish this input to control. Should contain a value if <code>preference-editable</code> is set to <code>true</code>.
<code>preference-editable</code>: Allows the element to modify a preference. Defaults to <code>true</code> for the following elements: <code><checkbox></code>, <code><colorpicker></code>, <code><radiogroup></code>, <code><textbox></code>, <code><listitem></code>, <code><listbox></code> and <code><menulist></code>.
<code>onpreferenceread</code>: Code to execute when the preference is read - return value may be used.
<code>onpreferencewrite</code>: Code to execute when the preference is written - return value may be used.
Anything to add?
If you have any feedback / suggestions / questions, feel free to reply to this thread. See also the corresponding knowledgebase document:
Preferences bindings - MozillaZine Knowledge Base