The nsIPrefBranch interface is used to manipulate the preferences data. This
object may be obtained from the preferences service (nsIPrefService) and
used to get and set default and/or user preferences across the application.
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.
@see nsIPrefService
Called to determine the type of a specific preference.
| aPrefName | The preference to get the type of. |
| long A value representing the type of the preference. This value will be PREF_STRING, PREF_INT, or PREF_BOOL. |
Called to get the state of an individual boolean preference.
@see setBoolPref
| aPrefName | The boolean preference to get the state of. |
| boolean The value of the requested boolean preference. |
Called to set the state of an individual boolean preference.
@throws Error if setting failed or the preference has a default
value of a type other than boolean.
@see getBoolPref
| aPrefName | The boolean preference to set the state of. |
| aValue | The boolean value to set the preference to. |
Called to get the state of an individual floating-point preference.
“Floating point” preferences are really string preferences that
are converted to floating point numbers.
@see setCharPref
| aPrefName | The floating point preference to get the state of. |
| float The value of the requested floating point preference. |
Called to get the state of an individual string preference.
@see setCharPref
| aPrefName | The string preference to retrieve. |
| string The value of the requested string preference. |
Called to set the state of an individual string preference.
@throws Error if setting failed or the preference has a default
value of a type other than string.
@see getCharPref
| aPrefName | The string preference to set. |
| aValue | The string value to set the preference to. |
Called to get the state of an individual integer preference.
@see setIntPref
| aPrefName | The integer preference to get the value of. |
| long The value of the requested integer preference. |
Called to set the state of an individual integer preference.
@throws Error if setting failed or the preference has a default
value of a type other than integer.
@see getIntPref
| aPrefName | The integer preference to set the value of. |
| aValue | The integer value to set the preference to. |
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.
@throws Error The value does not exist or is the wrong type.
@see setComplexValue
| aPrefName | The complex preference to get the value of. |
| aType | The XPCOM interface that this complex preference represents. Interfaces currently supported are: - nsIFile - nsISupportsString (UniChar) - nsIPrefLocalizedString (Localized UniChar) |
| aValue | The XPCOM object into which to the complex preference value should be retrieved. |
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.
@throws Error if setting failed or the value is the wrong type.
@see getComplexValue
| aPrefName | The complex preference to set the value of. |
| aType | The XPCOM interface that this complex preference represents. Interfaces currently supported are: - nsIFile - nsISupportsString (UniChar) - nsIPrefLocalizedString (Localized UniChar) |
| aValue | The XPCOM object from which to set the complex preference value. |
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.
@note
This method does nothing if this object is a default branch.
| aPrefName | The preference to be cleared. |
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.
@note
This method can be called on either a default or user branch but, in
effect, always operates on the default branch.
@throws Error The preference does not exist or an error occurred.
@see unlockPref
| aPrefName | The preference to be locked. |
Called to check if a specific preference has a user value associated to
it.
@note
This method can be called on either a default or user branch but, in
effect, always operates on the user branch.
@note
If a preference was manually set to a value that equals the default value,
then the preference no longer has a user set value, i.e. it is
considered reset to its default value.
In particular, this method will return false for such a preference and
the preference will not be saved to a file by nsIPrefService.savePrefFile.
| aPrefName | The preference to be tested. |
| boolean true The preference has a user set value. false The preference only has a default value. |
Called to check if a specific preference is locked. If a preference is
locked calling its Get method will always return the default value.
@note
This method can be called on either a default or user branch but, in
effect, always operates on the default branch.
@see lockPref
@see unlockPref
| aPrefName | The preference to be tested. |
| boolean true The preference is locked. false The preference is not locked. |
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.
@note
This method can be called on either a default or user branch but, in
effect, always operates on the default branch.
@throws Error The preference does not exist or an error occurred.
@see lockPref
| aPrefName | The preference to be unlocked. |
Called to remove all of the preferences referenced by this branch.
@note
This method can be called on either a default or user branch but, in
effect, always operates on both.
@throws Error The preference(s) do not exist or an error occurred.
| aStartingAt | The point on the branch at which to start the deleting preferences. Pass in "" to remove all preferences referenced by this branch. |
Returns an array of strings representing the child preferences of the
root of this branch.
@note
This method can be called on either a default or user branch but, in
effect, always operates on both.
@throws Error The preference(s) do not exist or an error occurred.
| 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 | Receives the number of elements in the array. |
| aChildArray | Receives the array of child preferences. |
Called to reset all of the preferences referenced by this branch to their
default values.
@note
This method can be called on either a default or user branch but, in
effect, always operates on the user branch.
@throws Error The preference(s) do not exist or an error occurred.
| 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. |
Add a preference change observer. On preference changes, the following
arguments will be passed to the nsIObserver.observe() method:
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”.
@note
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.
@note
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.
@note
It is possible to change preferences during the notification.
@note
It is not safe to change observers during this callback in Gecko
releases before 1.9. If you want a safe way to remove a pref observer,
please use an nsITimer.
@see nsIObserver
@see removeObserver
| aDomain | The preference on which to listen for changes. This can be the name of an entire branch to observe. e.g. 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. |
| aHoldWeak | true Hold a weak reference to |aObserver|. The object must implement the nsISupportsWeakReference interface or this will fail. false Hold a strong reference to |aObserver|. |
Remove a preference change observer.
@note
Note that you must call removeObserver() on the same nsIPrefBranch
instance on which you called addObserver() in order to remove aObserver;
otherwise, the observer will not be removed.
@see nsIObserver
@see addObserver
| aDomain | The preference which is being observed for changes. |
| aObserver | An observer previously registered with addObserver(). |
Called to get the root on which this branch is based, such as
“browser.startup.”
Values describing the basic preference types.
@see getPrefType