Object.prototype.watch()

  • Revision slug: JavaScript/Reference/Global_Objects/Object/watch
  • Revision title: watch
  • Revision id: 49848
  • Created:
  • Creator: Enumera
  • Is current revision? No
  • Comment /* Description */

Revision Content

Summary

Watches for a property to be assigned a value and runs a function when that occurs.

Method of Object
Implemented in: JavaScript 1.2, NES 3.0

Syntax

watch(prop, handler)

Parameters

prop 
The name of a property of the object.
handler 
A function to call.

Description

Watches for assignment to a property named prop in this object, calling handler(prop, oldval, newval) whenever prop is set and storing the return value in that property. A watchpoint can filter (or nullify) the value assignment, by returning a modified newval (or oldval).

If you delete a property for which a watchpoint has been set, that watchpoint does not disappear. If you later recreate the property, the watchpoint is still in effect.

To remove a watchpoint, use the unwatch method. By default, the watch method is inherited by every object descended from Object.

The JavaScript debugger has functionality similar to that provided by this method, as well as other debugging options. For information on the debugger, see Venkman.

In NES 3.0 and 4.x, handler is called from script as well as native code. In Firefox, handler is only called from script, not from native code. For example, window.watch('location', myHandler) will not call myHandler if the user clicks a link to an anchor within the current document. However, the following code will call myHandler: window.location += '#myAnchor';.

Examples

Example: Using watch and unwatch

<script language="JavaScript">

var o = {p:1};
o.watch("p",
   function (id,oldval,newval) {
      document.writeln("o." + id + " changed from "
         + oldval + " to " + newval);
      return newval;
   });

o.p = 2;
o.p = 3;
delete o.p;
o.p = 4;

o.unwatch('p');
o.p = 5;

</script>

This script displays the following:

o.p changed from 1 to 2
o.p changed from 2 to 3
o.p changed from undefined to 4

See Also

unwatch

{{ wiki.languages( { "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Object/watch" } ) }}

Revision Source

<p>
</p>
<h3 name="Summary"> Summary </h3>
<p>Watches for a property to be assigned a value and runs a function when that occurs.
</p>
<table class="fullwidth-table">
<tbody><tr>
<td class="header" colspan="2">Method of <a href="en/Core_JavaScript_1.5_Reference/Objects/Object">Object</a></td>
</tr>
<tr>
<td>Implemented in:</td>
<td>JavaScript 1.2, NES 3.0</td>
</tr>
</tbody></table>
<h3 name="Syntax"> Syntax </h3>
<p><code>
watch(<i>prop</i>, <i>handler</i>)
</code>
</p>
<h3 name="Parameters"> Parameters </h3>
<dl><dt> <code>prop</code> </dt><dd> The name of a property of the object.
</dd></dl>
<dl><dt> <code>handler</code> </dt><dd> A function to call.
</dd></dl>
<h3 name="Description"> Description </h3>
<p>Watches for assignment to a property named <code>prop</code> in this object, calling <code>handler(prop, oldval, newval)</code> whenever <code>prop</code> is set and storing the return value in that property. A watchpoint can filter (or nullify) the value assignment, by returning a modified <code>newval</code> (or <code>oldval</code>).
</p><p>If you delete a property for which a watchpoint has been set, that watchpoint does not disappear. If you later recreate the property, the watchpoint is still in effect.
</p><p>To remove a watchpoint, use the <code><a href="en/Core_JavaScript_1.5_Reference/Objects/Object/unwatch">unwatch</a></code> method. By default, the <code>watch</code> method is inherited by every object descended from <code>Object</code>.
</p><p>The JavaScript debugger has functionality similar to that provided by this method, as well as other debugging options. For information on the debugger, see <a href="en/Venkman">Venkman</a>.
</p><p>In NES 3.0 and 4.x, <code>handler</code> is called from script as well as native code.  In Firefox, <code>handler</code> is only called from script, not from native code.  For example, <code>window.watch('location', myHandler)</code> will not call <code>myHandler</code> if the user clicks a link to an anchor within the current document.  However, the following code will call <code>myHandler</code>: <code>window.location += '#myAnchor';</code>.
</p>
<h3 name="Examples"> Examples </h3>
<h4 name="Example:_Using_watch_and_unwatch"> Example: Using <code>watch</code> and <code>unwatch</code> </h4>
<pre>&lt;script language="JavaScript"&gt;

var o = {p:1};
o.watch("p",
   function (id,oldval,newval) {
      document.writeln("o." + id + " changed from "
         + oldval + " to " + newval);
      return newval;
   });

o.p = 2;
o.p = 3;
delete o.p;
o.p = 4;

o.unwatch('p');
o.p = 5;

&lt;/script&gt;
</pre>
<p>This script displays the following:
</p>
<pre>o.p changed from 1 to 2
o.p changed from 2 to 3
o.p changed from undefined to 4
</pre>
<h3 name="See_Also"> See Also </h3>
<p><a href="en/Core_JavaScript_1.5_Reference/Objects/Object/unwatch">unwatch</a>
</p>{{ wiki.languages( { "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/Object/watch" } ) }}
Revert to this revision