Bug 718255 - Merge nsIPrefBranch2 with nsIPrefBranch - Part A, merge interfaces; r=bsmedberg, sr=gavin
authorGeoff Lankow <geoff@darktrojan.net>
Mon, 16 Jan 2012 21:47:13 +1300
changeset 86756 e933d31eb6965196994df3c2298dd2c09224980c
parent 86755 5c8d7e3de1b8f510fbbae899ed56ca3012326e65
child 86757 910cc1ad28039d8970ac40ab2bf402b26c5af9e4
push id6022
push usergeoff@darktrojan.net
push dateMon, 13 Feb 2012 23:44:11 +0000
treeherdermozilla-inbound@04ac18d14436 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersbsmedberg, gavin
bugs718255
milestone13.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 718255 - Merge nsIPrefBranch2 with nsIPrefBranch - Part A, merge interfaces; r=bsmedberg, sr=gavin
modules/libpref/public/nsIPrefBranch.idl
modules/libpref/public/nsIPrefBranch2.idl
--- a/modules/libpref/public/nsIPrefBranch.idl
+++ b/modules/libpref/public/nsIPrefBranch.idl
@@ -34,33 +34,35 @@
  * and other provisions required by the GPL or the LGPL. If you do not delete
  * the provisions above, a recipient may use your version of this file under
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
 
 #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
  * 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
  */
 
-[scriptable, uuid(e162bfa0-01bd-4e9f-9843-8fb2efcd6d1f)]
+[scriptable, uuid(7df46a54-d8b0-448e-903c-4341a1b2499c)]
 interface nsIPrefBranch : nsISupports
 {
 
   /**
    * Values describing the basic preference types.
    *
    * @see getPrefType
    */
@@ -340,17 +342,99 @@ interface nsIPrefBranch : nsISupports
    * This method can be called on either a default or user branch but, in
    * effect, always operates on the user branch.
    *
    * @return NS_OK The preference(s) were successfully reset.
    * @return Other The preference(s) do not exist or an error occurred.
    */
   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);
 };
 
 
 %{C++
 
 #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"
 
 %}
--- a/modules/libpref/public/nsIPrefBranch2.idl
+++ b/modules/libpref/public/nsIPrefBranch2.idl
@@ -35,106 +35,17 @@
  * and other provisions required by the GPL or the LGPL. If you do not delete
  * the provisions above, a recipient may use your version of this file under
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
 
 #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"
-
-%}