preference

« XUL Reference home [ Examples | Attributes | Properties | Methods | Related ]

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 attribute is set, 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. In the case of form elements, it will not be submitted. Do not set the attribute to true, as this will suggest you can set it to false to enable the element again, which is not the case.
The disabled attribute is allowed only for form controls. Using it with an anchor tag (an <a> link) will have no effect.

The element will, however, still respond to mouse events. To enable the element, leave this attribute out entirely.; 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

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

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

Preferences System documentation:

Introduction: Getting Started | Examples | Troubleshooting
Reference: prefwindow | prefpane | preferences | preference | XUL attributes