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 constants as the source for data binding

You can automatically use a static constant or 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 static constant or from a read-only property that a getter method defines occurs only once at application start up, you omit the [Bindable] metadata tag for the static constant or read-only property.

Flex 2

Comments

Add Comment

No screen name said on Oct 31, 2006 at 4:33 PM :

It is also possible to apply [Bindable] to read-only properties that do not evaluate to a constant value. This is useful for properties whose value is computed and updated by some internal algorithm and that should not be settable.

The documentation suggests that read-only properties cannot have a [Bindable] tag so one must also define a dummy setter method. This is undesirable. Moreover omitting the [Bindable] tag would exclude the property from consideration in run-time data binding.

The solution is to specify a custom event type that is fired whenever the property's computed value may change. It is important that a custom event type (other than 'propertyChange') be used as otherwise the compiler will warn that read-only properties should not have [Bindable] tags.

In the following example, the computedProperty yields the value of some expression. When some interesting change in internal state occurs, possibly in response to events received from other objects, we call the notifyComputedPropertyChange() to fire the event. The event causes dependent binding expressions to be re-evaluated as needed.

public class MyClass extends EventDispatcher
{
[Bindable(event="computedPropertyChange")]
public function get computedProperty():Object
{
return someExpression;
}

private function notifyComputedPropertyChange():void
{
dispatchEvent(new Event('computedPropertyChange'));
}

// etc...
}

This usage seems to work fine although I find no mention of it in the documentation. I have found it extremely useful in many diverse situations where I could not otherwise have applied data binding. I hope it will continue to remain supported and indeed be promoted in the official documentation!

sparky1962 said on Feb 28, 2007 at 10:58 AM :

This section doesn't make it clear what the type of the propertyChange event is (PropertyChangeEvent?), what the "type" property is set to (PropertyChangeEvent.UPDATED?) or on which object the event is dispatched (presumably on the "mother" object with the property and not on the property itself?)
If the event's dispatched on a "mother" object that has more than one bindable property, how do listeners for the PropertyChangeEvent know which property has changed? Is the name of the property that changed a property of the PropertyChangeEvent class?
Also the phrase "if the property remains the same" is ambiguous as the concept of being "the same" for a property that is a "reference type" (to use .NET speak) can mean lots of different things. If the property is a pointer to an object and it is reassigned to point to a equivalent object, is it "the same"? Alternatively if the pointer is not changed but what it points to changes, is it "the same"?

smgilson said on Mar 2, 2007 at 10:54 AM :

The literal answer (as can be seen in the generated code in the file _Foo-binding-generated.as, where Foo.mxml is an MXML component with bindings) is that "not the same" translates to the following AS test:

(oldValue !== value)

The implications with respect to your two cases are:

1. property repointed to a different but equivalent object: binding will fire.
2. property not changed, but the thing it points to (say, a container) changes internally: binding will *not* fire.

Stephen Gilson
Flex Doc Team

_Sam_ said on Aug 8, 2007 at 10:55 AM :

It's also possible to put the Binding tag on a method (not a property getter, a standalone method) and that method is re-invoked when the corresponding event is dispatched.

danger42 said on Aug 9, 2007 at 6:51 AM :

Good point, Sam. There's more info on doing this in the revamped binding chapter of the Flex docs. You can find the updated version here:

http://blogs.adobe.com/flexdoc/pdf/databinding.pdf

These changes will make it into the next revision of the docs.

hth,
matt horn
flex docs

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

Current page: http://livedocs.adobe.com/flex/2/docs/00001653.html

Add Comment