nsIPrefBranch

This object is created with a "root" value which describes the base point in the preferences "tree" from which this "branch" stems. Preferences are accessed off of this root by using just the final portion of the preference. For example, if this object is created with the root "browser.startup.", the preferences "browser.startup.page", "browser.startup.homepage", and "browser.startup.homepage_override" can be accessed by simply passing "page", "homepage", or "homepage_override" to the various Get/Set methods.

Method overview

Attributes

Constants

Methods

addObserver()

Adds a preference change observer. On preference changes, the following arguments will be passed to nsIObserver.observe():

aSubject - The nsIPrefBranch object (this).

aTopic - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID

aData - The name of the preference which has changed, relative to the "root" of the aSubject branch.

aSubject.get*Pref(aData) will get the new value of the modified preference. For example, if your observer is registered with addObserver("bar.", ...) on a branch with root "foo.", modifying the preference "foo.bar.baz" will trigger the observer, and aData parameter will be "bar.baz".

void addObserver(
  in string aDomain, 
  in nsIObserver aObserver, 
  in boolean aHoldWeak
);

Parameters

aDomain

The preference on which to listen for changes. This can be the name of an entire branch to observe. For example holding the "root" prefbranch and calling addObserver("foo.bar.", ...) will observe changes to foo.bar.baz and foo.bar.bzip.

aObserver

The object to be notified if the preference changes. The structure of aObserver is any object with an observe function. See nsIObserver and here is a quick snippet:

var myObserver = {
   observe: function(aSubject, aTopic, aData) {
      //do stuff here
   }
}

aHoldWeak

true holds a weak reference to aObserver. The object must implement the nsISupportsWeakReference interface or this will fail. false holds a strong reference to aObserver.

clearUserPref()

Called to clear a user set value from a specific preference. This will, in effect, reset the value to the default value. If no default value exists the preference will cease to exist.

void clearUserPref(
  in string aPrefName
);

Parameters

aPrefName

The preference to be cleared.

Remarks

deleteBranch()

Called to remove all of the preferences referenced by this branch.

void deleteBranch(
  in string aStartingAt
);

Parameters

aStartingAt

The point on the branch at which to start the deleting preferences. Pass in "" to remove all preferences referenced by this branch.

getBoolPref()

Called to get the state of an individual boolean preference.

boolean getBoolPref(
  in string aPrefName,
  [optional] in boolean aDefaultValue
);

Parameters

aPrefName

The boolean preference to get the state of.

aDefaultValue Requires Gecko 54

Optional - a default value to use if the preference does not exist (instead of throwing an exception).

Return value

The value of the requested boolean preference.

getCharPref()

Called to get the state of an individual string preference.

string getCharPref(
  in string aPrefName,
  [optional] in string aDefaultValue
);

Parameters

aPrefName

The string preference to retrieve.

aDefaultValue Requires Gecko 54

Optional - a default value to use if the preference does not exist (instead of throwing an exception).

Return value

Returns string - The value of the requested string preference.

getChildList()

Returns an array of strings representing the child preferences of the root of this branch.

