Preference XUL Attributes

<prefwindow> 裡的 Widgets 可能有下述屬性 (除此以外，尚有標準屬性).

preference

Specifies id of the linked <preference> element. preference 和 widget 兩者的 value 將保持同步.

如下例，當 pane 被載入時， textbox 從名稱 extensions.example.mypref 的 preference 來自動初始化它的 value ；反過來說，當使用者改變 textbox 的 value 時，<preference>元素的 value 會同步更新，並將在適當的時候儲存至 preferences system.

<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. 例如，你可能有一個 checkbox，當一個整數值是 3 時它被打勾，是 2 時不被打勾。為了初始化這個 UI 元素，你不能依賴預設的 initialization routine，因為這兩個數值對 checkbox 元素來說是無意義的. 你需要寫轉換函數來轉換 preference value 成 UI 元素可用的初始值，並且也轉換 UI 元素的 value 成某些格式來儲存至 preferences file. 這就是 onsyncfrompreference/onsynctopreference 的作用.

onsyncfrompreference 被呼叫，當一個元素從 preferences 被初始化。 明確地說, 當一個 preference 元素的 value 被載入, 所有使用那個 preference 的元素將使他們的 onsyncfrompreference handler 被呼叫.

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.