Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-11-26 06:11:37 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 718255 - Merge nsIPrefBranch2 with nsIPrefBranch - Part A, merge interfaces; r=bsmedberg, sr=gavin

Browse Source
This commit is contained in:
Geoff Lankow 2012-01-16 21:47:13 +13:00
parent 09f0260b72
commit dc5bc2c28a
2 changed files with 87 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
modules/libpref/public/nsIPrefBranch.idl
View File

@ -39,6 +39,8 @@
#include "nsISupports.idl"
interface nsIObserver;
/**
* The nsIPrefBranch interface is used to manipulate the preferences data. This
* object may be obtained from the preferences service (nsIPrefService) and
@ -55,7 +57,7 @@
* @see nsIPrefService
*/
[scriptable, uuid(e162bfa0-01bd-4e9f-9843-8fb2efcd6d1f)]
[scriptable, uuid(7df46a54-d8b0-448e-903c-4341a1b2499c)]
interface nsIPrefBranch : nsISupports
{
@ -345,6 +347,84 @@ interface nsIPrefBranch : nsISupports
*/
void resetBranch(in string aStartingAt);
/**
* 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".
*
* @param 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
* @param aObserver The object to be notified if the preference changes.
* @param 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|.
*
* @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
*/
void addObserver(in string aDomain, in nsIObserver aObserver,
in boolean aHoldWeak);
/**
* Remove a preference change observer.
*
* @param aDomain The preference which is being observed for changes.
* @param aObserver An observer previously registered with addObserver().
*
* @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
*/
void removeObserver(in string aDomain, in nsIObserver aObserver);
};
@ -352,5 +432,9 @@ interface nsIPrefBranch : nsISupports
#define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1"
#define NS_PREFBRANCH_CLASSNAME "Preferences Branch"
/**
* Notification sent when a preference changes.
*/
#define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed"
%}

93
modules/libpref/public/nsIPrefBranch2.idl
View File

@ -40,101 +40,12 @@
#include "nsIPrefBranch.idl"
interface nsIObserver;
/**
* nsIPrefBranch2 allows clients to observe changes to pref values.
* An empty interface to provide backwards compatibility for existing code.
*
* @see nsIPrefBranch
*/
[scriptable, uuid(d9bb54df-daac-4ce6-a70c-95d87b770cd8)]
[scriptable, uuid(8892016d-07f7-4530-b5c1-d73dfcde4a1c)]
interface nsIPrefBranch2 : nsIPrefBranch
{
/**
* 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".
*
* @param 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
* @param aObserver The object to be notified if the preference changes.
* @param 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|.
*
* @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
*/
void addObserver(in string aDomain, in nsIObserver aObserver,
in boolean aHoldWeak);
/**
* Remove a preference change observer.
*
* @param aDomain The preference which is being observed for changes.
* @param aObserver An observer previously registered with addObserver().
*
* @note
* Note that you must call removeObserver() on the same nsIPrefBranch2
* instance on which you called addObserver() in order to remove aObserver;
* otherwise, the observer will not be removed.
*
* @see nsIObserver
* @see addObserver
*/
void removeObserver(in string aDomain, in nsIObserver aObserver);
};
%{C++
/**
* Notification sent when a preference changes.
*/
#define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed"
%}