N-R > Object.watch |  |

Object.watch

Object, Object.watch, watch

Availability

Flash Player 6.

Usage

    myObject.watch( prop, callback [, userData] )

Parameters

`prop` A string indicating 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 value of `true` if the watchpoint is created successfully, otherwise, returns a `false` value.

Description

Method; registers a callback function to be invoked when a specified property of an ActionScript object changes. When the property changes, the callback function is invoked with `myObject` as the containing object. You must return the new value from the `object.watch` callback function, or 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 may 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 Netscape 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 callback function and use it in the callback function.

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 in order to fire watchpoints on it. To work with a getter/setter property, `Object.watch` needs to evaluate the property constantly, which is inefficient.

Generally, ActionScript predefined properties, such as `_x`, `_y`, `_width` and `_height`, are getter/setter properties, and thus cannot be watched with `Object.watch`.

Example

This example shows a CheckBox component with methods that set the label or value of each check box instance:

    myCheckBox1.setValue(true);
    myCheckBox1.setLabel("new label");
    ...

It's convenient to think of the value and label of a check box as properties. It's possible to use `Object.watch` to make accessing the value and label look like property access rather than method invocation, as in the following:

    // Define constructor for (and thus define) CheckBox class
    function CheckBox() {
    	...
    	this.watch('value', function (id, oldval, newval){
    		...
    	});
    	this.watch('label', function(id, oldval, newval){
    		...
    	});
    }

When the value or label property is modified, the function specified by the component is invoked to perform any tasks needed to update the appearance and state of the component to reflect its new parameters. Therefore, the following assignment statement uses an `Object.watch` handler to notify the component that the variable has changed and causes it to update its graphical representation.

    myCheckBox1.value = false;

This syntax is more concise than the former syntax:

    myCheckBox1.setValue(false);

See also

`Object.addProperty`, `Object.unwatch`