mozilla
Your Search Results

    extIPreferenceBranch

    This content covers features introduced in Thunderbird 3

    The extIPreferenceBranch interface provides simplified access to preferences. The interface has a predefined root preference branch. The root branch is set based on the context of the owner. For example, an extension's preferences has a root of "extensions.extensionid.", while the application-level preferences have an empty root. All preference "aName" parameters used in this interface are relative to the root branch. extIPreferenceBranch is defined in toolkit/components/exthelper/extIApplication.idl.

    Implemented via XPCOM service for extIApplication: see the instructions on the FUEL (Firefox), STEEL (Thunderbird) and SMILE (SeaMonkey) pages.

    Method overview

    boolean has(in AString aName)
    extIPreference get(in AString aName)
    nsIVariant getValue(in AString aName, in nsIVariant aDefaultValue)
    void setValue(in AString aName, in nsIVariant aValue)
    void reset()

    Attributes

    Attribute Type Description
    root readonly attribute AString The name of the branch root.
    all readonly attribute nsIVariant Array of extIPreference listing all preferences in this branch.
    events readonly attribute extIEvents The events object for the preferences supports: "change"

    Methods

    has()

    Check to see if a preference exists.

    boolean has(in AString aName)
    
    Parameters
    aName
    The name of preference
    Return value

    true if the preference exists, false if not

    get()

    Gets an object representing a preference

    extIPreference get(in AString aName)
    
    Parameters
    aName
    The name of preference
    Return value

    a preference object, or null if the preference does not exist

    getValue()

    Gets the value of a preference. Returns a default value if the preference does not exist.

    nsIVariant getValue(in AString aName, in nsIVariant aDefaultValue)
    
    Parameters
    aName
    The name of a preference
    aDefaultValue
    The default value of a preference.  This will be passed back to you without any processing and can be something which would not be valid as a preference.  For example, null/undefined/an object.
    Return value

    The value of the preference or the given default value if preference does not exists.  The use of a variant as the return value means that to JavaScript code the value will appear as a value of the same type as is used in the preferences file and no coercion will occur.  A quoted string in the preference file will always appear as a string, even if the value of the string is "true" or "false".  An integer preference appears as a JavaScript Number, and a boolean appears as a JavaScript Boolean.  There are no other types supported by the preference subsystem.

    setValue()

    Sets the value of a preference with the given name.

    void setValue(in AString aName, in nsIVariant aValue)
    
    Parameters
    aName
    The name of a preference
    aValue
    The value of a preference
    Return value

     

    reset()

    Resets all preferences in a branch back to their default values.

    Note: This function has not been implemented and will raise an exception.  See bug 481044
    void reset()
    
    Parameters
    Return value

    Examples

    var myExt = Application.extensions.get('myapplicationid');
    
    function myFunc (event) {
      Application.console.log('change!');
    };
    
    myExt.prefs.get("myprefname").events.addListener("change", myFunc);
    

    See also

     FUEL (Firefox), STEEL (Thunderbird) and SMILE (SeaMonkey)

    Known issues

    Bug 488587 - Function registered as FUEL preference listener not always called

    Document Tags and Contributors

    Last updated by: Sheppy,