1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
|
## Objective
Use this API to access Thunderbird's system preferences or to migrate your own preferences from the Thunderbird preference system to the local storage of your MailExtension.
## Usage
Add the [LegacyPrefs API](https://github.com/thunderbird/webext-support/tree/master/experiments/LegacyPrefs) to your add-on. Your `manifest.json` needs an entry like this:
```
"experiment_apis": {
"LegacyPrefs": {
"schema": "api/LegacyPrefs/schema.json",
"parent": {
"scopes": ["addon_parent"],
"paths": [["LegacyPrefs"]],
"script": "api/LegacyPrefs/implementation.js"
}
}
},
```
## API Functions
This API provides the following functions:
### async getPref(aName, [aFallback])
Returns the value for the ``aName`` preference. If it is not defined or has no default value assigned, ``aFallback`` will be returned (which defaults to ``null``).
### async getUserPref(aName)
Returns the user defined value for the ``aName`` preference. This will ignore any defined default value and will only return an explicitly set value, which differs from the default. Otherwise it will return ``null``.
### clearUserPref(aName)
Clears the user defined value for preference ``aName``. Subsequent calls to ``getUserPref(aName)`` will return ``null``.
### async setPref(aName, aValue)
Set the ``aName`` preference to the given value. Will return false and log an error to the console, if the type of ``aValue`` does not match the type of the preference.
## API Events
This API provides the following events:
### onChanged.addListener(listener, branch)
Register a listener which is notified each time a value in the specified branch is changed. The listener returns the name and the new value of the changed preference.
Example:
```
browser.LegacyPrefs.onChanged.addListener(async (name, value) => {
console.log(`Changed value in "mailnews.": ${name} = ${value}`);
}, "mailnews.");
```
|