The following table describes the metadata tags that you can use in ActionScript class files:

ArrayElementType metadata tag

When you define an Array variable in ActionScript, you specify Array as the data type of the variable. However, you cannot specify the data type of the elements of the Array.

To allow the Flex MXML compiler to perform type checking on Array elements, you can use the [ArrayElementType] metadata tag to specify the allowed data type of the Array elements, as the following example shows:

public class MyTypedArrayComponent extends VBox {

    [ArrayElementType("String")] 
    public var newStringProperty:Array;

    [ArrayElementType("Number")] 
    public var newNumberProperty:Array;
    ...
} 

In this example, you specify String as the allowed data type of the Array elements. If a user attempts to assign elements of a data type other than String to the Array in an MXML file, the compiler issues a syntax error, as the following example shows:

<MyComp:MyTypedArrayComponent>
    <MyComp:newStringProperty>
        <mx:Number>94062</mx:Number>
        <mx:Number>14850</mx:Number>
        <mx:Number>53402</mx:Number>
    </MyComp:newStringProperty>
</MyComp:MyTypedArrayComponent>

In this example, you try to use Number objects to initialize the Array, so the compiler issues an error.

You can also specify Array properties as tag attributes, rather than using child tags, as the following example shows:

<MyComp:MyTypedArrayComponent newNumberProperty="[abc,def]"/>

This MXML code generates an error because Flex cannot convert the Strings "abc" and "def" to a Number.

You insert the [ArrayElementType] metadata tag before the variable definition. The tag has the following syntax:

[ArrayElementType("elementType")]

The following table describes the property of the [ArrayElementType] 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.

For more information on data binding and on this metadata tag, see Binding Data.

Working with bindable property chains

When you specify a property as the source of a data binding, Flex monitors not only that property for changes, but also the chain of properties leading up to it. The entire chain of properties, including the destination property, is called a bindable property chain. In the following example, firstName.text is a bindable property chain that includes both a firstName object and its text property:

<first>{firstName.text}</first>

You should raise an event when any named property in a bindable property chain changes. If the property is marked with the [Bindable] metadata tag, the Flex compiler generates the event for you.

The following example uses the [Bindable] metadata tag for a variable and a getter property. The example also shows how to call the dispatchEvent() function.

[Bindable] 
public var minFontSize:Number = 5;

[Bindable("textChanged")] 
public function get text():String {
     return myText;
}

public function set text(t : String):void {
     myText = t;
    dispatchEvent( new Event( "textChanged" ) );}

If you omit the event name in the [Bindable] metadata tag, the Flex compiler automatically generates and dispatches an event named propertyChange so that the property can be used as the source of a data binding expression.

You should also provide the compiler with specific information about an object by casting the object to a known type. In the following example, the myList List control contains Customer objects, so the selectedItem property is cast to a Customer object:

<mx:Model id="selectedCustomer">
    <customer>
        <name>{Customer(myList.selectedItem).name}</name>
        <address>{Customer(myList.selectedItem).address}</address>
        ... 
    </customer>
</mx:Model>

There are some situations in which binding does not execute automatically as expected. Binding does not execute automatically when you change an entire item of a dataProvider property, as the following example shows:

dataProvider[i] = newItem

Binding also does not execute automatically for subproperties of properties that have [Bindable] metadata, as the following example shows:

...
[Bindable]
var temp;
// Binding is triggered:
temp = new Object();
// Binding is not triggered, because label not a bindable property
// of Object:
temp.label = foo; 
...

In this code example, the problem with {temp.label} is that temp is an Object. You can solve this problem in one of the following ways:

• Preinitialize the Object.
• Assign an ObjectProxy to temp; all of an ObjectProxy's properties are bindable.
• Make temp a strongly typed object with a label property that is bindable.

Binding also does not execute automatically when you are binding data to a property that Flash Player updates automatically, such as the mouseX property.

The executeBindings() method of the UIComponent class executes all the bindings for which a UIComponent object is the destination. All containers and controls, as well as the Repeater component, extend the UIComponent class. The executeChildBindings() method of the Container and Repeater classes executes all of the bindings for which the child UIComponent components of a Container or Repeater class are destinations. All containers extend the Container class.

These methods give you a way to execute bindings that do not occur as expected. By adding one line of code, such as a call to executeChildBindings() method, you can update the user interface after making a change that does not cause bindings to execute. However, you should only use the executeBindings() method when you are sure that bindings do not execute automatically.

DefaultProperty metadata tag

The [DefaultProperty] metadata tag defines the name of the default property of the component when you use the component in an MXML file.

The [DefaultProperty] metadata tag has the following syntax:

[DefaultProperty("propertyName")]

The propertyName property specifies the name of the default property.

