Readonly rootCalled to get the root on which this branch is based, such as "browser.startup."
Optional aInstancePtr: objectA run time mechanism for interface discovery.
NS_OK if the interface is supported by the associated instance, NS_NOINTERFACE if it is not.
aInstancePtr must not be null.
[in] A requested interface IID
[out] A pointer to an interface pointer to receive the result.
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".
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.
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 Gecko releases before 1.9. If you want a safe way to remove a pref observer, please use an nsITimer.
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
The object to be notified if the preference changes.
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|.
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.
This method does nothing if this object is a default branch.
The preference to be cleared.
Called to remove all of the preferences referenced by this branch.
This method can be called on either a default or user branch but, in effect, always operates on both.
Error The preference(s) do not exist or an error occurred.
The point on the branch at which to start the deleting preferences. Pass in "" to remove all preferences referenced by this branch.
Called to get the state of an individual boolean preference.
boolean The value of the requested boolean preference.
setBoolPref
The boolean preference to get the state of.
The value to return if the preference is not set.
Called to get the state of an individual ascii string preference.
ACString The value of the requested string preference.
setCharPref
The string preference to retrieve.
The string to return if the preference is not set.
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.
Error The value does not exist or is the wrong type.
setComplexValue
The complex preference to get the value of.
The XPCOM interface that this complex preference represents. Interfaces currently supported are:
The XPCOM object into which to the complex preference value should be retrieved.
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.
float The value of the requested floating point preference.
setCharPref
The floating point preference to get the state of.
The value to return if the preference is not set.
Called to get the state of an individual integer preference.
long The value of the requested integer preference.
setIntPref
The integer preference to get the value of.
The value to return if the preference is not set.
Called to get the state of an individual unicode string preference.
AUTF8String The value of the requested string preference.
setStringPref
The string preference to retrieve.
The string to return if the preference is not set.
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.
This method can be called on either a default or user branch but, in effect, always operates on the default branch.
Error The preference does not exist or an error occurred.
unlockPref
The preference to be locked.
Called to check if a specific preference has a default value associated to it.
This method can be called on either a default or user branch but, in effect, always operates on the user branch.
This method can be used to distinguish between a built-in preference and a user-added preference.
boolean true The preference has a default value. false The preference only has a user value.
The preference to be tested.
Called to check if a specific preference has a user value associated to it.
This method can be called on either a default or user branch but, in effect, always operates on the user branch.
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.
boolean true The preference has a user set value. false The preference only has a default value.
The preference to be tested.
Called to check if a specific preference is locked. If a preference is locked calling its Get method will always return the default value.
This method can be called on either a default or user branch but, in effect, always operates on the default branch.
boolean true The preference is locked. false The preference is not locked.
The preference to be tested.
Called to check if a specific preference has been sanitized. If a preference is sanitized, any user value the preference may have will not be present in a sub-process. A preference is never sanitized in the parent process; it is only marked as sanitized when it is converted to a dom::Pref for serialization to a child process.
This method can be called on either a default or user branch but it makes no difference.
boolean true The preference is sanitized. false The preference is not sanitized.
The preference to be tested.
Remove a preference change observer.
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.
The preference which is being observed for changes.
An observer previously registered with addObserver().
Called to reset all of the preferences referenced by this branch to their default values.
This method can be called on either a default or user branch but, in effect, always operates on the user branch.
Error The preference(s) do not exist or an error occurred.
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.
Called to set the state of an individual boolean preference.
Error if setting failed or the preference has a default value of a type other than boolean.
getBoolPref
The boolean preference to set the state of.
The boolean value to set the preference to.
Called to set the state of an individual ascii string preference.
Error if setting failed or the preference has a default value of a type other than string.
getCharPref
The string preference to set.
The string value to set the preference to.
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.
Error if setting failed or the value is the wrong type.
getComplexValue
The complex preference to set the value of.
The XPCOM interface that this complex preference represents. Interfaces currently supported are:
The XPCOM object from which to set the complex preference value.
Called to set the state of an individual integer preference.
Error if setting failed or the preference has a default value of a type other than integer.
getIntPref
The integer preference to set the value of.
The integer value to set the preference to.
Called to set the state of an individual unicode string preference.
Error if setting failed or the preference has a default value of a type other than string.
getStringPref
The string preference to set.
The string value to set the preference to.
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.
This method can be called on either a default or user branch but, in effect, always operates on the default branch.
Error The preference does not exist or an error occurred.
lockPref
The preference to be unlocked.
Generated using TypeDoc
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