Dev : Using preferencesFrom MozillaZine Knowledge BaseThis page is part of the extension development documentation project. Ask your questions in MozillaZine Forums. Also try browsing example code. Note: development documentation is in process of being moved to Mozilla Development Center (MDC). This article is about using Mozilla Preferences system. Information here applies to the Mozilla Suite, Firefox, Thunderbird and possibly other Mozilla-based applications. Intended audience is Mozilla extension developers who wish to learn details about using preferences in Mozilla. If you haven't yet, read other documents about Mozilla preferences on XUL Planet and on mozilla.org (links below in Resources section).
XPCOM interfaces for preferences systemMozilla exposes its preferences system through a few XPCOM interfaces. Look in the Resources section below for the link to list of preferences-related interfaces. Three most used interfaces are It's worth noting that there also is an Preferences service is instantiated exactly as any other service. (See Creating XPCOM Components document at XUL Planet for details.) To get an Here are two examples: // Get the root branch var prefs = Components.classes["@mozilla.org/preferences-service;1"]. getService(Components.interfaces.nsIPrefBranch); // Get the "extensions.myext." branch var prefs = Components.classes["@mozilla.org/preferences-service;1"]. getService(Components.interfaces.nsIPrefService); prefs = prefs.getBranch("extensions.myext."); Simple typesThere are three types of preferences: string, integer and boolean. Each entry in preferences database (prefs.js) has one of those types. There are six methods of // prefs is an nsIPrefBranch. // Look in the above section for examples of getting one. var value = prefs.getBoolPref("accessibility.typeaheadfind"); // get a pref prefs.setBoolPref("accessibility.typeaheadfind", !value); // set a pref Complex typesAs noted in previous section, each entry in prefs database (prefs.js) must have a string, an integer or a boolean value. However, there is a concept of complex types, which makes it easier for developers to save and load There are two void getComplexValue(in string aPrefName, in nsIIDRef aType, [iid_is(aType), retval] out nsQIResult aValue); void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue); As you can see, both of them take
nsISupportsStringAs noted above, this is used to handle unicode strings in preferences. Example: // prefs is an nsIPrefBranch // Example 1: getting unicode value var value = prefs.getComplexValue("preference.with.non.ascii.value", Components.interfaces.nsISupportsString).data; // Example 2: setting unicode value var str = Components.classes["@mozilla.org/supports-string;1"] .createInstance(Components.interfaces.nsISupportsString); str.data = "some non-ascii text"; prefs.setComplexValue("preference.with.non.ascii.value", Components.interfaces.nsISupportsString, str); nsIPrefLocalizedStringAnother complex type supported by Mozilla is It's easier to explain this on example. Let's say you want to make the default value for
The code in step 3 will read the default value from nsILocalFile and nsIRelativeFilePrefPlease see the File IO article for details on Default preferencesEach preference may have up to two values — current and default. That means there are two “pref trees” — current and default, — and each of them may or may not have a value for preference in question. You can see the list of preferences in about:config (where available). Preferences that have user value are bold, those that don't have a user value are printed in normal font. What effect do default preferences have on various get methodsWhen one of get methods of
If the branch is from the “default” tree, the get method doesn't check the tree with current values at all. (This is not exactly how it's coded in Where are the default values read from
How to install extension's defaults filesFor Mozilla, copy them to For Firefox/Thunderbird, just put them in Using preferences observersYou can use Note: During Gecko 1.8 development, Here's an example (note, this code hasn't actually been tested, so it may contain typos and other errors): var myPrefObserver = { register: function() { var prefService = Components.classes["@mozilla.org/preferences-service;1"]. getService(Components.interfaces.nsIPrefService); this._branch = prefService.getBranch("extensions.myextension."); var pbi = this._branch.QueryInterface(Components.interfaces.nsIPrefBranchInternal); pbi.addObserver("", this, false); }, unregister: function() { if(!this._branch) return; var pbi = this._branch.QueryInterface(Components.interfaces.nsIPrefBranchInternal); pbi.removeObserver("", this); }, observe: function(aSubject, aTopic, aData) { if(aTopic != "nsPref:changed") return; // aSubject is the nsIPrefBranch we're observing switch (aData) { case "pref1": // extensions.myextension.pref1 was changed break; case "pref2": // extensions.myextension.pref2 was changed break; } } } myPrefListener.register(); Using preferences in extensionsIf you're writing your extension for one of Toolkit applications (Firefox, Thunderbird, Nvu), it's recommended to provide default values for your extension's preferences (see above for information on how to do it). It has the following benefits:
Javascript wrappers for preferences systemThere are a few Javascript wrappers to make your life easier: see this and this. Resources
|