You can use the [DefaultProperty] metadata tag in your ActionScript component to define a single default property. For more information and an example, see Creating a default property.

Deprecated metadata tag

A class or class elements marked as deprecated is one which is considered obsolete, and whose use is discouraged in the current release. While the class or class element still works, its use can generate compiler warnings.

The mxmlc command-line compiler supports the show-deprecation-warnings compiler option, which, when true, configures the compiler to issue deprecation warnings when your application uses deprecated elements. The default value is true.

Insert the [Deprecated] metadata tag before a property, method, or class definition to mark that element as deprecated. The [Deprecated] metadata tag has the following options for its syntax when used with a class, property or method:

[Deprecated("string_describing_deprecation")]
[Deprecated(message="string_describing_deprecation")]
[Deprecated(replacement="string_specifying_replacement")]
[Deprecated(replacement="string_specifying_replacement", since="version_of_replacement")]

The following uses the [Deprecated] metadata tag to mark the dataProvider property as obsolete:

[Deprecated(replacement="MenuBarItem.data")]
public function set dataProvider(value:Object):void
{
    ...
}

The [Event], [Effect] and [Style] metadata tags also support deprecation. These tags support the following options for syntax:

[Event(... , deprecatedMessage="string_describing_deprecation")]
[Event(... , deprecatedReplacement="change2")]
[Event(... , deprecatedReplacement="string_specifying_replacement", deprecatedSince="version_of_replacement")]

These metadata tags support the deprecatedReplacement and deprecatedSince attributes to mark the event, effect, or style as deprecated.

Effect metadata tag

The [Effect] metadata tag defines the name of the MXML property that you use to assign an effect to a component and the event that triggers the effect. If you define a custom effect, you can use the [Effect] metadata tag to specify that property to the Flex compiler.

For more information on defining custom effects, see Effects.

An effect is paired with a trigger that invokes the effect. A trigger is an event, such as a mouse click on a component, a component getting focus, or a component becoming visible. An effect is a visible or audible change to the component that occurs over a period of time.

You insert the [Effect] metadata tag before the class definition in an ActionScript file or in the <mx:Metadata> block in an MXML file. The [Effect] metadata tag has the following syntax:

[Effect(name="eventNameEffect", event="eventName")]

The following table describes the properties of the [Effect] metadata tag:

The [Effect] metadata tag is often paired with an [Event] metadata tag, where the [Event] metadata tag defines the event corresponding to the effect's trigger. By convention, the name of the effect is the event name with the suffix Effect, as the following example of an ActionScript file shows:

// Define event corresponding to the effect trigger.
[Event(name="darken", type="flash.events.Event")]
// Define the effect.
[Effect(name="darkenEffect", event="darken")] 
class ModalText extends TextArea {
    ...
}

In an MXML file, you can define the event and effect in an <mx:Metadata> block, as the following example shows:

<mx:Metadata>
    [Event(name="darken", type="flash.events.Event")]
    [Effect(name="darkenEffect", event="darken")]
</mx:Metadata>

Event metadata tag

Use the [Event] metadata tag to define the MXML property for an event and the data type of the event object that a component emits. You insert the [Event] metadata tag before the class definition in an ActionScript file, or in the <mx:Metadata> block in an MXML file.

For more information on defining custom events, see Custom Events.

The [Event] metadata tag has the following syntax:

[Event(name="eventName", type="package.eventType")]

The following table describes the properties of the [Event] metadata tag:

The following example identifies the myClickEvent event as an event that the component can dispatch:

[Event(name="myClickEvent", type="flash.events.Event")]

If you do not identify an event in the class file with the [Event] metadata tag, the MXML compiler generates an error if you try to use the event name in MXML. Any component can register an event listener for the event in ActionScript by using the addEventListener() method, even if you omit the [Event] metadata tag.

The following example identifies the myClickEvent event as an event that an ActionScript component can dispatch:

[Event(name="myEnableEvent", type="flash.events.Event")]
public class MyComponent extends UIComponent
{
    ...
}

The following example shows the [Event] metadata tag in the <mx:Metadata> tag in an MXML file:

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

    <mx:Metadata> 
        [Event(name="myEnableEvent", type="flash.events.Event")] 
    </mx:Metadata> 

    ....

</mx:TextArea>

IconFile metadata tag

Use the [IconFile] metadata tag to identify the filename for the icon that represents the component in the Insert bar of Flex Builder.

The [IconFile] metadata tag has the following syntax:

[IconFile("fileName")]

The fileName property specifies a PNG, GIF, or JPEG file that contains the icon, as the following example shows:

[IconFile("MyButton.png")]
public class MyButton extends Button
{
    ...
}

Inspectable metadata tag

