Preference XUL Attributes

Widgets inside a <prefwindow> may have the following attributes (in addition to the standard attributes).

preference

Specifies id of the linked <preference> element. The value of the preference and of the widget will be kept synchronized.

For example, the following example makes the textbox automatically initialize its value from the <tt>extensions.example.mypref</tt> preference, when the pane is loaded. And the other way round, when user changes the value of the textbox, the value of the <preference> element is updated, and will be written to the preferences system when appropriate.

<preference id="my_pref" name="extensions.example.mypref" type="unichar"/>
<textbox preference="my_pref"/>

preference-editable

By default, the <preference> element will automatically modify the value of a few standard widgets: checkbox, colorpicker, radiogroup, textbox, listitem, listbox, and menulist.

If you wish it to update the value of an element with different local name, for example your own XBL widget, you need to set the preference-editable="true" attribute on it.

For your widget to modify the <preference>'s value, you need to make sure a change, command, or input event is fired after the widget's value changes.

bug # or any testcases ? Note: this does not currently work on the tree widget. It may not work on anything so far (the API says it is to be available in version 1.8).

onsyncfrompreference/onsynctopreference

Often you will have UI whose construction does not map easily to a given preference type. For example, you may have a checkbox that is checked when an integer preference value is 3 and not when it's 2. To initialize this UI element you can't rely on the default initialization routine, since both values are meaningless to the checkbox element. You need to write translation functions to translate the preference value into an initialization value for the UI element, and to translate the UI element's value into something to write to the preferences file. This is what onsyncfrompreference/onsynctopreference are for.

onsyncfrompreference is called when an element is initialized from preferences. Specifically, when the value of a preference element is loaded, all the elements using that preference will have their onsyncfrompreference handler called.

If you supply an implementation of this event, your implementation will be invoked during initialization and you can return the value with which to initialize the UI element with, or undefined to tell the preferences system to initialize the UI element with the default value (i.e. to attempt to initialize with the preference value). In the above example, you might write the checkbox like this:

<checkbox preference="foo.bar" onsyncfrompreference="return onsyncfrompreference();"/>

.. script:
function onsyncfrompreference()
{
  var preference = document.getElementById("foo.bar");
  // .value === undefined means the preference is set to the default value
  var actualValue = preference.value !== undefined ?
                      preference.value : preference.defaultValue;
  // actualValue may be |null| here if the pref didn't have the default value.
  return preference.value == 3;

  // If foo.bar was boolean and we wanted to use its value to initialize 
  // the checkbox, we could still implement this method if we wanted to
  // perform any other initialization actions at this time. 
}

onsynctopreference is called when preferences are being written - the preferences system asks each element to translate its current state into a value suitable for writing to the specified preference. You can return a special value or undefined to tell the preferences system to use its standard means for obtaining the value. In the above example:

<checkbox preference="foo.bar" onsynctopreference="return onsynctopreference();"/>
.. script:
function onsynctopreference()
{
  var checkbox = document.getElementById("checkbox");
  return checkbox.checked ? 3 : 2;
}

// If foo.bar was boolean and we wanted to use its value to write to
// preferences, we could still implement this method if we wanted to 
// perform any other initialization actions at this time.