User Guide

Object 567
You can use the return statement in your callback method definition to affect the value of
the property you are watching. The value returned by your
callback method is assigned to
the watched object property. The value you choose to return depends on whether you wish to
monitor, modify or prevent changes to the property:
■ If you are merely monitoring the property, return the newVal parameter.
■ If you are modifying the value of the property, return your own value.
■ If you want to prevent changes to the property, return the oldVal parameter.
If the callback method you define does not have a return statement, then the watched
object property is assigned a value of
undefined.
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
Object.unwatch method.
Only a single watchpoint can be registered on a property. Subsequent calls to
Object.watch() on the same property replace the original watchpoint.
The
Object.watch() method behaves similarly to the Object.watch() function in
JavaScript 1.2 and later. The primary difference is the
userData parameter, which is a Flash
addition to
Object.watch() that Netscape Navigator does not support. You can pass the
userData parameter to the event handler and use it in the event handler.
The
Object.watch() method cannot watch getter/setter properties. Getter/setter properties
operate through lazy evaluation-- the value of the property is not determined until the
property is actually queried. Lazy evaluation is often efficient because the property is not
constantly updated; it is, rather, evaluated when needed. However,
Object.watch() needs to
evaluate a property to determine whether to invoke the
callback function. To work with a
getter/setter property,
Object.watch() needs to evaluate the property constantly, which is
inefficient.
Generally, predefined ActionScript properties, such as
_x, _y, _width, and _height, are
getter/setter properties and cannot be watched with
Object.watch().
Availability: ActionScript 1.0; Flash Lite 2.0
Parameters
name:String - A string; the name of the object property to watch.
callback:Function - The function to invoke when the watched property changes. This
parameter is a function object, not a function name as a string. The form of
callback is
callback(prop, oldVal, newVal, userData).