Contents

Index

How do I retrieve and modify Mozilla preferences?

Mozilla and Mozilla-based applications load user preferences from a number of sources. Each source is a JavaScript file that contains some special functions not available to other normal JavaScript code. These functions are used to assign preferences into Mozilla's preference system. Newer versions of Mozilla (after 1.4) use a simpler parser to read preferences, but older versions use the JavaScript interpreter to read them. Thus, the older versions may contain arbitrary JavaScript code in addition to the preference code, but only core classes may be used. DOM and XPCOM functions cannot be used.

The following preferences are used:

• Default Preferences: these are stored in the directory defaults/pref in the Mozilla application directory.
• Current Preferences: these are stored in the profile directory with the name prefs.js. This is where the user's settings are stored. This file will be overwritten when the preferences are modified.
• User Preferences: the file user.js in the user's profile directory holds additional preferences the user has added. This file is never written to by Mozilla, but a user may wish to set preferences manually in this file to override other settings.
• Lockfile Settings: these preferences are stored in a file that usually has the name mozilla.cfg or netscape.cfg. The file may be located on a network. It is intended to be used by an administrator or ISP to set settings centrally. In addition, certain preferences may be locked such that a user cannot change them. Locked preferences will be disabled in the Mozilla preferences dialog.

The preferences themselves are identified by a name comprised of a number of words separated by dots. For example, 'browser.startup.homepage' is used to specify the home page. There is no significance to the name of the preference or to each part of the name. Mozilla doesn't handle preferences that start with 'browser' in any special way, however it is strongly recommended that all preferences be grouped like this to eliminate conflicts. When creating your own preference, use your application's name as the initial word.

You can view the current preferences organized by name by entering 'about:config' in the browser address field.

The value of the preferences are of three types, booleans, integers or strings. Use the corresponding JavaScript type to assign preferences of each type. There is also a complex type for representing objects, but you should rarely need to use it, if ever.

The preference system in Mozilla is compatible with that used by Netscape Communicator 4.x. The older navigator.preference function used to retrieve and modify preferences is still supported but it is recommended that you use the XPCOM interface instead. The XPCOM interfaces described below and in the XPCOM reference are frozen and will not change.

The preferences interface allows you to get preferences by using 'branches'. For example, if you request the 'browser' branch, you can use it to retrieve all preferences that begin with 'browser'. When querying via the branch, you can leave out the prefix for simplicity. This would be useful when referring to preferences in your application with the prefix 'xulsample'. Create a branch object, store it globally and then refer to each preference using the branch without having to specify the 'xulsample.' prefix every time.

However, you may also use the preference system without using branches. In this case, you will need to specify the full path to each preference every time. You can retrieve and modify preferences using the nsIPrefBranch interface, which is implemented by each branch, including the top-level, which is really a branch containing all of the preferences.

To use the preference system, you first need to get a reference to the preferences service. Since it is a service, you should use the getService method. Don't use createInstance or things will break. The preference service implements both the nsIPrefService and nsIPrefBranch interfaces.

  var prefs = Components.classes["@mozilla.org/preferences-service;1"].
                getService(Components.interfaces.nsIPrefBranch);

This example will create a preference branch from the top-level, which you can use to return any preference. To get the type of a given preference, use the getPrefType function. Once you know the type, you can use functions to get the value of the preference as a value of that type. The following example will retrieve the browser homepage:

  var homepage;
  if (prefs.getPrefType("browser.startup.homepage") == prefs.PREF_STRING){
    homepage = prefs.getCharPref("browser.startup.homepage");
  }

In this case, you could probably avoid the type check, since the homepage would presumably always be a string. In addition to getCharPref which returns string preferences, there are also getIntPref and getBoolPref functions to return integer and boolean preferences respectively.

You can use various functions beginning with 'set' to modify preferences. For example, the following will disable javascript (chrome applications won't be affected by this):

  prefs.setBoolPref("javascript.enabled",false);

Here is a complete example, which displays the current setting of the 'open tabs in background' preference:

  var prefs = Components.classes["@mozilla.org/preferences-service;1"].
                getService(Components.interfaces.nsIPrefBranch);

  var tabsMode;
  if (prefs.getPrefType("browser.tabs.loadInBackground") == prefs.PREF_BOOL){
    tabsMode = prefs.getBoolPref("browser.tabs.loadInBackground");
  }
  alert(tabsMode);