Creating and Extending Flex 2 Components > Creating Custom Flex Components > Using Metadata Tags in Custom Components > Metadata tags > Bindable metadata tag

Bindable metadata tag

When a property is the source of a data binding expression, Flex automatically copies the value of the source property to any destination property when the source property changes. To signal to Flex to perform the copy, you must use the [Bindable] metadata tag to register the property with Flex, and the source property must dispatch an event.

The [Bindable] metadata tag has the following syntax:

[Bindable]
[Bindable(event="eventname")]

If you omit the event name, Flex automatically creates an event named propertyChange.

You can use the [Bindable] metadata tag in three places:

• Before a public class definition.

  The [Bindable] metadata tag makes usable as the source of a binding expression all public properties that you defined as variables, and all public properties that are defined by using both a setter and a getter method. In this case, [Bindable] takes no parameters, as the following example shows:

  [Bindable]
  public class TextAreaFontControl extends TextArea {}
  

  The Flex compiler automatically generates an event named propertyChange for all public properties so that the properties can be used as the source of a data binding expression. In this case, specifying the [Bindable] metadata tag with no event is the same as specifying the following:

  [Bindable(event="propertyChange")]
  

  If the property value remains the same on a write, Flex does not dispatch the event or update the property.

  NOTE

  When you use the [Bindable] metadata tag before a public class definition, it only applies to public properties; it does not apply to private or protected properties, or to properties defined in any other namespace. You must insert the [Bindable] metadata tag before a nonpublic property to make it usable as the source for a data binding expression.

• Before a public, protected, or private property defined as a variable to make that specific property support binding.

  The tag can have the following forms:

  [Bindable]
  public var foo;
  

  The Flex compiler automatically generates an event named propertyChange for the property. If the property value remains the same on a write, Flex does not dispatch the event or update the property.

  You can also specify the event name, as the following example shows:

  [Bindable(event="fooChanged")]
  public var foo;
  

  In this case, you are responsible for generating and dispatching the event, typically as part of some other method of your class. You can specify a [Bindable] tag that includes the event specification if you want to name the event, even when you already specified the [Bindable] tag at the class level.

• Before a public, protected, or private property defined by a getter or setter method.

  You must define both a setter and a getter method to use the [Bindable] tag with the property. If you define just a setter method, you create a write-only property that you cannot use as the source of a data-binding expression. If you define just a getter method, you create a read-only property that you can use as the source of a data-binding expression without inserting the [Bindable] metadata tag. This is similar to the way that you can use a variable, defined by using the const keyword, as the source for a data binding expression.

  The tag can have the following forms:

  [Bindable]
  public function set shortNames(val:Boolean):void {
      ...                
  }
  
  public function get shortNames():Boolean {
      ...
  }    
  

  The Flex compiler automatically generates an event named propertyChange for the property. If the property value remains the same on a write, Flex does not dispatch the event or update the property. To determine if the property value changes, Flex calls the getter method to obtain the current value of the property.

  You can specify the event name, as the following example shows:

  [Bindable(event="changeShortNames")]
  public function set shortNames(val:Boolean):void {
      ...
      // Create and dispatch event. 
      dispatchEvent(new Event("changeShortNames"));
  }
  
  // Get method. 
  public function get shortNames():Boolean {
      ...
  }                
  

  In this case, you are responsible for generating and dispatching the event, typically in the setter method. You can specify a [Bindable] tag that includes the event specification to name the event, even when you already specified the [Bindable] tag at the class level.

The following example makes the maxFontSize and minFontSize properties that you defined as variables that can be used as the sources for data bindings:

    // Define public vars for tracking font size.
    [Bindable]
    public var maxFontSize:Number = 15;
    [Bindable]
    public var minFontSize:Number = 5;

In the following example, you make a public property that you defined by using a setter and a getter method that is usable as the source for data binding The [Bindable] metadata tag includes the name of the event broadcast by the setter method when the property changes:

    // Define private variable.
    private var _maxFontSize:Number = 15;

    [Bindable(event="maxFontSizeChanged")]
    // Define public getter method.
    public function get maxFontSize():Number {
        return _maxFontSize;
    }

    // Define public setter method.
    public function set maxFontSize(value:Number):void {
        if (value <= 30) {
            _maxFontSize = value;
        } else _maxFontSize = 30;

        // Create event object. 
        var eventObj:Event = new Event("maxFontSizeChanged");
        dispatchEvent(eventObj);

    }

In this example, the setter updates the value of the property, and then creates and dispatches an event to invoke an update of the destination of the data binding.

In an MXML file, you can make all public properties that you defined as variables usable as the source for data binding by including the [Bindable] metadata tag in an <mx:Metadata> block, as the following example shows:

<mx:Metadata>
    [Bindable]
</mx:Metadata>

You can also use the [Bindable] metadata tag in an <mx:Script> block in an MXML file to make individual properties that you defined as variables usable as the source for a data binding expression. Alternatively, you can use the [Bindable] metadata tag with properties that you defined by using setter and getter methods.

Subtopics

Using read-only properties as the source for data binding

You can automatically use a read-only property defined by a getter method, which means no setter method, as the source for a data-binding expression. Flex performs the data binding once when the application starts.

Because the data binding from a read-only property occurs only once at application start up, you omit the [Bindable] metadata tag for the read-only property.

Using static properties as the source for data binding

You can automatically use a static constant as the source for a data-binding expression. Flex performs the data binding once when the application starts. Because the data binding occurs only once at application start up, you omit the [Bindable] metadata tag for the static constant.

You cannot use the [Bindable] metadata tag with a static variable. If you do, the compiler issues an error.

The following example uses a static constant as the source for a data-binding expression:

<?xml version="1.0"?>
<!-- metadata/StaticBinding.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
      <![CDATA[

        // This syntax casues a compiler error.
        // [Bindable]
        // public static var varString:String="A static var.";

        public static const constString:String="A static const.";
      ]]>
    </mx:Script>

    <!-- This binding occurs once at application startup. -->
    <mx:Button label="{constString}"/>    
</mx:Application>

Flex 2.01

Comments

Add Comment

bmantuano said on Aug 22, 2007 at 5:28 PM :

Although listed above in the doc, the following will not create a bindable property.
[Bindable(event="fooChanged")]
public var foo;

Otherwise the following statements would update any bindings to foo, but they do not:
foo = newValue;
dispatchEvent(new Event("fooChanged"));

I suspect it is related to the internal optimization which prevents a binding from executing when the value has not changed.

smgilson said on Aug 23, 2007 at 8:03 AM :

That is correct - a binding does not trigger unless the value of the property changes.

Stephen Gilson
Flex Doc Team

Rambo 007 said on Mar 18, 2008 at 1:37 PM :

I think the example with the "changeShortNames" event is very wrong, and very confusing. The Bindable metadata goes before the GETTER function, never before the setter. It's basically telling the compiler "if you see this function used in a binding source context, be prepared to watch for the declared change events to signal that the function should be invoked again to return a new value". Doesn' t make sense to mark the setter as bindable, since it won't be used in a binding source context.

Jovin49 said on Mar 18, 2008 at 2:11 PM :

The documentation for Metadata tags has been updated for Flex 3. The error in the example has been corrected in the new docs.

Access the Flex 3 docs: http://www.adobe.com/go/flex3_livedocs

Navigate to Custom Component Development > Metadata Tags in Custom Components > Metadata Tags

Vince Genovese
Flex Doc Team

Related Topics

• Using Data Binding

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flex/201/html/metadata_141_06.html

Add Comment