Table of Contents

someObject.watch(prop, callback, userData)

Arguments

prop

A string indicating the name of the property to watch on someObject. The name must adhere to the rules for creating an identifier, outlined under Section 15.5 in Chapter 15.

callback

A function called whenever a value assignment attempt is made on prop. The function return value becomes the actual value assigned to the property.

userData

An arbitrary data value passed to callback.

Returns

A Boolean; true if the watchpoint was created successfully; false otherwise (for example, if callback is not a valid function).

Description

The watch( ) method registers a so-called watchpoint for someObject.prop. When a watchpoint is in effect, callback acts as a moderator for all value assignments to someObject.prop.

Whenever a value is assigned to prop, callback is executed and passed the following four arguments:

prop

The name of the property modified.

oldval

The old value of the property.

newval

The proposed new value of the property, as specified in the property assignment that triggered the watchpoint.

userData

An optional data value supplied by the original watch( ) call.

Hence, callback must take the generalized form:

function someWatch (prop, oldval, newval, userData) {
  return theNewPropertyValue;
}

The callback function is expected to return the actual value to be assigned to the property. For example, the following code places on rectangle.numSides a watchpoint that rejects all numSides assignments by simply returning oldval (effectively making numSides read-only). This is known as nullifying the assignment.

// Create the object and numSides property
var rectangle = new Object();
rectangle.numSides = 4;
// Add the watchpoint
rectangle.watch("numSides", rectWatch);
// Create the callback function that moderates assignments to numSides
function rectWatch (prop, oldval, newval, userData) {
  // Return the old value, which is, therefore, reassigned to the property
  return oldval;
}
// Usage: Attempt to change the value of numSides
rectangle.numSides = 3;
// Check if we changed it...
trace(rectangle.numSides);  // Nope! Displays: 4

To allow the property assignment to proceed unaltered, callback can return newval. For example:

function rectWatch (prop, oldval, newval, userData) {
  // Return the proposed new value unscathed
  return newval;
}

A watchpoint callback function that returns newval, and therefore has no net effect on property assignment, can still be useful. By adding a trace( ) command or a debugger breakpoint within the callback function, you can debug, log, or monitor any changes to the property.

Alternatively, callback can use newval to calculate or filter the property's final value (for example, by bringing an out-of-range value into valid range). Or callback can perform other tasks related to the property assignment. For example, consider a game in which a Buy button is disabled when the player has no money. By watching the player's cash property, we can turn the Buy button on and off, depending on the players current amount of money:

// Simplified GamePlayer class
function GamePlayer (startingMoney) {
  // Add watchpoint (notice that watchpoints can be set before a property exists)
  this.watch("cash", this.assignCash);
  // Assign the cash property an initial value
  this.cash = startingMoney;
}
   
// Method: assignCash()
GamePlayer.prototype.assignCash = function (prop, oldval, newval) {
  trace("Assigning cash: " + newval);
  // If the player has no cash...
  if (newval =  = 0) {
    // ...turn off the Buy button
    trace("Player has no money. Disabling Buy button.");
    gameGUI.buyButton.enabled = false;
  } else if (newval > 0) {
    // ...otherwise, turn on the Buy button
    trace("Player has some money. Enabling Buy button.");
    gameGUI.buyButton.enabled = true;
  }
   
  // Assign the new value to the cash property
  return newval;
}
   
// Make the player and issue 10 money units to start
p1 = new GamePlayer(10);
   
// Take away all the player's money
p1.cash = 0;
   
// OUTPUT:
Assigning cash: 10
Player has some money. Enabling Buy button.
Assigning cash: 0
Player has no money. Disabling Buy button.

A watchpoint can be set before a property exists, and the watchpoint continues to exist even if the watched property is deleted. If the property is recreated, the watch is triggered. To stop watching a property (i.e., to remove a watchpoint) use Object.unwatch( ).

There are limitations on which properties can be watched:

• Properties inherited through an object's prototype cannot be watched. The watched property must be assigned directly to someObject (use Object.hasOwnProperty( ) to distinguish between direct and inherited properties).

• Properties available in Flash 4 (_x, _y, _width, _height, etc.) cannot be watched. See the Availability heading for each property's entry in this Language Reference.

• Getter/setter properties created with Object.addProperty( ) cannot be watched. The getter/setter properties defined internally by Flash 6 ActionScript are listed in Table 18-15. Note that the Camera, Microphone, NetStream, and Video objects apply to Macromedia Flash Communication Server MX (Comm Server) and are not covered in this book (see http://www.macromedia.com/software/flashcom/ and Appendix A for additional resources).

Table 18-15. Getter/setter properties (Flash 6), which cannot be watched

Object	Getter/setter properties
Button	tabIndex
Camera	All properties
Microphone	All properties
MovieClip	tabIndex
NetStream	All properties
Sound	duration position
Stage	All properties
TextField	All properties
TextFormat	All properties
Video	All properties
XML	contentType docTypeDecl ignoreWhite loaded status xmlDecl
XMLnode	attributes childNodes firstChild lastChild nextSibling nodeName nodeType nodeValue parentNode previousSibling

See Also

Object.addProperty( ), Object._ _proto_ _, Object.unwatch( )

Table of Contents