(To call from javascript use children = nsIPrefBranch.getChildList("",obj), which will fill in obj.value with the count and return an array of keys! (It is not void in javascript)

void getChildList(
  in string aStartingAt,
  out unsigned long aCount,
  [array, size_is(aCount), retval] out string aChildArray
);

Parameters

aStartingAt

The point on the branch at which to start enumerating the child preferences. Pass in "" to enumerate all preferences referenced by this branch.

aCount Optional from Gecko 2.0

Receives the number of elements in the array.

aChildArray

Receives the array of child preferences.

getComplexValue()

Called to get the state of an individual complex preference. A complex preference is a preference which represents an XPCOM object that can not be easily represented using a standard boolean, integer or string value.

void getComplexValue(
  in string aPrefName,
  in nsIIDRef aType,
  [iid_is(aType), retval] out nsQIResult aValue
);

Parameters

aPrefName

The complex preference to get the value of.

aType

The XPCOM interface that this complex preference represents. Interfaces currently supported are:

• NsILocalFile
• NsISupportsString (UniChar)
• NsIPrefLocalizedString (Localized UniChar)
• NsIFileSpec (deprecated - to be removed eventually)

aValue

The XPCOM object into which to the complex preference value should be retrieved.

getIntPref()

Called to get the state of an individual integer preference.

long getIntPref(
  in string aPrefName,
  [optional] in long aDefaultValue
);

Parameters

aPrefName

The integer preference to get the value of.

aDefaultValue Requires Gecko 54

Optional - a default value to use if the preference does not exist (instead of throwing an exception).

Return value

Returns long - The value of the requested integer preference.

getPrefType()

Called to determine the type of a specific preference.

long getPrefType(
  in string aPrefName
);

Parameters

aPrefName

The preference to get the type of.

Return value

Returns long - A value representing the type of the preference. This value will be PREF_STRING, PREF_INT, PREF_BOOL, or PREF_INVALID.

lockPref()

Called to lock a specific preference. Locking a preference will cause the preference service to always return the default value regardless of whether there is a user set value or not.

void lockPref(
  in string aPrefName
);

Parameters

aPrefName

The preference to be locked.

prefHasUserValue()

Called to check if a specific preference has a user value associated to it.

boolean prefHasUserValue(
  in string aPrefName
);

Parameters

aPrefName

The preference to be tested.

Return value

Returns boolean - true The preference has a user set value. false The preference only has a default value.

prefIsLocked()

Called to check if a specific preference is locked. If a preference is locked calling its Get method will always return the default value.

boolean prefIsLocked(
  in string aPrefName
);

Parameters

aPrefName

The preference to be tested.

Return value

Returns boolean - true The preference is locked. false The preference is not locked.

removeObserver()

Remove a preference change observer.

  void removeObserver(
     in string aDomain, 
     in nsIObserver aObserver
  );

Parameters

aDomain

The preference which is being observed for changes.

aObserver

An observer previously registered with addObserver.

resetBranch()

Called to reset all of the preferences referenced by this branch to their default values.

void resetBranch(
  in string aStartingAt
);

Parameters

aStartingAt

The point on the branch at which to start the resetting preferences to their default values. Pass in "" to reset all preferences referenced by this branch.

setBoolPref()

Called to set the state of an individual boolean preference.

void setBoolPref(
  in string aPrefName,
  in long aValue
);

Parameters

aPrefName

The boolean preference to set the state of.

aValue

The boolean value to set the preference to.

setCharPref()

Called to set the state of an individual string preference.

void setCharPref(
  in string aPrefName,
  in string aValue
);

Parameters

aPrefName

The string preference to set.

aValue

The string value to set the preference to.

setComplexValue()

Called to set the state of an individual complex preference. A complex preference is a preference which represents an XPCOM object that can not be easily represented using a standard boolean, integer or string value.

void setComplexValue(
  in string aPrefName,
  in nsIIDRef aType,
  in nsISupports aValue
);

Parameters

aPrefName

The complex preference to set the value of.

aType

The XPCOM interface that this complex preference represents. Interfaces currently supported are:

• NsILocalFile
• NsISupportsString (UniChar)
• NsIPrefLocalizedString (Localized UniChar)
• NsIFileSpec (deprecated - to be removed eventually)

aValue

The XPCOM object from which to set the complex preference value.

setIntPref()

Called to set the state of an individual integer preference.

void setIntPref(
  in string aPrefName,
  in long aValue
);

Parameters

aPrefName

The integer preference to set the value of.

aValue

The integer value to set the preference to.

unlockPref()

Called to unlock a specific preference. Unlocking a previously locked preference allows the preference service to once again return the user set value of the preference.

void unlockPref(
  in string aPrefName
);

Parameters

aPrefName

The preference to be unlocked.

Remarks

Registering as a preference observer can open an object to potential cyclical references which will cause memory leaks. These cycles generally occur because an object both registers itself as an observer (causing the branch to hold a reference to the observer) and holds a reference to the branch object for the purpose of getting/setting preference values. There are 3 approaches which have been implemented in an attempt to avoid these situations:

1. The nsPrefBranch object supports nsISupportsWeakReference. Any consumer may hold a weak reference to it instead of a strong one.
2. The nsPrefBranch object listens for xpcom-shutdown and frees all of the objects currently in its observer list. This ensures that long lived objects (services for example) will be freed correctly.
3. The observer can request to be held as a weak reference when it is registered. This insures that shorter lived objects (say one tied to an open window) will not fall into the cyclical reference trap.

The list of registered observers may be changed during the dispatch of nsPref:changed notification. However, the observers are not guaranteed to be notified in any particular order, so you can't be sure whether the added/removed observer will be called during the notification when it is added/removed. 

It is possible to change preferences during the notification.

It is not safe to change observers during this callback in releases before Gecko 1.9. If you want a safe way to remove a preference observer, please use an nsITimer.

See also

• nsIPrefService