A metadata tag is an instruction to the compiler, written in square brackets on the
line before a class, a property or a method. It is not code: it does not run, and most
tags are dropped once the compiler has acted on them. The tags come from the Flex
compiler, which Flash authoring also uses for some of them, such as
[Embed].
Syntax
[Name]
[Name("value")]
[Name(key="value", key="value", …)]- A tag applies to the next definition: before
classfor a class tag, beforevar,constorfunction getfor a property tag, beforefunctionfor a method tag. - Several tags can stack on one definition.
- Values are strings in double quotes. A value without a key goes to the tag’s default argument, such as
sourcefor[Embed]. - Class tags such as
[Event]go inside the package block, directly before the class declaration. - Tags cannot be switched on and off with conditional compilation.
Which tags reach the SWF
The ABC format has room for metadata on every class, method and property, so a tag
can survive compilation and be read at run time by
flash.utils.describeType(). By default the Flex and AIR compilers keep only
[Bindable], [Managed], [ChangeEvent],
[NonCommittingChangeEvent] and [Transient]; the option
-keep-as3-metadata+=Name keeps others, which frameworks use for their own
tags such as [Inject]. See
Compiled bytecode.
[SWF]
On the main class of an ActionScript-only project, sets the properties of the SWF the compiler writes:
[SWF(width="800", height="600", frameRate="60", backgroundColor="#000000")]
public class Main extends Sprite {| Key | Meaning |
|---|---|
width, height | The stage size in pixels. |
widthPercent, heightPercent | The size as a percentage of the browser window, written with the %. |
frameRate | Frames per second; 24 if not given. |
backgroundColor | The stage colour, such as "#FFFFFF". |
pageTitle | The title for the browser’s title bar. |
scriptRecursionLimit | The deepest call stack allowed; 1000 if not given. |
scriptTimeLimit | Seconds a handler may run before it is stopped; 60 at most. |
In Flash authoring these come from the document’s properties and publish settings instead.
[Frame]
[Frame(factoryClass="com.example.Preloader")]
public class Main extends Sprite {Makes the Flex compiler write a two-frame SWF: the named factory class on frame 1,
and this class with everything it uses on frame 2. The factory shows progress while the
rest downloads, then creates the main class by name. The Flex framework itself starts
applications this way. ActionScript Compiler 2.0 is reported not to support the tag,
though its -frame option does the same.
[Embed]
Puts a file into the SWF at compile time and gives the code a class for it. The tag
goes on a Class variable, usually static; creating an
instance of the class gives the asset.
[Embed(source="../assets/logo.png")]
private static const Logo:Class;
[Embed(source="../assets/click.mp3")]
private static const ClickSound:Class;
[Embed(source="../assets/level1.xml", mimeType="application/octet-stream")]
private static const Level1:Class;
[Embed(source="../assets/ui.swf", symbol="PlayButton")]
private static const PlayButton:Class;
var logo:Bitmap = new Logo();
var click:Sound = new ClickSound();
var level:XML = XML(new Level1()); // a ByteArray of the file’s bytes| Asset | MIME type | The class extends |
|---|---|---|
| GIF, JPEG, PNG | image/gif, image/jpeg, image/png | mx.core.BitmapAsset, a Bitmap |
| SVG | image/svg | mx.core.SpriteAsset |
| MP3 | audio/mpeg | mx.core.SoundAsset, a Sound |
| A whole SWF | application/x-shockwave-flash | mx.core.MovieClipAsset |
| A symbol from a SWF | application/x-shockwave-flash | SpriteAsset for one frame, MovieClipAsset for more |
| TrueType or OpenType font | application/x-font, application/x-font-truetype | A Font, registered under fontName |
| Anything else | application/octet-stream | mx.core.ByteArrayAsset, a ByteArray |
| Key | Meaning |
|---|---|
source | The file, relative to the .as file or absolute; the default key. Web addresses are not allowed. |
mimeType | Overrides the type guessed from the extension. |
symbol | A symbol exported from the SWF given as source. |
compression, quality | Compress a GIF or PNG when it is stored, at a quality from 0 to 100; lower is smaller. |
smoothing | Smooth the bitmap when it is scaled. |
scaleGridTop, scaleGridBottom, scaleGridLeft, scaleGridRight | Nine-slice scaling lines, in pixels. |
fontName, fontFamily, fontWeight, fontStyle, unicodeRange, embedAsCFF | For fonts: the name to register, which face, which characters, and whether to store it for the Flash Text Engine (CFF) or for TextField. |
The mx.core asset classes are small, and the compiler links them from the
SDK even into projects that do not use the Flex framework. In Flash authoring the same is done by giving a library item a class
name for export.
[Event]
[Event(name="scoreChanged", type="com.example.events.ScoreEvent")]
public class Scoreboard extends Sprite {Declares that the class dispatches an event of that name and class (the type with its package). It does not dispatch anything itself; editors use it for code hints, ASDoc lists it, and in MXML it lets the event be set as an attribute.