Preferences System:preference

From MDC

Contents 1 Overview 2 XUL Syntax 3 Attributes 4 Properties 5 Methods 6 Events

[edit] Overview

<preference> is a representation of a preference, an element that is used as an intermediary between UI elements and items in user preferences.

It must be a direct child of <preferences>.

[edit] XUL Syntax

<preference id="pref_id" name="preference.name" type="int"/>

[edit] Attributes

id 

The id of the element, it's used as a value of preference attribute on UI elements.

instantApply 

You can set this attribute to true to make the preference apply instantly, even when the global setting is not to use instant apply.

inverted 

(Applies only to prefs with type="bool".) When this is set to true, the value on the associated UI element is a negation of the value stored in user preferences.

name 

The preference it controls (e.g. browser.preferences.instantApply).

readonly 

When set to true, changing the value of associated UI elements doesn't affect the preference. Note that setting this attribute to true doesn't disable the UI element.

type 

The type of the preference. Possible values are: int, bool, string (for non-unicode (ASCII) strings), wstring (like nsIPrefLocalizedString), unichar (unicode string), file (nsIFile).

[edit] Properties

defaultValue (readonly) 

Returns the default value of the preference. The type of the property depends on the value of the type property.

disabled (boolean)

Gets/sets the value of disabled attribute, also updating disabled property of associated UI elements. (but initial value of attribute doesn't seem to have any effect??)

hasUserValue (readonly boolean) 

Returns true if the preference has a user value set.

instantApply (readonly boolean) 

Whether to use instant apply for this preference. This is true if either the element has an instantApply attribute set to true, or the <prefwindow>'s instantApply property is true. (But note bug 293439.)

inverted (boolean) 

Gets and sets the value of the inverted attribute.

locked (readonly boolean) 

Returns true if the preference is locked.

name (string) 

Gets and sets the value of the name attribute.

preferences (readonly DOMElement) 

Parent <preferences> element.

readonly (boolean) 

Gets and sets the value of the readonly attribute.

tabIndex (integer) 

Gets/sets the value of tabindex attribute, also updating tab index of associated UI elements. (?? same comment as for disabled)

type (string) 

Gets and sets the value of the type attribute.

value 

The current value of the preference. If instantApply is on, this is always equal to valueFromPreferences. Otherwise, it's the current value of associated UI elements, i.e. what user currently sees.

valueFromPreferences 

Gets and sets the value stored in the user preference, specified in name.

[edit] Methods

type getElementValue(in DOMElement element); 

Retrieves the value that should be written to preferences based on the current state of the supplied element. This function calls onsynctopreference.

boolean isElementEditable(in DOMElement element) 

Returns true, if the given element is "editable" (see below).

void reset(); 

Resets the preference to its default value.

Note: this method throws an exception if the preference doesn't have a user value set yet.

void setElementValue(in DOMElement element); 

Initializes the supplied element from the value stored in the preference. This function calls onsyncfrompreference.

void updateElements(); 

Update all elements that observe this preference.

[edit] Events

change 

When a preference value changes, an onchange/change event is fired on the <preference> element. You can handle this if you wish to.