michael@0: /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface nsIObserver; michael@0: michael@0: /** michael@0: * The nsIPrefBranch interface is used to manipulate the preferences data. This michael@0: * object may be obtained from the preferences service (nsIPrefService) and michael@0: * used to get and set default and/or user preferences across the application. michael@0: * michael@0: * This object is created with a "root" value which describes the base point in michael@0: * the preferences "tree" from which this "branch" stems. Preferences are michael@0: * accessed off of this root by using just the final portion of the preference. michael@0: * For example, if this object is created with the root "browser.startup.", michael@0: * the preferences "browser.startup.page", "browser.startup.homepage", michael@0: * and "browser.startup.homepage_override" can be accessed by simply passing michael@0: * "page", "homepage", or "homepage_override" to the various Get/Set methods. michael@0: * michael@0: * @see nsIPrefService michael@0: */ michael@0: michael@0: [scriptable, uuid(55d25e49-793f-4727-a69f-de8b15f4b985)] michael@0: interface nsIPrefBranch : nsISupports michael@0: { michael@0: michael@0: /** michael@0: * Values describing the basic preference types. michael@0: * michael@0: * @see getPrefType michael@0: */ michael@0: const long PREF_INVALID = 0; michael@0: const long PREF_STRING = 32; michael@0: const long PREF_INT = 64; michael@0: const long PREF_BOOL = 128; michael@0: michael@0: /** michael@0: * Called to get the root on which this branch is based, such as michael@0: * "browser.startup." michael@0: */ michael@0: readonly attribute string root; michael@0: michael@0: /** michael@0: * Called to determine the type of a specific preference. michael@0: * michael@0: * @param aPrefName The preference to get the type of. michael@0: * michael@0: * @return long A value representing the type of the preference. This michael@0: * value will be PREF_STRING, PREF_INT, or PREF_BOOL. michael@0: */ michael@0: long getPrefType(in string aPrefName); michael@0: michael@0: /** michael@0: * Called to get the state of an individual boolean preference. michael@0: * michael@0: * @param aPrefName The boolean preference to get the state of. michael@0: * michael@0: * @return boolean The value of the requested boolean preference. michael@0: * michael@0: * @see setBoolPref michael@0: */ michael@0: boolean getBoolPref(in string aPrefName); michael@0: michael@0: /** michael@0: * Called to set the state of an individual boolean preference. michael@0: * michael@0: * @param aPrefName The boolean preference to set the state of. michael@0: * @param aValue The boolean value to set the preference to. michael@0: * michael@0: * @throws Error if setting failed or the preference has a default michael@0: value of a type other than boolean. michael@0: * michael@0: * @see getBoolPref michael@0: */ michael@0: void setBoolPref(in string aPrefName, in boolean aValue); michael@0: michael@0: /** michael@0: * Called to get the state of an individual floating-point preference. michael@0: * "Floating point" preferences are really string preferences that michael@0: * are converted to floating point numbers. michael@0: * michael@0: * @param aPrefName The floating point preference to get the state of. michael@0: * michael@0: * @return float The value of the requested floating point preference. michael@0: * michael@0: * @see setCharPref michael@0: */ michael@0: float getFloatPref(in string aPrefName); michael@0: michael@0: /** michael@0: * Called to get the state of an individual string preference. michael@0: * michael@0: * @param aPrefName The string preference to retrieve. michael@0: * michael@0: * @return string The value of the requested string preference. michael@0: * michael@0: * @see setCharPref michael@0: */ michael@0: string getCharPref(in string aPrefName); michael@0: michael@0: /** michael@0: * Called to set the state of an individual string preference. michael@0: * michael@0: * @param aPrefName The string preference to set. michael@0: * @param aValue The string value to set the preference to. michael@0: * michael@0: * @throws Error if setting failed or the preference has a default michael@0: value of a type other than string. michael@0: * michael@0: * @see getCharPref michael@0: */ michael@0: void setCharPref(in string aPrefName, in string aValue); michael@0: michael@0: /** michael@0: * Called to get the state of an individual integer preference. michael@0: * michael@0: * @param aPrefName The integer preference to get the value of. michael@0: * michael@0: * @return long The value of the requested integer preference. michael@0: * michael@0: * @see setIntPref michael@0: */ michael@0: long getIntPref(in string aPrefName); michael@0: michael@0: /** michael@0: * Called to set the state of an individual integer preference. michael@0: * michael@0: * @param aPrefName The integer preference to set the value of. michael@0: * @param aValue The integer value to set the preference to. michael@0: * michael@0: * @throws Error if setting failed or the preference has a default michael@0: value of a type other than integer. michael@0: * michael@0: * @see getIntPref michael@0: */ michael@0: void setIntPref(in string aPrefName, in long aValue); michael@0: michael@0: /** michael@0: * Called to get the state of an individual complex preference. A complex michael@0: * preference is a preference which represents an XPCOM object that can not michael@0: * be easily represented using a standard boolean, integer or string value. michael@0: * michael@0: * @param aPrefName The complex preference to get the value of. michael@0: * @param aType The XPCOM interface that this complex preference michael@0: * represents. Interfaces currently supported are: michael@0: * - nsIFile michael@0: * - nsISupportsString (UniChar) michael@0: * - nsIPrefLocalizedString (Localized UniChar) michael@0: * @param aValue The XPCOM object into which to the complex preference michael@0: * value should be retrieved. michael@0: * michael@0: * @throws Error The value does not exist or is the wrong type. michael@0: * michael@0: * @see setComplexValue michael@0: */ michael@0: void getComplexValue(in string aPrefName, in nsIIDRef aType, michael@0: [iid_is(aType), retval] out nsQIResult aValue); michael@0: michael@0: /** michael@0: * Called to set the state of an individual complex preference. A complex michael@0: * preference is a preference which represents an XPCOM object that can not michael@0: * be easily represented using a standard boolean, integer or string value. michael@0: * michael@0: * @param aPrefName The complex preference to set the value of. michael@0: * @param aType The XPCOM interface that this complex preference michael@0: * represents. Interfaces currently supported are: michael@0: * - nsIFile michael@0: * - nsISupportsString (UniChar) michael@0: * - nsIPrefLocalizedString (Localized UniChar) michael@0: * @param aValue The XPCOM object from which to set the complex preference michael@0: * value. michael@0: * michael@0: * @throws Error if setting failed or the value is the wrong type. michael@0: * michael@0: * @see getComplexValue michael@0: */ michael@0: void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue); michael@0: michael@0: /** michael@0: * Called to clear a user set value from a specific preference. This will, in michael@0: * effect, reset the value to the default value. If no default value exists michael@0: * the preference will cease to exist. michael@0: * michael@0: * @param aPrefName The preference to be cleared. michael@0: * michael@0: * @note michael@0: * This method does nothing if this object is a default branch. michael@0: */ michael@0: void clearUserPref(in string aPrefName); michael@0: michael@0: /** michael@0: * Called to lock a specific preference. Locking a preference will cause the michael@0: * preference service to always return the default value regardless of michael@0: * whether there is a user set value or not. michael@0: * michael@0: * @param aPrefName The preference to be locked. michael@0: * michael@0: * @note michael@0: * This method can be called on either a default or user branch but, in michael@0: * effect, always operates on the default branch. michael@0: * michael@0: * @throws Error The preference does not exist or an error occurred. michael@0: * michael@0: * @see unlockPref michael@0: */ michael@0: void lockPref(in string aPrefName); michael@0: michael@0: /** michael@0: * Called to check if a specific preference has a user value associated to michael@0: * it. michael@0: * michael@0: * @param aPrefName The preference to be tested. michael@0: * michael@0: * @note michael@0: * This method can be called on either a default or user branch but, in michael@0: * effect, always operates on the user branch. michael@0: * michael@0: * @note michael@0: * If a preference was manually set to a value that equals the default value, michael@0: * then the preference no longer has a user set value, i.e. it is michael@0: * considered reset to its default value. michael@0: * In particular, this method will return false for such a preference and michael@0: * the preference will not be saved to a file by nsIPrefService.savePrefFile. michael@0: * michael@0: * @return boolean true The preference has a user set value. michael@0: * false The preference only has a default value. michael@0: */ michael@0: boolean prefHasUserValue(in string aPrefName); michael@0: michael@0: /** michael@0: * Called to check if a specific preference is locked. If a preference is michael@0: * locked calling its Get method will always return the default value. michael@0: * michael@0: * @param aPrefName The preference to be tested. michael@0: * michael@0: * @note michael@0: * This method can be called on either a default or user branch but, in michael@0: * effect, always operates on the default branch. michael@0: * michael@0: * @return boolean true The preference is locked. michael@0: * false The preference is not locked. michael@0: * michael@0: * @see lockPref michael@0: * @see unlockPref michael@0: */ michael@0: boolean prefIsLocked(in string aPrefName); michael@0: michael@0: /** michael@0: * Called to unlock a specific preference. Unlocking a previously locked michael@0: * preference allows the preference service to once again return the user set michael@0: * value of the preference. michael@0: * michael@0: * @param aPrefName The preference to be unlocked. michael@0: * michael@0: * @note michael@0: * This method can be called on either a default or user branch but, in michael@0: * effect, always operates on the default branch. michael@0: * michael@0: * @throws Error The preference does not exist or an error occurred. michael@0: * michael@0: * @see lockPref michael@0: */ michael@0: void unlockPref(in string aPrefName); michael@0: michael@0: michael@0: /** michael@0: * Called to remove all of the preferences referenced by this branch. michael@0: * michael@0: * @param aStartingAt The point on the branch at which to start the deleting michael@0: * preferences. Pass in "" to remove all preferences michael@0: * referenced by this branch. michael@0: * michael@0: * @note michael@0: * This method can be called on either a default or user branch but, in michael@0: * effect, always operates on both. michael@0: * michael@0: * @throws Error The preference(s) do not exist or an error occurred. michael@0: */ michael@0: void deleteBranch(in string aStartingAt); michael@0: michael@0: /** michael@0: * Returns an array of strings representing the child preferences of the michael@0: * root of this branch. michael@0: * michael@0: * @param aStartingAt The point on the branch at which to start enumerating michael@0: * the child preferences. Pass in "" to enumerate all michael@0: * preferences referenced by this branch. michael@0: * @param aCount Receives the number of elements in the array. michael@0: * @param aChildArray Receives the array of child preferences. michael@0: * michael@0: * @note michael@0: * This method can be called on either a default or user branch but, in michael@0: * effect, always operates on both. michael@0: * michael@0: * @throws Error The preference(s) do not exist or an error occurred. michael@0: */ michael@0: void getChildList(in string aStartingAt, michael@0: [optional] out unsigned long aCount, michael@0: [array, size_is(aCount), retval] out string aChildArray); michael@0: michael@0: /** michael@0: * Called to reset all of the preferences referenced by this branch to their michael@0: * default values. michael@0: * michael@0: * @param aStartingAt The point on the branch at which to start the resetting michael@0: * preferences to their default values. Pass in "" to michael@0: * reset all preferences referenced by this branch. michael@0: * michael@0: * @note michael@0: * This method can be called on either a default or user branch but, in michael@0: * effect, always operates on the user branch. michael@0: * michael@0: * @throws Error The preference(s) do not exist or an error occurred. michael@0: */ michael@0: void resetBranch(in string aStartingAt); michael@0: michael@0: /** michael@0: * Add a preference change observer. On preference changes, the following michael@0: * arguments will be passed to the nsIObserver.observe() method: michael@0: * aSubject - The nsIPrefBranch object (this) michael@0: * aTopic - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID michael@0: * aData - The name of the preference which has changed, relative to michael@0: * the |root| of the aSubject branch. michael@0: * michael@0: * aSubject.get*Pref(aData) will get the new value of the modified michael@0: * preference. For example, if your observer is registered with michael@0: * addObserver("bar.", ...) on a branch with root "foo.", modifying michael@0: * the preference "foo.bar.baz" will trigger the observer, and aData michael@0: * parameter will be "bar.baz". michael@0: * michael@0: * @param aDomain The preference on which to listen for changes. This can michael@0: * be the name of an entire branch to observe. michael@0: * e.g. Holding the "root" prefbranch and calling michael@0: * addObserver("foo.bar.", ...) will observe changes to michael@0: * foo.bar.baz and foo.bar.bzip michael@0: * @param aObserver The object to be notified if the preference changes. michael@0: * @param aHoldWeak true Hold a weak reference to |aObserver|. The object michael@0: * must implement the nsISupportsWeakReference michael@0: * interface or this will fail. michael@0: * false Hold a strong reference to |aObserver|. michael@0: * michael@0: * @note michael@0: * Registering as a preference observer can open an object to potential michael@0: * cyclical references which will cause memory leaks. These cycles generally michael@0: * occur because an object both registers itself as an observer (causing the michael@0: * branch to hold a reference to the observer) and holds a reference to the michael@0: * branch object for the purpose of getting/setting preference values. There michael@0: * are 3 approaches which have been implemented in an attempt to avoid these michael@0: * situations. michael@0: * 1) The nsPrefBranch object supports nsISupportsWeakReference. Any consumer michael@0: * may hold a weak reference to it instead of a strong one. michael@0: * 2) The nsPrefBranch object listens for xpcom-shutdown and frees all of the michael@0: * objects currently in its observer list. This ensures that long lived michael@0: * objects (services for example) will be freed correctly. michael@0: * 3) The observer can request to be held as a weak reference when it is michael@0: * registered. This insures that shorter lived objects (say one tied to an michael@0: * open window) will not fall into the cyclical reference trap. michael@0: * michael@0: * @note michael@0: * The list of registered observers may be changed during the dispatch of michael@0: * nsPref:changed notification. However, the observers are not guaranteed michael@0: * to be notified in any particular order, so you can't be sure whether the michael@0: * added/removed observer will be called during the notification when it michael@0: * is added/removed. michael@0: * michael@0: * @note michael@0: * It is possible to change preferences during the notification. michael@0: * michael@0: * @note michael@0: * It is not safe to change observers during this callback in Gecko michael@0: * releases before 1.9. If you want a safe way to remove a pref observer, michael@0: * please use an nsITimer. michael@0: * michael@0: * @see nsIObserver michael@0: * @see removeObserver michael@0: */ michael@0: void addObserver(in string aDomain, in nsIObserver aObserver, michael@0: in boolean aHoldWeak); michael@0: michael@0: /** michael@0: * Remove a preference change observer. michael@0: * michael@0: * @param aDomain The preference which is being observed for changes. michael@0: * @param aObserver An observer previously registered with addObserver(). michael@0: * michael@0: * @note michael@0: * Note that you must call removeObserver() on the same nsIPrefBranch michael@0: * instance on which you called addObserver() in order to remove aObserver; michael@0: * otherwise, the observer will not be removed. michael@0: * michael@0: * @see nsIObserver michael@0: * @see addObserver michael@0: */ michael@0: void removeObserver(in string aDomain, in nsIObserver aObserver); michael@0: }; michael@0: michael@0: michael@0: %{C++ michael@0: michael@0: #define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1" michael@0: /** michael@0: * Notification sent when a preference changes. michael@0: */ michael@0: #define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed" michael@0: michael@0: %}