Adding component metadata

You can add component metadata tags in your external ActionScript class files to tell the compiler about component parameters, data binding properties, and events. Metadata tags are used in the Flash authoring environment for a variety of purposes.

The metadata tags can only be used in external ActionScript class files. You cannot use metadata tags in FLA files.

Metadata is associated with a class declaration or an individual data field. If the value of an attribute is of type String, you must enclose that attribute in quotation marks.

Metadata statements are bound to the next line of the ActionScript file. When defining a component property, add the metadata tag on the line before the property declaration. The only exception is the Event metadata tag. When defining component events, add the metadata tag outside the class definition so that the event is bound to the entire class.

In the following example, the Inspectable tags apply to the flavorStr, colorStr, and shapeStr parameters:

[Inspectable(defaultValue="strawberry")]
public var flavorStr:String;
[Inspectable(defaultValue="blue")]
public var colorStr:String;
[Inspectable(defaultValue="circular")]
public var shapeStr:String;

In the Property inspector and the Parameters tab of the Component inspector, Flash displays all of these parameters as type String.

Metadata tags

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

The following sections describe the component metadata tags in more detail.

About the Inspectable tag

You use the Inspectable tag to specify the user-editable (inspectable) parameters that appear in the Component inspector and Property inspector. This lets you maintain the inspectable properties and the underlying ActionScript code in the same place. To see the component properties, drag an instance of the component onto the Stage and select the Parameters tab of the Component inspector.

Collection parameters are also inspectable. For more information, see About the Collection tag.

The following figure shows the Parameters tab of the Component inspector for the DateChooser component:

Alternatively, you can view a subset of the component properties on the Property inspector Parameters tab.

When determining which parameters to reveal in the authoring environment, Flash uses the Inspectable tag. The syntax for this tag is as follows:

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

The following example defines the enabled parameter as inspectable:

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

The Inspectable tag also supports loosely typed attributes like this:

[Inspectable("danger", 1, true, maybe)] 

The metadata statement must immediately precede the property's variable declaration in order to be bound to that property.

The following table describes the attributes of the Inspectable tag:

None of these attributes are required. You can simply have Inspectable as the metadata tag.

All properties of the superclass that are marked Inspectable are automatically inspectable in the current class. Use the InspectableList tag if you want to hide some of these properties for the current class.

About the InspectableList tag

Use the InspectableList tag to specify which subset of inspectable properties should appear in the Property inspector. Use InspectableList in combination with Inspectable so that you can hide inherited attributes for components that are subclasses. If you do not add an InspectableList tag to your component's class, all inspectable parameters, including those of the component's parent classes, appear in the Property inspector.

The InspectableList syntax is as follows:

[InspectableList("attribute1"[,...])]
// class definition

The InspectableList tag must immediately precede the class definition because it applies to the entire class.

The following example allows the flavorStr and colorStr properties to be displayed in the Property inspector, but excludes other inspectable properties from the Parent class:

[InspectableList("flavorStr","colorStr")]
class BlackDot extends DotParent {
   [Inspectable(defaultValue="strawberry")]
   public var flavorStr:String;
   [Inspectable(defaultValue="blue")]
   public var colorStr:String;
   ...
}

About the Event tag

Use the Event tag to define events that the component emits.

This tag has the following syntax:

[Event("event_name")]

For example, the following code defines a click event:

[Event("click")]

Add the Event statements outside the class definition in the ActionScript file so that the events are bound to the class and not a particular member of the class.

The following example shows the Event metadata for the UIObject class, which handles the resize, move, and draw events:

...
import mx.events.UIEvent;
[Event("resize")]
[Event("move")]
[Event("draw")]
class mx.core.UIObject extends MovieClip {
   ...
}

To broadcast a particular instance, call the dispatchEvent() method. See Using the dispatchEvent() method.

About the Bindable tag

Data binding connects components to each other. You achieve visual data binding through the Bindings tab of the Component inspector. From there, you add, view, and remove bindings for a component.

Although data binding works with any component, its main purpose is to connect user interface components to external data sources, such as web services and XML documents. These data sources are available as components with properties, which you can bind to other component properties.

Use the Bindable tag before a property in an ActionScript class to make the property appear in the Bindings tab in the Component inspector. You can declare a property by using var or getter/setter methods. If a property has both a getter and a setter method, you only need to apply the Bindable tag to one.

The Bindable tag has the following syntax:

[Bindable "readonly"|"writeonly",type="datatype"]

Both attributes are optional.

