In Gecko 13 this Interface was merged into the
Add a preference change observer. On preference changes, the following arguments will be passed to
aSubject - The
nsIPrefBranch object (this).
aTopic - The string defined by
aData - The name of the preference which has changed, relative to the "root" of the
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
void addObserver( in string aDomain, in nsIObserver aObserver, in boolean aHoldWeak );
The preference on which to listen for changes. This can be the name of an entire branch to observe. For example holding the "root"
addObserver("foo.bar.", ...)will observe changes to
- The object to be notified if the preference changes.
trueholds a weak reference to
aObserver. The object must implement the
nsISupportsWeakReferenceinterface or this will fail.
falseholds a strong reference to
Remove a preference change observer.
removeObservermethod 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 );
- The preference which is being observed for changes.
- An observer previously registered with addObserver.
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