Core JavaScript 1.5 Reference:Global Objects:Object:watch

From MDC

Contents 1 Summary 2 Syntax 3 Parameters 4 Description 5 Examples 5.1 Example: Using watch and unwatch 5.2 Example: Using watch to validate an object's properties 6 See Also

[edit] 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

[edit] Syntax

object.watch(prop, handler)

[edit] Parameters

prop 

The name of a property of the object.

handler 

A function to call.

[edit] 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 by returning 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 native code as well as assignments in script. In Firefox, handler is only called from assignments in 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, window.location += '#myAnchor' will call myHandler:

[edit] Examples

[edit] Example: Using watch and unwatch

var o = {p:1};
o.watch("p",
   function (id, oldval, newval) {
      print("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;

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

[edit] Example: Using watch to validate an object's properties

You can use watch to test any assignment to an object's properties. This example ensures that every Person always has a valid name and an age between 0 and 200.

Person = function(name,age) {
  this.watch("age", Person.prototype._isValidAssignment);
  this.watch("name", Person.prototype._isValidAssignment);
  this.name = name;
  this.age = age;
}

Person.prototype.toString = function() {
  return this.name + ", " + this.age;
};

Person.prototype._isValidAssignment = function(id, oldval, newval) {
  if (id == "name" && (!newval || newval.length > 30)) {
    throw new RangeError("invalid name for " + this);
  }
  if (id == "age"  && (newval < 0 || newval > 200)) {
    throw new RangeError("invalid age for " + this);
  }
  return newval;
}

will = new Person("Will", 29);
print(will);   // Will, 29

try {
  will.name = "";
} catch (e) {
  print(e);
}

try {
  will.age = -4;
} catch (e) {
  print(e);
}

This script displays the following:

Will, 29
RangeError: invalid name for Will, 29
RangeError: invalid age for Will, 29

[edit] See Also

unwatch