preference

Declares a preference that may be adjusted in a prefpane. This element must be placed inside a preferences element. Each preference element corresponds to a preference which is stored in the user's preferences file. You can connect a user interface element such as a checkbox to a preference element using the user interface element's preference attribute.

More information is available in the Preferences System article.

Attributes
disabled, instantApply, inverted, name, onchange, readonly, tabindex, type
Properties
defaultValue, disabled, hasUserValue, inverted, locked, name, preferences, readOnly, tabIndex, type, value, valueFromPreferences
Methods
reset

Examples

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

See Preferences System for a complete example.

Attributes

disabled
Type: boolean
Indicates whether the element is disabled or not. If this element is set to true the element is disabled. Disabled elements are usually drawn with grayed-out text. If the element is disabled, it does not respond to user actions, it cannot be focused, and the command event will not fire.
Visible controls have a disabled property which, except for menus and menuitems, is normally preferred to use of the attribute, as it may need to update additional state.
instantApply
Type: boolean
If true, the preference will be changed as soon as the user interface is modified.
inverted
Type: boolean
For boolean preferences, if this attribute is set to true, it indicates that the value of the preference is the reverse of the user interface element attached to it. For instance, checking the checkbox disables the preference instead of enabling it.
name
Type: string
The name of the preference to change. For example, the browser's home page is set with the preference browser.startup.homepage.

Overview

An onchange attribute is an event listener to the object for the Event change. A change event is fired in different ways for different XUL Input Elements as listed below:

onchange
Type: script code
TextBox When Enter key is pressed
Radio/Check Box When the state is changed
Select List When the selected item is changed

What is accessible

The script context at this point can only access the following things:

  • Global Values/Functions i.e. window, document, or any of the functions/objects/variables bound to the window object
  • Event object

Example

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<window
    id="findfile-window"
    title="Find Files"
    orient="horizontal"
    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <script type="text/javascript">
  function myFunction(e){
    /*
      Do something cool here or just say the below
    */
    alert(e.target.nodeName);
  }
  </script>
  <textbox id="find-text" onchange="return myFunction(event);"/>
</window>

 

readonly
Type: boolean
If set to true, then the user cannot change the value of the element. However, the value may still be modified by a script.
tabindex
Type: integer
The tab order of the element. The tab order is the order in which the focus is moved when the user presses the "tab" key. Elements with a higher tabindex are later in the tab sequence.
type
Type: one of the values below
The preference type which should be one of the following values.
bool
A boolean set to either true or false. Usually a checkbox would be connected to these preferences.
int
An integer
string
A string
unichar
A Unicode string
wstring
A localized string. In this situation the preference will save the path to a property file which contains the actual value of the preference.
file
A file. The file path will be stored in the preferences.

 

Properties

defaultValue (readonly)
Returns the default value of the preference. The type of the property depends on the value of the type property.
If the preference has no default value, this property returns null.

disabled
Type: boolean
Gets and sets the value of the disabled attribute.
hasUserValue
Type: boolean
True if the preference has been changed from its default value.

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 451025.)

inverted
Type: boolean
Gets and sets the value of the inverted attribute.
locked
Type: boolean
If true, the preference has been locked and disabled in the system configuration, preventing the value from being changed. This property is read-only.
name
Type: string
The name of the preference to change. For example, the browser's home page is set with the preference browser.startup.homepage.
preferences
Type: element
Reference to the containing preferences element.
readOnly
Type: boolean
If set to true, then the user cannot modify the value of the element.
tabIndex
Type: integer
Gets and sets the value of the tabindex attribute.
type
Type: string
Gets and sets the value of the type attribute.

value
Gets and sets the value of the user preference specified in name. In pref dialogs with instantApply == true (default on Mac OS X) this value is kept in sync with the actual value stored in the preferences (see valueFromPreferences). When instantApply is off (default on Windows), this gets and sets the current value of the preference in the currently open dialog.

There's a special case of value === undefined, indicating that the preference does not have a user-set value (hasUserValue == false). In this case the actual value to be displayed in the UI is obtained from the defaultValue property.
valueFromPreferences
Gets and sets the value stored in the user preference, specified in name. (This always accesses the nsIPrefBranch APIs regardless of the instantApply mode in effect).

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

reset()
Return type: no return value
Resets the preference to its default value.
For a textbox it also clears the undo transaction list (Gecko 1.9).

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.

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature, getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

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.

Document Tags and Contributors

Contributors to this page: Sheppy, Enn, pippijn, Nickolay, Marsf, Db48x, trevorh, another_sam, Mgjbot, Ptak82, Dria
Last updated by: Sheppy,