| Object.watch( ) Method | Flash 6 |
| create a watchpoint to moderate property assignment | | 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 | 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( ) |
