mozilla
Your Search Results

    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,