Defining data bindings in ActionScript

You can define a data binding in ActionScript by using the mx.binding.utils.BindingUtils class. This class defines static methods that let you create a data binding to a property implemented as a variable, by using the bindProperty() method, or to a method, by using the bindSetter() method. For an example using the bindProperty() method, see About data binding.

Differences between defining bindings in MXML and ActionScript

There are a few differences between defining data bindings in MXML at compile time and in defining them at runtime in ActionScript:

  • You cannot include ActionScript code in a data binding expression defined by the bindProperty() or bindSetter() method. Instead, use the bindSetter() method to specify a method to call when the binding occurs.

  • You cannot include an E4X expression in a data binding expression defined in ActionScript.

  • You cannot include functions or array elements in property chains in a data binding expression defined by the bindProperty() or bindSetter() method.

  • The MXML compiler has better warning and error detection support than runtime data bindings defined by the bindProperty() or bindSetter() method.

Example: Defining a data binding in ActionScript

The following example uses the bindSetter() method to set up a data binding. The arguments to the bindSetter() method specify the following:

  • The source object

  • The name of the source property

  • A method that is called when the source property changes

In the following example, as you enter text in the TextInput control, the text is converted to upper case as it is copied to the TextArea control:

<?xml version="1.0"?>
<!-- binding/BindSetterAS.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <fx:Script>
        <![CDATA[

            import mx.binding.utils.*;
            import mx.events.FlexEvent;

            // Method called when myTI.text changes.
            public function updateMyString(val:String):void {
                myTA.text = val.toUpperCase();
            }

            <!-- Event listener to configure binding. -->
            public function mySetterBinding(event:FlexEvent):void {
                var watcherSetter:ChangeWatcher = 
                    BindingUtils.bindSetter(updateMyString, myTI, "text");
            }
        ]]>
    </fx:Script>

    <s:Label text="Bind Setter using setter method"/>
    <s:TextInput id="myTI" 
        text="Hello Setter" />
    <s:TextArea id="myTA" 
        initialize="mySetterBinding(event);"/>
</s:Application>

The executing SWF file for the previous example is shown below:

Defining binding watchers

Flex includes the mx.binding.utils.ChangeWatcher class that you can use to define a data‑binding watcher. Typically, a data-binding watcher invokes an event listener when a binding occurs. To set up a data-binding watcher, you use the static watch() method of the ChangeWatcher class, as the following example shows:

<?xml version="1.0"?>
<!-- binding/DetectWatcher.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    initialize="initWatcher();">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

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

          public var myWatcher:ChangeWatcher;

          // Define binding watcher. 
          public function initWatcher():void {
            // Define a watcher for the text binding.
              myWatcher = ChangeWatcher.watch(textarea, "text", watcherListener);
          }

          // Event listener when binding occurs. 
          public function watcherListener(event:Event):void {
            myTA1.text="binding occurred";
                
            // Use myWatcher.unwatch() to remove the watcher.
          }
        ]]>
    </fx:Script>

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

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

The executing SWF file for the previous example is shown below:

You define an event listener for the data-binding watcher, where the event listener takes 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. For more information on determining the event type, see Using the Bindable metadata tag.

Many event listeners take an event object of type PropertyChangeEvent because that is the default data type of the event dispatched by bindable properties. You can always specify an event type of flash.events.Event, the base class for all Flex events.