package com.ericfeminella.utils
{
import mx.binding.utils.BindingUtils;
import mx.binding.utils.ChangeWatcher;
import flash.utils.Dictionary;
/**
*
* Provides a mechanism for dynamically adding data bindings
* to a property on an object as well as management of all
* objects within the Binding Chain.
*
* <p>
* This class provides a wrapper implementation for the
* mx.bindings.utils API from which multiple objects
* within a Binding Chain can be managed and modified
* </p>
*
*/
public final class DynamicBindingChain
{
/**
*
* Defines a hash which contains a reference to all objects
* added to the DynamicBindingChain chain. The object which
* contains a property which will participate in the Binding
* chain is used as the key in the Dictionary
*
*/
private var chain:Dictionary;
/**
*
* Defines the binding host of the DynamicBindingChain
* instance property
*
*/
private var host:Object;
/**
*
* Defines the binding property for the DynamicBindingChain
* instance
*
*/
private var property:String;
/**
*
* Creates a new DynamicBindingChain object and initializes
* properties.
*
* <p>
* DynamicBindingChain objects can be used to wrap the
* mx.binding.utils API in order to manage the binding
* chain throughout the lifecycle of a DynamicBindingChain
* instance
* </p>
*
* @param the owner of the properrty from which the
* host object is to be bound
* @param the property that the newly binded property
* will be bound
*
*/
public function DynamicBindingChain(owner:Object, property:String)
{
this.chain = new Dictionary();
this.host = owner;
this.property = property;
}
/**
*
* Retrieves the property which objects added to the
* Binding chain will be bound to
*
* @return the property name which objects are to bind
*
*/
public function get Property() : String
{
return property;
}
/**
*
* Retrieves the host object which contains the property
* which other objects in the Binding chain are bound
*
* @return object which contains the hosting property
*
*/
public function get Host() : Object
{
return host;
}
/**
*
* Adds a new object to the current binding chain for
* this DynamicBindingChain instance
*
* @param host object from which to add a bindable
* property. This object will be used as the
* key for managing the ChangeWatcher instance
* created by adding the dynamic binding
*
* @param the property on the host object which is to
* be made bindable
*
*/
public function addToBindingChain(instance:Object, property:String) : void
{
var watcher:ChangeWatcher = BindingUtils.bindProperty( instance, property, this.host, this.property );
chain[ instance.toString() ] = watcher;
}
/**
*
* Removes binding from a dynamic bindable object property
* which has been added to the DynamicBindingChain instance
*
* @param the instance which contains the bound property
*
*/
public function removeFromBindingChain(instance:Object) : void
{
var watcher:ChangeWatcher = getWatcher(instance);
watcher.unwatch();
}
/**
*
* Determines if the object property of a bindable object
* which has been added to the DynamicBindingChain instance
* is currently bound to the value of the host property
*
* @param the instance which contains the bound property
* @return true if binding has been added, otherwise false
*
*/
public function objectIsBound(instance:Object) : Boolean
{
var watcher:ChangeWatcher = getWatcher( instance );
return watcher.isWatching();
}
/**
*
* Adds a handler function to an object which has been added
* to the DynamicBindingChain instance which is invoked whenever
* the value of the host property in the binding chain changes
*
* @param the instance which contains the bound property
* @param method which handles property change updates
*
*/
public function addHandlerToObject(instance:Object, handler:Function) : void
{
var watcher:ChangeWatcher = getWatcher(instance);
watcher.setHandler(handler);
}
/**
*
* Retrieves the property value of each object which has been
* added to the DynamicBindingChain instance
*
* @param the instance which contains the bound property
* @return the current bound property value
*
*/
public function getCurrentValue(instance:Object) : Object
{
var watcher:ChangeWatcher = getWatcher( instance );
return watcher.getValue();
}
/**
*
* Determines the amount of objects currently added
* to the Binding Chain
*
* @return the length of the Binding Chain
*
*/
public function objectsInChain() : int
{
var i:int = 0;
for (var prop:Object in this.chain)
{
i++;
}
return i;
}
/**
*
* @private
*
* Retrieves a ChangeWatcher which has been added to the
* DynamicBindingChain instance hash
*
* @param object instance which hosts the binding property
* previously added to the DynamicBindingChain
*
* @throws undefined exception which occurs when the object
* specified has not been added to the chain
*
* @return ChangeWatcher instance added to the chain
*
*/
private function getWatcher(instance:Object) : ChangeWatcher
{
var watcher:ChangeWatcher = chain[instance.toString()] as ChangeWatcher;
return watcher;
}
}
}