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