GM_watchValue

Greg Parris edited this page Jul 18, 2013 · 1 revision

Description

GM_watchValue allows a userscript to be notified when a script preference (typically set through GM_setValue) is modified.

Arguments

String aName

The name of the preference to monitor.

Function aCallback

The function called when the preference value changes. Gets passed the Response Object (see below).

Returns

String aUUID

A unique identifier (UUID), tying the monitored preference to the callback. Used to unwatch a value using GM_unwatchValue.

Response Object

The response object passed as the first argument to the GM_watchValue callback mentioned above.

  • String name: The name of the preference that was modified.
  • String Boolean Integer oldValue: The previous value of the preference.
  • String Boolean Integer newValue: The current value of the preference.

Example

GM_setValue("foo", "bar");
 
function myObserver1(aNotice) {
GM_log("#1 observed '" + aNotice.name + "' changed from '"
     + aNotice.oldValue + "' to '" + aNotice.newValue + "'");
}
 
function myObserver2(aNotice) {
GM_log("#2 observed '" + aNotice.name + "' changed from '"
     + aNotice.oldValue + "' to '" + aNotice.newValue + "'");
}
 
var obs1UUID = GM_watchValue("foo", myObserver1);
GM_log("'foo' observer #1 GUID == " + obs1UUID);
 
var obs2UUID = GM_watchValue("foo", myObserver2);
GM_log("'foo' observer #2 GUID == " + obs1UUID);
 
GM_setValue("foo", "baz");
 
if (GM_unwatchValue("foo", obs1UUID))
  GM_log("removed 'foo' observer #1");
else
  GM_log("unable to remove 'foo' observer #1");
 
GM_setValue("foo", "qux");
 
if (GM_unwatchValue("foo"))
  GM_log("removed all 'foo' observers");
else
  GM_log("unable to remove all 'foo' observers");

 
GM_setValue("foo", "bar");