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,