Defining binding watchers -- Flex 2.01

You can detect when a binding occurs in your application. Flex includes the mx.binding.utils.ChangeWatcher class that you can use to define a watcher for a data binding. Typically, your event watcher invokes an event listener when the binding occurs.

To set up a binding watcher, you use the static watch() method of the ChangeWatcher class, as the following example shows:

<?xml version="1.0"?>
<!-- binding/DetectWatcher.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    initialize="initWatcher();">

    <mx:Script>
      <![CDATA[
        import mx.utils.*;
        import mx.binding.utils.*;
        import mx.events.FlexEvent;
        import mx.events.PropertyChangeEvent;

        // Define a bindable property. 
        [Bindable]
        public var propChain:Object;
        
        public var myWatcher:ChangeWatcher;

        // Define binding watcher. 
        public function initWatcher():void {
            // Define a watcher for the text binding.
            ChangeWatcher.watch(textarea, "text", watcherListener);
                
            // Initialize the Object. 
            propChain = new ObjectProxy();
            propChain.sub1 = new ObjectProxy();
            propChain.sub1.sub2 = new String("first sub2");

            // Define a watcher for the Object binding.
            myWatcher=
                ChangeWatcher.watch(this, ["propChain","sub1","sub2"],
                    watcherListenerProp);
        }

        // Event listener when binding occurs. 
        public function watcherListener(event:Event):void {
            myTA1.text="binding occurred";
        }

        // Event listener when binding occurs. 
        public function watcherListenerProp(event:PropertyChangeEvent):void
        {
            myTA2.text="prop chain binding occurred";
            myWatcher.unwatch();
        }
      ]]>
    </mx:Script>

    <!-- Define a binding expression to watch. -->
    <mx:TextInput id="textinput" text="Hello"/>
    <mx:TextArea id="textarea" text="{textinput.text}"/>

    <!-- Trigger a binding. -->
    <mx:Button label="Submit" click="textinput.text='Goodbye';"/>
    <mx:TextArea id="myTA1"/>

    <!-- Trigger a binding to a bindable property chain. -->
    <mx:Button label="Submit prop chain" 
        click="propChain.sub1.sub2 = 'second sub2';"/>
    <mx:TextArea id="myTA2"/>
</mx:Application>

This example uses the ObjectProxy class to manipulate the propChain variable because that class provides the ability to track changes to an item. In this example, the event listener for the propChain Object uses the unwatch() method to remove the watcher after the first binding occurs.

You define an event listener for each binding watcher, where the event listeners take a single argument that contains the event object. The data type of the event object is determined by the property being watched. Each bindable property can dispatch a different event type and the associated event object. The [Bindable] metadata tag, used to make a property bindable, specifies the event type of the event dispatched when the property changes. For more information about the [Bindable] metadata tag, see Using Metadata Tags in Custom Components in Creating and Extending Flex 2 Components.

The watcherListener() event listener takes an event object of type FlexEvent because that is the data type of the event dispatched by the text property of the TextArea control when it changes.

The watcherListenerProp() event listener takes an event object of type PropertyChangeEvent because that is the data type of the event dispatched by the propChain Object. This is also the event type associated with the propertyChange event, the default event dispatched by a property when you do not specify an event type in the [Bindable] metadata tag.

For both event listeners, you can specify an event type of flash.events.Event, the base class for all Flex events.