User Guide

388 Chapter 6: ActionScript Core Classes
Description
Method; registers an event handler to be invoked when a specified property of an ActionScript
object changes. When the property changes, the event handler is invoked with
myObject as the
containing object.
Your 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().
Example
The following example uses watch() to check whether the speed property exceeds the speed
limit:
// Create a new object
var myObject:Object = new Object();
// Add a property that tracks speed
myObject.speed = 0;
// Write the callback function to be executed if the speed property changes