The [Inspectable] metadata tag defines information about an attribute of your component that you expose in code hints and in the Property inspector area of Flex Builder. The [Inspectable] metadata tag is not required for either code hints or the Property inspector. The following rules determine how Flex Builder displays this information:

• All public properties in components appear in code hints and in the Flex Builder Property inspector. If you have extra information about the property that you want to add, such as enumeration values or that a String property represents a file path, add the [Inspectable] metadata tag with that information.
• Code hints for components and the information in the Property inspector come from the same data. Therefore, if the attribute appears in one, it should appear in the other.
• Code hints for ActionScript components do not require metadata to work correctly so that you always see the appropriate code hints, depending the current scope. Flex Builder uses the public, protected, private, and static keywords, plus the current scope, to determine which ActionScript code hints to show.

The [Inspectable] metadata tag must immediately precede the property's variable declaration or the setter and getter methods to be bound to that property. The [Inspectable] metadata tag has the following syntaxes:

[Inspectable(attribute=value[,attribute=value,...])]
property_declaration name:type; 
[Inspectable(attribute=value[,attribute=value,...])]
setter_getter_declarations; 

The following table describes the properties of the [Inspectable] metadata tag:

The following example defines the myProp parameter as inspectable:

[Inspectable(defaultValue=true, verbose=1, category="Other")]
public var myProp:Boolean;

InstanceType metadata tag

The [InstanceType] metadata tag specifies the allowed data type of a property of type IDeferredInstance, as the following example shows:

// Define a deferred property for the top component.
[InstanceType("mx.controls.Label")]
public var topRow:IDeferredInstance;

The Flex compiler validates that users assign values only of the specified type to the property. In this example, if the component user sets the topRow property to a value of a type other than mx.controls.Label, the compiler issues an error message.

You use the [InstanceType] metadata tag when creating template components. For more information, see Template Components.

The [InstanceType] metadata tag has the following syntax:

[InstanceType("package.className")]

You must specify a fully qualified package and class name.

NonCommittingChangeEvent metadata tag

The [NonCommittingChangeEvent] metadata tag identifies an event as an interim trigger, which means that the event should not invoke Flex data validators on the property. You use this tag for properties that might change often, but which you do not want to validate on every change.

An example of this is if you tied a validator to the text property of a TextInput control. The text property changes on every keystroke, but you do not want to validate the property until the user presses the Enter key or changes focus away from the field. The NonCommittingChangeEvent tag lets you dispatch a change event, but that does not trigger validation.

You insert the [NonCommittingChangeEvent] metadata tag before an ActionScript property definition or before a setter or getter method. The [NonCommittingChangeEvent] metadata tag has the following syntax:

[NonCommittingChangeEvent("event_name")]

In the following example, the component dispatches the change event every time the user enters a keystroke, but the change event does not trigger data binding or data validators. When the user completes data entry by pressing the Enter key, the component broadcasts the valueCommit event to trigger any data bindings and data validators:

[Event(name="change", type="flash.events.Event")]
class MyText extends UIComponent {
    ...

    [Bindable(event="valueCommit")]
    [NonCommittingChangeEvent("change")]
    function get text():String {
        return getText();
    }
    function set text(t):void {
        setText(t);
        // Dispatch events. 
    }
}

RemoteClass metadata tag

Use the [RemoteClass] metadata tag to register the class with Flex so that Flex preserves type information when a class instance is serialized by using Action Message Format (AMF). You insert the [RemoteClass] metadata tag before an ActionScript class definition. The [RemoteClass] metadata tag has the following syntax:

[RemoteClass]

You can also use this tag to represent a server-side Java object in a client application. You use the [RemoteClass(alias=" ")] metadata tag to create an ActionScript object that maps directly to the Java object. You specify the fully qualified class name of the Java class as the value of alias. For more information, see Accessing Server-Side Data with Flex.

Style metadata tag

Use the [Style] metadata tag to define the MXML tag attribute for a style property for the component. You insert the [Style] metadata tag before the class definition in an ActionScript file, or in the <mx:Metadata> block in an MXML file.

The [Style] metadata tag has the following syntax:

[Style(name="style_name"[,property="value",...])]

The following table describes the properties for the [Style] metadata tag:

The following example shows the definition of the textSelectedColor style property:

[Style(name="textSelectedColor",type="Number",format="Color",inherit="yes")]

The next example shows the definition of the verticalAlign style property:

[Style(name="verticalAlign", type="String", enumeration="bottom,middle,top", inherit="no")]

For more information on the [Style] metadata tag, see Custom Style Properties.

Transient metadata tag

Use the [Transient] metadata tag to identifies a property that should be omitted from data that is sent to the server when an ActionScript object is mapped to a Java object using the [RemoteClass] metadata tag.

The [Transient] metadata tag has the following syntax:

[Transient]
public var count:Number = 5;