watch (Object.watch method) -- Version 8

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.

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 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().

Parameters

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).

userData:Object [optional] - 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.

Returns

Boolean - A Boolean value: true if the watchpoint is created successfully, false otherwise.

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
var speedWatcher:Function = function(prop, oldVal, newVal, speedLimit) {
    // Check whether speed is above the limit
    if (newVal > speedLimit) {
    trace ("You are speeding.");
    }
    else {
    trace ("You are not speeding.");
    }
    
    // Return the value of newVal.
    return newVal;
}
// Use watch() to register the event handler, passing as parameters:
// - the name of the property to watch: "speed"
// - a reference to the callback function speedWatcher
// - the speedLimit of 55 as the userData parameter
myObject.watch("speed", speedWatcher, 55);

// set the speed property to 54, then to 57
myObject.speed = 54; // output: You are not speeding
myObject.speed = 57; // output: You are speeding

// unwatch the object
myObject.unwatch("speed");
myObject.speed = 54; // there should be no output

watch (Object.watch method)

Parameters

Returns

Example

See also