canmove, Confirmed users
2,056
edits
Labs/JS Modules: Difference between revisions
document the observe/ignore API of the Preferences module
(document new API methods and changes) |
(document the observe/ignore API of the Preferences module) |
||
| Line 112: | Line 112: | ||
Unregister observers by calling <code>Observers.remove</code> with the same parameters you passed to <code>Observers.add</code>: | Unregister observers by calling <code>Observers.remove</code> with the same parameters you passed to <code>Observers.add</code>: | ||
Observers.remove(" | Observers.remove("something", someFunction); | ||
Observers.remove(" | Observers.remove("something", someObject.onSomething, someObject); | ||
Observers.remove(" | Observers.remove("something", someObject); | ||
Note: the Observers module wraps observers in a wrapper that implements [http://mxr.mozilla.org/mozilla/source/xpcom/base/nsIWeakReference.idl?mark=71-94#71 nsISupportsWeakReference], so you don't necessarily have to remove your observers to avoid leaking memory. Nevertheless, it is good practice to do so anyway. | Note: the Observers module wraps observers in a wrapper that implements [http://mxr.mozilla.org/mozilla/source/xpcom/base/nsIWeakReference.idl?mark=71-94#71 nsISupportsWeakReference], so you don't necessarily have to remove your observers to avoid leaking memory. Nevertheless, it is good practice to do so anyway. | ||
| Line 164: | Line 164: | ||
== Preferences == | == Preferences == | ||
=== Getting & Setting === | |||
The [http://hg.mozdev.org/jsmodules/file/tip/Preferences.js Preferences module] provides an API for accessing application preferences. Getting and setting prefs is easy: | The [http://hg.mozdev.org/jsmodules/file/tip/Preferences.js Preferences module] provides an API for accessing application preferences. Getting and setting prefs is easy: | ||
| Line 194: | Line 196: | ||
testBranch.set({ foo: 1, bar: "awesome", baz: true }); | testBranch.set({ foo: 1, bar: "awesome", baz: true }); | ||
=== Resetting & Checking === | |||
You can also reset preferences (i.e. remove the user-set value) and check if they're set: | You can also reset preferences (i.e. remove the user-set value) and check if they're set: | ||
| Line 206: | Line 210: | ||
let hasFoo = Preferences.has("extensions.test.foo"); | let hasFoo = Preferences.has("extensions.test.foo"); | ||
// hasFoo == true, if the pref has a default value | // hasFoo == true, if the pref has a default value | ||
=== Locking and Unlocking === | |||
Preferences with default values can be locked to prevent users from changing them. While they are locked, <code>get</code> will always return the default value, even if the user set a value back when the preference was unlocked. | Preferences with default values can be locked to prevent users from changing them. While they are locked, <code>get</code> will always return the default value, even if the user set a value back when the preference was unlocked. | ||
| Line 221: | Line 227: | ||
lockedFoo = Preferences.locked("extensions.test.foo"); | lockedFoo = Preferences.locked("extensions.test.foo"); | ||
// lockedFoo == false, since we've just unlocked it | // lockedFoo == false, since we've just unlocked it | ||
=== Registering a Function Observer === | |||
Register a function as an observer by calling <code>observe</code> with the name of the preference to observe and the function to observe it: | |||
function someFunction(newValue) {...}; | |||
Preferences.observe("something", someFunction); | |||
When receiving a notification that the preference has changed, the function will be provided the new value of the preference. | |||
=== Registering a Method Observer === | |||
Register a method as an observer by calling <code>observe</code> with the name of the preference to observe, the method to observe it, and the object to which the method belongs: | |||
let someObject = { | |||
onSomething: function(newValue) {...}, | |||
}; | |||
Preferences.observe("something", someObject.onSomething, someObject); | |||
When receiving a notification that the preference has changed, the method will be provided the new value of the preference. | |||
=== Registering an Object Observer === | |||
Register an object that implements the [http://mxr.mozilla.org/mozilla/source/xpcom/ds/nsIObserver.idl nsIObserver interface] as an observer by calling <code>observe</code> with the name of the preference to observe and the object to observe it: | |||
let someObject = { | |||
observe: function(subject, topic, data) {...} | |||
}; | |||
Preferences.observe("something", someObject); | |||
When receiving a notification that a preference has changed, the object's observe method will be provided the notification's subject, topic, and data parameters, in that order, which is compatible with the type signature of the [http://mxr.mozilla.org/mozilla/source/xpcom/ds/nsIObserver.idl nsIObserver] interface. | |||
=== Unregistering Observers === | |||
Unregister observers by calling <code>ignore</code> with the same parameters you passed to <code>observe</code>: | |||
Preferences.ignore("something", someFunction); | |||
Preferences.ignore("something", someObject.onSomething, someObject); | |||
Preferences.ignore("something", someObject); | |||
Note: the module wraps observers in a wrapper that implements [http://mxr.mozilla.org/mozilla/source/xpcom/base/nsIWeakReference.idl?mark=71-94#71 nsISupportsWeakReference], so you don't necessarily have to remove your observers to avoid leaking memory. Nevertheless, it is good practice to do so anyway. | |||
== StringBundle == | == StringBundle == | ||