Metadata tags

If you want to replace one class with another, mark the class to be replaced with the [Alternative] metadata tag. The [Alternative] metadata tag specifies the replacement class, and a version number that indicates when the replacement occurred.

The [Alternative] metadata tag is not the same a the [Deprecated] metadata tag. When a class is deprecated, it might not work in a future release. A class marked by the [Alternative] metadata tag is still supported, but it indicates that there is an alternate to the class. For example, the MX Button class is marked with the [Alternative] metadata tag to indicate that you should use the Spark Button class instead.

Insert the [Alternative] metadata tag before the class definition of the class to be replaced. The [Alternative] metadata tag has the following syntax:

[Alternative(replacement="packageAndClassName", since="versionNum")]

The replacement option specifies the package and class name of the alternate class, and the since option specifies a version number.

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> 
        <fx:Number>94062</fx:Number> 
        <fx:Number>14850</fx:Number> 
        <fx:Number>53402</fx: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:

elementType

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 Data binding.

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.

A class or class element 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.

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 Custom 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 <fx: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:

eventNameEffect

eventName

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 <fx:Metadata> block, as the following example shows:

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

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 <fx: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:

eventName

eventType

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 <fx:Metadata> tag in an MXML file:

<?xml version="1.0"?> 
<!-- TextAreaEnabled.mxml --> 
<mx:TextArea xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
 
    <fx:Metadata> 
        [Event(name="myEnableEvent", type="flash.events.Event")] 
    </fx:Metadata> 
 
    .... 
 
</mx:TextArea>

Use the [HostComponent] metadata tag to identify the host component of a Spark skin class. The [HostComponent] metadata tag has the following syntax:

<Metadata> 
    [HostComponent(componentName)] 
</Metadata>

For example:

<Metadata> 
    [HostComponent("spark.components.Button")] 
</Metadata>

As a result of this metadata, Flex creates the property hostComponent on the skin class. You can then use this property to access public members of the host component’s instance from within the skin. For example, in a Button skin, you can access the Button’s style properties.

For more information, see Spark Skinning.

Use the [IconFile] metadata tag to identify the filename for the icon that represents the component in the Insert bar of Flash 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 
{ 
    ... 
}

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 Flash Builder. The [Inspectable] metadata tag is not required for either code hints or the Property inspector. The following rules determine how Flash Builder displays this information:

• All public properties in components appear in code hints and in the Flash 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. Flash 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:

category

defaultValue

enumeration

environment

format

listOffset

name

type

variable

verbose

The following example defines the myProp parameter as inspectable:

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

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 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.

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.  
    } 
}

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.

If a property is typed as a String, the compiler automatically tries to convert its value in MXML to a String. If the property is of a type such as *, Object, or Array, the compiler by default attempts to convert the value to an appropriate data type. Use the [RichTextContent] metadata tag to indicate that the value of a property in MXML should always be interpreted by the compiler as a String.

For example, the content property of the spark.components.TextArea and spark.primitives.RichText classes is typed as Object. However, these classes use the [RichTextContent] metadata tag to indicate that the value of the property in MXML should always be interpreted as a String.

<!-- Without [RichTextContent] metadata, interpret the value as type Number. --> 
<s:RichText> 
    <s:content>1</s:content> 
</s:RichText> 
 
<!-- Without [RichTextContent] metadata, interpret the value as type Array. --> 
<s:RichText> 
    <s:content>[1]</s:content> 
</s:RichText>

Data binding syntax, {}, and @ functions, such as @Resource and @Embed, are supported by properties that use the [RichTextContent] metadata tag.

You insert the [RichTextContent] metadata tag a property before a property definition in ActionScript. The [RichTextContent] metadata tag has the following syntax:

[RichTextContent]

Components can uses skins made up of skin parts. Use the [SkinPart] metadata tag to define a property of a component that corresponds to a skin part. Users of the component do not set the skin part properties directly. The component's skin sets the skin part properties.

[SkinPart(type="package.className", required="true_false")] 
/** 
* Optional ASDoc comment. 
*/  
Property definition

The type and required attributes are optional. The type attribute specifies the data type of the skin part, which determines whether the part is static or dynamic. The default value of type is determined by the data type of the property.

The required attribute specifies if the skin class must define the skin part. The default value of the required attribute is false.

SkinPart metadata is inherited by subclasses of the component.

For more information, see Spark Skinning.

The [SkinState] metadata tag defines the view states that a component’s skin must support. The tag goes outside the component’s class definition, and inside the package definition. The tag is inherited, but can be overridden in a subclass.

[SkinState("stateName")]

The following example defines two skin states for a component:

package spark.components.supportCl asses 
{ 
    /** 
    *  Optional ASDoc comment. */ 
    [SkinState("n ormal")] 
 
    /** 
    *  Optional ASDoc comment. */ 
    [SkinState("disabled")] 
 
    public class MyClass {}

For more information, see Spark Skinning.

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 <fx: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:

name

arrayType

enumeration

format

inherit

states

[Style(name="thumbSkin", type="Class", inherit="no", states="disabled, down, over, up")]

type

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.

Use the [SWF] metadata tag to specify attributes of the application when you write the main application file in ActionScript. Typically, you set these attributes by using the <s:Application> tag when you write the main application file in MXML.

The [SWF] tag has the following syntax:

[SWF(option="value"[,option="value",...])]

You can specify several options the [SWF] metadata tag. The following table describes these options:

frameRate

pageTitle

scriptRecursionLimit

scriptTimeLimit

For more information on these options, see Specifying options of the Application container.

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;