User Guide

676 Chapter 2: ActionScript Language Reference
Object.watch()
Availability
Flash Player 6.
Usage
myObject.watch( prop:String, callback:Function [, userData:Object] ) : Boolean
Parameters
prop
A string; the name of the object property to watch.
callback 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)
.
userData An arbitrary piece of ActionScript data that is passed to the callback method. If
the
userData parameter is omitted, undefined is passed to the callback method. This parameter
is optional.
Returns
A Boolean value: true if the watchpoint is created successfully, false otherwise.
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.