/modules/libpref/public/nsIPrefBranch.idl

http://github.com/zpao/v8monkey · IDL · 440 lines · 39 code · 30 blank · 371 comment · 0 complexity · 3c6c0457fcaa20c3e7addc152c1ecbc2 MD5 · raw file

  1. /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3. * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4. *
  5. * The contents of this file are subject to the Mozilla Public License Version
  6. * 1.1 (the "License"); you may not use this file except in compliance with
  7. * the License. You may obtain a copy of the License at
  8. * http://www.mozilla.org/MPL/
  9. *
  10. * Software distributed under the License is distributed on an "AS IS" basis,
  11. * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12. * for the specific language governing rights and limitations under the
  13. * License.
  14. *
  15. * The Original Code is Mozilla Communicator client code.
  16. *
  17. * The Initial Developer of the Original Code is
  18. * Netscape Communications Corporation.
  19. * Portions created by the Initial Developer are Copyright (C) 1998
  20. * the Initial Developer. All Rights Reserved.
  21. *
  22. * Contributor(s):
  23. * Alec Flett <alecf@netscape.com>
  24. * Brian Nesse <bnesse@netscape.com>
  25. *
  26. * Alternatively, the contents of this file may be used under the terms of
  27. * either the GNU General Public License Version 2 or later (the "GPL"), or
  28. * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29. * in which case the provisions of the GPL or the LGPL are applicable instead
  30. * of those above. If you wish to allow use of your version of this file only
  31. * under the terms of either the GPL or the LGPL, and not to allow others to
  32. * use your version of this file under the terms of the MPL, indicate your
  33. * decision by deleting the provisions above and replace them with the notice
  34. * and other provisions required by the GPL or the LGPL. If you do not delete
  35. * the provisions above, a recipient may use your version of this file under
  36. * the terms of any one of the MPL, the GPL or the LGPL.
  37. *
  38. * ***** END LICENSE BLOCK ***** */
  39. #include "nsISupports.idl"
  40. interface nsIObserver;
  41. /**
  42. * The nsIPrefBranch interface is used to manipulate the preferences data. This
  43. * object may be obtained from the preferences service (nsIPrefService) and
  44. * used to get and set default and/or user preferences across the application.
  45. *
  46. * This object is created with a "root" value which describes the base point in
  47. * the preferences "tree" from which this "branch" stems. Preferences are
  48. * accessed off of this root by using just the final portion of the preference.
  49. * For example, if this object is created with the root "browser.startup.",
  50. * the preferences "browser.startup.page", "browser.startup.homepage",
  51. * and "browser.startup.homepage_override" can be accessed by simply passing
  52. * "page", "homepage", or "homepage_override" to the various Get/Set methods.
  53. *
  54. * @see nsIPrefService
  55. */
  56. [scriptable, uuid(7df46a54-d8b0-448e-903c-4341a1b2499c)]
  57. interface nsIPrefBranch : nsISupports
  58. {
  59. /**
  60. * Values describing the basic preference types.
  61. *
  62. * @see getPrefType
  63. */
  64. const long PREF_INVALID = 0;
  65. const long PREF_STRING = 32;
  66. const long PREF_INT = 64;
  67. const long PREF_BOOL = 128;
  68. /**
  69. * Called to get the root on which this branch is based, such as
  70. * "browser.startup."
  71. */
  72. readonly attribute string root;
  73. /**
  74. * Called to determine the type of a specific preference.
  75. *
  76. * @param aPrefName The preference to get the type of.
  77. *
  78. * @return long A value representing the type of the preference. This
  79. * value will be PREF_STRING, PREF_INT, or PREF_BOOL.
  80. */
  81. long getPrefType(in string aPrefName);
  82. /**
  83. * Called to get the state of an individual boolean preference.
  84. *
  85. * @param aPrefName The boolean preference to get the state of.
  86. *
  87. * @return boolean The value of the requested boolean preference.
  88. *
  89. * @see setBoolPref
  90. */
  91. boolean getBoolPref(in string aPrefName);
  92. /**
  93. * Called to set the state of an individual boolean preference.
  94. *
  95. * @param aPrefName The boolean preference to set the state of.
  96. * @param aValue The boolean value to set the preference to.
  97. *
  98. * @return NS_OK The value was successfully set.
  99. * @return Other The value was not set or is the wrong type.
  100. *
  101. * @see getBoolPref
  102. */
  103. void setBoolPref(in string aPrefName, in boolean aValue);
  104. /**
  105. * Called to get the state of an individual string preference.
  106. *
  107. * @param aPrefName The string preference to retrieve.
  108. *
  109. * @return string The value of the requested string preference.
  110. *
  111. * @see setCharPref
  112. */
  113. string getCharPref(in string aPrefName);
  114. /**
  115. * Called to set the state of an individual string preference.
  116. *
  117. * @param aPrefName The string preference to set.
  118. * @param aValue The string value to set the preference to.
  119. *
  120. * @return NS_OK The value was successfully set.
  121. * @return Other The value was not set or is the wrong type.
  122. *
  123. * @see getCharPref
  124. */
  125. void setCharPref(in string aPrefName, in string aValue);
  126. /**
  127. * Called to get the state of an individual integer preference.
  128. *
  129. * @param aPrefName The integer preference to get the value of.
  130. *
  131. * @return long The value of the requested integer preference.
  132. *
  133. * @see setIntPref
  134. */
  135. long getIntPref(in string aPrefName);
  136. /**
  137. * Called to set the state of an individual integer preference.
  138. *
  139. * @param aPrefName The integer preference to set the value of.
  140. * @param aValue The integer value to set the preference to.
  141. *
  142. * @return NS_OK The value was successfully set.
  143. * @return Other The value was not set or is the wrong type.
  144. *
  145. * @see getIntPref
  146. */
  147. void setIntPref(in string aPrefName, in long aValue);
  148. /**
  149. * Called to get the state of an individual complex preference. A complex
  150. * preference is a preference which represents an XPCOM object that can not
  151. * be easily represented using a standard boolean, integer or string value.
  152. *
  153. * @param aPrefName The complex preference to get the value of.
  154. * @param aType The XPCOM interface that this complex preference
  155. * represents. Interfaces currently supported are:
  156. * - nsILocalFile
  157. * - nsISupportsString (UniChar)
  158. * - nsIPrefLocalizedString (Localized UniChar)
  159. * @param aValue The XPCOM object into which to the complex preference
  160. * value should be retrieved.
  161. *
  162. * @return NS_OK The value was successfully retrieved.
  163. * @return Other The value does not exist or is the wrong type.
  164. *
  165. * @see setComplexValue
  166. */
  167. void getComplexValue(in string aPrefName, in nsIIDRef aType,
  168. [iid_is(aType), retval] out nsQIResult aValue);
  169. /**
  170. * Called to set the state of an individual complex preference. A complex
  171. * preference is a preference which represents an XPCOM object that can not
  172. * be easily represented using a standard boolean, integer or string value.
  173. *
  174. * @param aPrefName The complex preference to set the value of.
  175. * @param aType The XPCOM interface that this complex preference
  176. * represents. Interfaces currently supported are:
  177. * - nsILocalFile
  178. * - nsISupportsString (UniChar)
  179. * - nsIPrefLocalizedString (Localized UniChar)
  180. * @param aValue The XPCOM object from which to set the complex preference
  181. * value.
  182. *
  183. * @return NS_OK The value was successfully set.
  184. * @return Other The value was not set or is the wrong type.
  185. *
  186. * @see getComplexValue
  187. */
  188. void setComplexValue(in string aPrefName, in nsIIDRef aType, in nsISupports aValue);
  189. /**
  190. * Called to clear a user set value from a specific preference. This will, in
  191. * effect, reset the value to the default value. If no default value exists
  192. * the preference will cease to exist.
  193. *
  194. * @param aPrefName The preference to be cleared.
  195. *
  196. * @note
  197. * This method does nothing if this object is a default branch.
  198. *
  199. * @return NS_OK The user preference was successfully cleared.
  200. */
  201. void clearUserPref(in string aPrefName);
  202. /**
  203. * Called to lock a specific preference. Locking a preference will cause the
  204. * preference service to always return the default value regardless of
  205. * whether there is a user set value or not.
  206. *
  207. * @param aPrefName The preference to be locked.
  208. *
  209. * @note
  210. * This method can be called on either a default or user branch but, in
  211. * effect, always operates on the default branch.
  212. *
  213. * @return NS_OK The preference was successfully locked.
  214. * @return Other The preference does not exist or an error occurred.
  215. *
  216. * @see unlockPref
  217. */
  218. void lockPref(in string aPrefName);
  219. /**
  220. * Called to check if a specific preference has a user value associated to
  221. * it.
  222. *
  223. * @param aPrefName The preference to be tested.
  224. *
  225. * @note
  226. * This method can be called on either a default or user branch but, in
  227. * effect, always operates on the user branch.
  228. *
  229. * @note
  230. * If a preference was manually set to a value that equals the default value,
  231. * then the preference no longer has a user set value, i.e. it is
  232. * considered reset to its default value.
  233. * In particular, this method will return false for such a preference and
  234. * the preference will not be saved to a file by nsIPrefService.savePrefFile.
  235. *
  236. * @return boolean true The preference has a user set value.
  237. * false The preference only has a default value.
  238. */
  239. boolean prefHasUserValue(in string aPrefName);
  240. /**
  241. * Called to check if a specific preference is locked. If a preference is
  242. * locked calling its Get method will always return the default value.
  243. *
  244. * @param aPrefName The preference to be tested.
  245. *
  246. * @note
  247. * This method can be called on either a default or user branch but, in
  248. * effect, always operates on the default branch.
  249. *
  250. * @return boolean true The preference is locked.
  251. * false The preference is not locked.
  252. *
  253. * @see lockPref
  254. * @see unlockPref
  255. */
  256. boolean prefIsLocked(in string aPrefName);
  257. /**
  258. * Called to unlock a specific preference. Unlocking a previously locked
  259. * preference allows the preference service to once again return the user set
  260. * value of the preference.
  261. *
  262. * @param aPrefName The preference to be unlocked.
  263. *
  264. * @note
  265. * This method can be called on either a default or user branch but, in
  266. * effect, always operates on the default branch.
  267. *
  268. * @return NS_OK The preference was successfully unlocked.
  269. * @return Other The preference does not exist or an error occurred.
  270. *
  271. * @see lockPref
  272. */
  273. void unlockPref(in string aPrefName);
  274. /**
  275. * Called to remove all of the preferences referenced by this branch.
  276. *
  277. * @param aStartingAt The point on the branch at which to start the deleting
  278. * preferences. Pass in "" to remove all preferences
  279. * referenced by this branch.
  280. *
  281. * @note
  282. * This method can be called on either a default or user branch but, in
  283. * effect, always operates on both.
  284. *
  285. * @return NS_OK The preference(s) were successfully removed.
  286. * @return Other The preference(s) do not exist or an error occurred.
  287. */
  288. void deleteBranch(in string aStartingAt);
  289. /**
  290. * Returns an array of strings representing the child preferences of the
  291. * root of this branch.
  292. *
  293. * @param aStartingAt The point on the branch at which to start enumerating
  294. * the child preferences. Pass in "" to enumerate all
  295. * preferences referenced by this branch.
  296. * @param aCount Receives the number of elements in the array.
  297. * @param aChildArray Receives the array of child preferences.
  298. *
  299. * @note
  300. * This method can be called on either a default or user branch but, in
  301. * effect, always operates on both.
  302. *
  303. * @return NS_OK The preference list was successfully retrieved.
  304. * @return Other The preference(s) do not exist or an error occurred.
  305. */
  306. void getChildList(in string aStartingAt,
  307. [optional] out unsigned long aCount,
  308. [array, size_is(aCount), retval] out string aChildArray);
  309. /**
  310. * Called to reset all of the preferences referenced by this branch to their
  311. * default values.
  312. *
  313. * @param aStartingAt The point on the branch at which to start the resetting
  314. * preferences to their default values. Pass in "" to
  315. * reset all preferences referenced by this branch.
  316. *
  317. * @note
  318. * This method can be called on either a default or user branch but, in
  319. * effect, always operates on the user branch.
  320. *
  321. * @return NS_OK The preference(s) were successfully reset.
  322. * @return Other The preference(s) do not exist or an error occurred.
  323. */
  324. void resetBranch(in string aStartingAt);
  325. /**
  326. * Add a preference change observer. On preference changes, the following
  327. * arguments will be passed to the nsIObserver.observe() method:
  328. * aSubject - The nsIPrefBranch object (this)
  329. * aTopic - The string defined by NS_PREFBRANCH_PREFCHANGE_TOPIC_ID
  330. * aData - The name of the preference which has changed, relative to
  331. * the |root| of the aSubject branch.
  332. *
  333. * aSubject.get*Pref(aData) will get the new value of the modified
  334. * preference. For example, if your observer is registered with
  335. * addObserver("bar.", ...) on a branch with root "foo.", modifying
  336. * the preference "foo.bar.baz" will trigger the observer, and aData
  337. * parameter will be "bar.baz".
  338. *
  339. * @param aDomain The preference on which to listen for changes. This can
  340. * be the name of an entire branch to observe.
  341. * e.g. Holding the "root" prefbranch and calling
  342. * addObserver("foo.bar.", ...) will observe changes to
  343. * foo.bar.baz and foo.bar.bzip
  344. * @param aObserver The object to be notified if the preference changes.
  345. * @param aHoldWeak true Hold a weak reference to |aObserver|. The object
  346. * must implement the nsISupportsWeakReference
  347. * interface or this will fail.
  348. * false Hold a strong reference to |aObserver|.
  349. *
  350. * @note
  351. * Registering as a preference observer can open an object to potential
  352. * cyclical references which will cause memory leaks. These cycles generally
  353. * occur because an object both registers itself as an observer (causing the
  354. * branch to hold a reference to the observer) and holds a reference to the
  355. * branch object for the purpose of getting/setting preference values. There
  356. * are 3 approaches which have been implemented in an attempt to avoid these
  357. * situations.
  358. * 1) The nsPrefBranch object supports nsISupportsWeakReference. Any consumer
  359. * may hold a weak reference to it instead of a strong one.
  360. * 2) The nsPrefBranch object listens for xpcom-shutdown and frees all of the
  361. * objects currently in its observer list. This ensures that long lived
  362. * objects (services for example) will be freed correctly.
  363. * 3) The observer can request to be held as a weak reference when it is
  364. * registered. This insures that shorter lived objects (say one tied to an
  365. * open window) will not fall into the cyclical reference trap.
  366. *
  367. * @note
  368. * The list of registered observers may be changed during the dispatch of
  369. * nsPref:changed notification. However, the observers are not guaranteed
  370. * to be notified in any particular order, so you can't be sure whether the
  371. * added/removed observer will be called during the notification when it
  372. * is added/removed.
  373. *
  374. * @note
  375. * It is possible to change preferences during the notification.
  376. *
  377. * @note
  378. * It is not safe to change observers during this callback in Gecko
  379. * releases before 1.9. If you want a safe way to remove a pref observer,
  380. * please use an nsITimer.
  381. *
  382. * @see nsIObserver
  383. * @see removeObserver
  384. */
  385. void addObserver(in string aDomain, in nsIObserver aObserver,
  386. in boolean aHoldWeak);
  387. /**
  388. * Remove a preference change observer.
  389. *
  390. * @param aDomain The preference which is being observed for changes.
  391. * @param aObserver An observer previously registered with addObserver().
  392. *
  393. * @note
  394. * Note that you must call removeObserver() on the same nsIPrefBranch
  395. * instance on which you called addObserver() in order to remove aObserver;
  396. * otherwise, the observer will not be removed.
  397. *
  398. * @see nsIObserver
  399. * @see addObserver
  400. */
  401. void removeObserver(in string aDomain, in nsIObserver aObserver);
  402. };
  403. %{C++
  404. #define NS_PREFBRANCH_CONTRACTID "@mozilla.org/preferencesbranch;1"
  405. #define NS_PREFBRANCH_CLASSNAME "Preferences Branch"
  406. /**
  407. * Notification sent when a preference changes.
  408. */
  409. #define NS_PREFBRANCH_PREFCHANGE_TOPIC_ID "nsPref:changed"
  410. %}