In Gecko 13 this Interface was merged into the nsIPrefBranch
interface.
nsIPrefBranch
Last changed in Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)Method overview
void addObserver(in string aDomain, in nsIObserver aObserver, in boolean aHoldWeak); |
void removeObserver(in string aDomain, in nsIObserver aObserver); |
Methods
addObserver()
Add 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 callingaddObserver("foo.bar.", ...)
will observe changes tofoo.bar.baz
andfoo.bar.bzip
. -
aObserver
- The object to be notified if the preference changes.
-
aHoldWeak
-
true
holds a weak reference toaObserver
. The object must implement thensISupportsWeakReference
interface or this will fail.false
holds a strong reference toaObserver
.
removeObserver()
Remove a preference change observer.
removeObserver
method on the same nsIPrefBranch2 instance on which you called addObserver()
method in order to remove aObserver
; otherwise, the observer will not be removed.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.
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:
- The nsPrefBranch object supports
nsISupportsWeakReference
. Any consumer may hold a weak reference to it instead of a strong one. - 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.
- 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
.