The Object class, which just about every other class extends, has great methods called watch and unwatch. This tutorial is not to explain the uses of those methods inparticular, but the extension functions I created to make it more usable.

What exactly does this do? It watches an object property for change and immediately invokes a function or a result catcher when a change occurs. There are no intervals or onEnterFrame() running to monitor properties. This method works great for waiting for changes in variables, Database results, and much more.

Here are the functions:

function watchThis ( where, what, returnWhere, returnWhat, cancelAfterFind, runFunc, funcArgs ){
    // reset watch if one is setup already
    where.unwatch( what );
   // setup a new watch with arguments supplied
   where.watch( what, watch_a, [where, returnWhere, returnWhat, cancelAfterFind, runFunc, funcArgs] );
}
function watch_a( id, old, newval, args){
    // apply value
    args[1][args[2]] = newval;
    // cancel the watch if argument is set
   if( args[3] ) args[0].unwatch(id);
    // run the callback function
   if( args[4] ) args[4](args[5]);
    // return value back to watch so it's not lost
   return newval;
}

The function you actually use here is watchThis. The function watch_a is just a support for the other. It is very important to return the newval as shown in the last line of the watch_a function. This will make sure the original data is not lost to the new object. Here is a breakdown of the arguments:

Arguments

where:Object

This is the object that contains the property to be watched. It must be the direct parent of the property.

what:String

 This is the property of the object being watched. Must be setup in quotation marks.

returnWhere:Object

This is the object to return the new value to. It is the direct parent of the property.

returnWhat:String

 This is the property in quotation marks of the object being returned to.

cancelAfterFind:Boolean

True / False of whether or not to continue watching an object after the first change.

runFunc:Function

 This is the callback function that will be invoked when a change is found in the watched object.




Here is a working example of how this works:

// include functions above in code here...
// text field to return results to. this is optional.
createTextField( "return_txt", 1, 0, 0, 300, 20);
// create new object to monitor
var obj:Object = new Object();
obj.results = 0;
// setup the watch function
watchThis( obj, "results", return_txt, "text", false, watchCallback, "Callback arguments" );
// you can replace 'return_txt' and 'text' with null if you don't want to return them to a variable / textfield
onMouseDown = function(){
    // this will increase a change in the object we're watching
    obj.results++;
}
// here's the callback function
function watchCallback(args){
    trace( 'This is a callback function: ' + args );
}

The arguments passed to the callback function are optional.
The returnWhere, returnWhat are optional. Can be replaced with null.
cancelAfterFind is false by default.
Callback Function is optional.

If you run the cancelAfterFind as true, it will stop watching the variable set after the first change ( in case you know it will change many times, but only want to initiate a function once ).

The value sent back to the return object is the value of the changed object property.

I've personally found countless uses for this function. It almost eliminates the use of setInterval and onEnterFrame for monitoring changes. With a little creative thinking, you can put it to great use. There shouldn't be any need to modify these functions.