The following example defines the variable flavorStr as a property that is accessible on the Bindings tab of the Component inspector:

[Bindable]
public var flavorStr:String = "strawberry";

The Bindable tag takes three options that specify the type of access to the property, as well as the data type of that property. The following table describes these options:

[Bindable("readonly")]

[Bindable("writeonly")]

All properties of all components can participate in data binding. The Bindable tag merely controls which of those properties are available for binding in the Component inspector. If a property is not preceded by the Bindable tag, you can still use it for data binding, but you have to create the bindings using ActionScript.

The Bindable tag is required when you use the ChangeEvent tag. For more information, see About the ChangeEvent tag.

For information on creating data binding in the Flash authoring environment, see "Data binding (Flash Professional only)" in Using Flash.

About the ChangeEvent tag

The ChangeEvent tag tells data binding that the component will generate an event any time the value of a specific property changes. In response to the event, data binding executes any binding that has that property as a source. The component only generates the event if you write appropriate ActionScript code in the component. The event should be included in the list of Event metadata declared by the class.

You can declare a property by using var or getter/setter methods. If a property has both a getter and a setter method, you only need to apply the ChangeEvent tag to one.

The ChangeEvent tag has the following syntax:

[Bindable]
[ChangeEvent("event")]
property_declaration or getter/setter function

In the following example, the component generates the change event when the value of the bindable property flavorStr changes:

[Bindable]
[ChangeEvent("change")]
public var flavorStr:String;

When the event that is specified in the metadata occurs, Flash notifies bindings that the property has changed.

You can register multiple events in the tag, as the following example shows:

[ChangeEvent("change1", "change2", "change3")]

Any one of those events indicates a change to the property. They do not all have to occur to indicate a change.

About the Collection tag

Use the Collection tag to describe an array of objects that can be modified as a collection of items in the Values dialog box while authoring. The type of the objects is identified by the collectionItem attribute. A collection property contains a series of collection items that you define in a separate class. This class is either mx.utils.CollectionImpl or a subclass of it. The individual objects are accessed through the methods of the class identified by the collectionClass attribute.

A collection property in the Component inspector and the Values dialog box that appears when you click the magnifying glass.

The syntax for the Collection tag is as follows:

[Collection (name="name", variable="varname", collectionClass="mx.utils.CollectionImpl", collectionItem="coll-item-classname", identifier="string")] 
public var varname:mx.utils.Collection;

The following table describes the attributes of the Collection tag:

For more information, see Collection Properties.

About the IconFile tag

You can add an icon that represents your component in the Components panel of the Flash authoring environment. For more information, see Adding an icon.

Comments

Add Comment

Vani S said on Nov 9, 2004 at 2:01 PM :

The above example works if you don't have any set and get method.

if you use set and get methods you need to you the method name.

Ex:

[InspectableList("selectBackgroundColor","iconOffset")]
class Test {

public var backgroundColor:String;

[Inspectable(name="Icon Offset", verbose = 1,type=Boolean, defaultValue=true)]
public var iconOffset:Boolean=true;

[Inspectable(name="Background Color", verbose = 1, type=Color, defaultValue=0xFFFFFF)]
function set selectBackgroundColor(colorValue:Number) {
backgroundColor = colorValue;
}
function get selectBackgroundColor():Number {
return backgroundColor;
}

}

hope this helps,
t8design.com

Vani S said on Nov 9, 2004 at 2:13 PM :

in the above example
public var backgroundColor:Number

No screen name said on Jan 12, 2005 at 7:26 AM :

[Inspectable (name="Your Parameter",type="Object",defaultValue="value1:0,value2:"something"")]

Watch out: I found trouble using spaces in Inspectable tag, so don't use them.
Right now component documentation is really poor.

jelaplan said on May 11, 2005 at 10:52 AM :

I good article that augments this metatdata tag material is availalbe at: http://www.person13.com/articles/components/creatingcomponents.html

jepo said on Jun 9, 2005 at 2:30 PM :

Thank you for your comments. This site is for documentation feedback only. Some comments with general questions about how to use components, bug reports, or feature requests for the Flash product, have been removed. Please use the Flash webforums for questions about how to use components: http://webforums.macromedia.com/flash. Please use this form for feature requests or suspected bugs: www.macromedia.com/support/email/wishform/.

windylou said on Jul 22, 2005 at 3:43 PM :

i cannot install from cd help help thanks

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

Current page: http://livedocs.adobe.com/flash/mx2004/main_7_2/00003096.html

Add Comment