| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE html |
| PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html lang="en-us" xml:lang="en-us"> |
| <head> |
| <meta name="DC.Type" content="topic"/> |
| <meta name="DC.Title" content="Metadata tags in custom components"/> |
| <meta name="DC.Format" content="XHTML"/> |
| <meta name="DC.Identifier" content="WS2db454920e96a9e51e63e3d11c0bf69084-7fe9_verapache"/> |
| <title>Metadata tags in custom components</title> |
| </head> |
| <body id="WS2db454920e96a9e51e63e3d11c0bf69084-7fe9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7fe9_verapache"><!-- --></a> |
| |
| <div> |
| <p>You insert metadata tags into your MXML and ActionScript |
| files to provide information to the Flex compiler. |
| Metadata tags do not get compiled into executable code, but provide |
| information to control how portions of your code get compiled. </p> |
| |
| <p>For more information about additional metadata tags that you |
| use when creating an application, such as the<samp class="codeph">[Embed]</samp>metadata |
| tag, see <a href="flx_embed_em.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fce_verapache">Embedding assets</a>.</p> |
| |
| </div> |
| |
| <div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ab2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ab2_verapache"><!-- --></a> |
| <h2 class="topictitle2">About metadata tags</h2> |
| |
| |
| <div> |
| <p>Metadata |
| tags provide information to the compiler that describes how your components |
| are used in an application. For example, you might create a component |
| that defines a new event. To make that event known to the Flex compiler |
| so that you can reference it in MXML, you insert the <samp class="codeph">[Event]</samp> metadata tag |
| into your component, as the following ActionScript class definition |
| shows:</p> |
| |
| <pre class="codeblock"> [Event(name="enableChanged", type="flash.events.Event")] |
| class ModalText extends TextArea { |
| ... |
| }</pre> |
| |
| <p>In this example, the <samp class="codeph">[Event]</samp> metadata tag specifies |
| the event name and the class that defines the type of the event |
| object dispatched by the event. After you identify the event to |
| the compiler, you can reference it in MXML, as the following example |
| shows:</p> |
| |
| <pre class="codeblock"> <?xml version="1.0"?> |
| <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" |
| xmlns:s="library://ns.adobe.com/flex/spark" |
| xmlns:mx="library://ns.adobe.com/flex/mx" xmlns:MyComp="*"> |
| |
| <fx:Script> |
| <![CDATA[ |
| <strong>function handleEnableChangeEvent(eventObj:Event):void {</strong> |
| ... |
| <strong>}</strong> |
| ]]> |
| </fx:Script> |
| |
| <strong><MyComp:ModalText enableChanged="handleEnableChangeEvent(event);"/></strong> |
| </s:Application></pre> |
| |
| <p>If you omit the <samp class="codeph">[Event]</samp> metadata tag from your |
| class definition, Flex issues a syntax error when it compiles your |
| MXML file. The error message indicates that Flex does not recognize |
| the <samp class="codeph">enableChanged</samp> property.</p> |
| |
| <p>The Flex compiler recognizes |
| component metadata statements in your ActionScript class files and |
| MXML files. The metadata tags define component attributes, data |
| binding properties, events, and other properties of the component. |
| Flex interprets these statements during compilation; they are never |
| interpreted during run time. </p> |
| |
| <p>Metadata statements are associated with a class declaration, |
| an individual data field, or a method. They are bound to the next |
| line in the file. When you define a component property or method, |
| add the metadata tag on the line before the property or method declaration. </p> |
| |
| </div> |
| |
| <div class="nested2" id="WS4b4ddee4904fe779a3910cb1219d2ce3ac-8000_verapache"><a name="WS4b4ddee4904fe779a3910cb1219d2ce3ac-8000_verapache"><!-- --></a> |
| <h3 class="topictitle3">Metadata tags in ActionScript</h3> |
| |
| |
| <div> |
| <p>In an ActionScript file, when you |
| define component events or other aspects of a component that affect |
| more than a single property, you add the metadata tag outside the |
| class definition so that the metadata is bound to the entire class, |
| as the following example shows: </p> |
| |
| <pre class="codeblock"> <strong>// Add the [Event] metadata tag outside of the class file.</strong> |
| <strong>[Event(name="enableChange", type="flash.events.Event")]</strong> |
| public class ModalText extends TextArea { |
| |
| ... |
| |
| // Define class properties/methods |
| private var _enableTA:Boolean; |
| |
| <strong>// Add the [Inspectable] metadata tag before the individual property.</strong> |
| <strong>[Inspectable(defaultValue="false")]</strong> |
| public function set enableTA(val:Boolean):void { |
| _enableTA = val; |
| this.enabled = val; |
| |
| // Define event object, initialize it, then dispatch it. |
| var eventObj:Event = new Event("enableChange"); |
| dispatchEvent(eventObj); |
| } |
| }</pre> |
| |
| <p>In this example, you add the <samp class="codeph">[Event]</samp> metadata |
| tag before the class definition to indicate that the class dispatches |
| an event named <samp class="codeph">enableChanged</samp>. For more information |
| on using this tag, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a21_verapache">Inspectable |
| metadata tag</a>.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS4b4ddee4904fe779a3910cb1219d2ce3ac-7fff_verapache"><a name="WS4b4ddee4904fe779a3910cb1219d2ce3ac-7fff_verapache"><!-- --></a> |
| <h3 class="topictitle3">Metadata tags in MXML</h3> |
| |
| |
| <div> |
| <p>In an MXML file, you insert the metadata tags either in |
| an <samp class="codeph"><fx:Script></samp> block along with your ActionScript |
| code, or in an <samp class="codeph"><fx:Metadata></samp> block, as the following |
| example shows:</p> |
| |
| <pre class="codeblock"> <?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"> |
| |
| <strong><fx:Metadata></strong> |
| <strong>[Event(name="enableChange", type="flash.events.Event")]</strong> |
| <strong></fx:Metadata></strong> |
| |
| <fx:Script> |
| <![CDATA[ |
| |
| // Import Event class. |
| import flash.events.Event; |
| |
| // Define class properties and methods. |
| private var _enableTA:Boolean; |
| |
| <strong>// Add the [Inspectable] metadata tag before the individual property.</strong> |
| <strong>[Inspectable(defaultValue="false")]</strong> |
| public function set enableTA(val:Boolean):void { |
| _enableTA = val; |
| this.enabled = val; |
| |
| // Define event object, initialize it, then dispatch it. |
| var eventObj:Event = new Event("enableChange"); |
| dispatchEvent(eventObj); |
| } |
| ]]> |
| </fx:Script> |
| </mx:TextArea></pre> |
| |
| <p>A key difference between the <samp class="codeph"><fx:Metadata></samp> and <samp class="codeph"><fx:Script></samp> tags |
| is that text within the <samp class="codeph"><fx:Metadata></samp> tag |
| is inserted before the generated class declaration, but text within <samp class="codeph"><fx:Script></samp> tag |
| is inserted in the body of the generated class declaration. Therefore, |
| metadata tags like <samp class="codeph">[Event]</samp> and <samp class="codeph">[Effect]</samp> must |
| go in an <samp class="codeph"><fx:Metadata></samp> tag, but the <samp class="codeph">[Bindable]</samp> and <samp class="codeph">[Embed]</samp> metadata |
| tags must go in an <samp class="codeph"><fx:Script></samp> tag.</p> |
| |
| </div> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf680e1-7ffe_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf680e1-7ffe_verapache"><!-- --></a> |
| <h2 class="topictitle2">Metadata tags</h2> |
| |
| |
| <div> |
| <p>The following table describes |
| the metadata tags that you can use in ActionScript class files: </p> |
| |
| |
| <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"> |
| |
| |
| <thead align="left"> |
| <tr> |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e266"> |
| <p>Tag</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e272"> |
| <p>Description</p> |
| |
| </th> |
| |
| </tr> |
| |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[Alternative]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Specifies a replacement class for an existing |
| class, and a version number that indicates when the replacement |
| occurred. For more information, see <a href="flx_metadata_me.html#WSccb96ffde9c4284e8cf0e2a121a112b38d-8000_verapache">Alternative |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[ArrayElementType]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Defines the allowed data type of each element |
| of an Array. For more information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a2c_verapache">ArrayElementType |
| metadata tag</a>. </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| |
| |
| <samp class="codeph">[Bindable]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Identifies a property that you can use as |
| the source of a data binding expression. For more information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a2a_verapache">Bindable |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <div class="p"> |
| <pre class="codeblock">[DefaultProperty]</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Defines the name of the default property |
| of the component when you use the component in an MXML file. For |
| more information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a29_verapache">DefaultProperty |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[Deprecated]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Marks a class or class element as deprecated |
| so that the compiler can recognize it and issue a warning when the |
| element is used in an application. For more information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a6c_verapache">Deprecated |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| |
| <samp class="codeph">[Effect]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Defines the MXML property name for the effect. |
| For more information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a27_verapache">Effect |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| |
| |
| |
| <samp class="codeph">[Embed]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Imports JPEG, GIF, PNG, SVG, and SWF files |
| at compile time. Also imports image assets from SWC files.</p> |
| |
| <p>This |
| is functionally equivalent to the MXML <samp class="codeph">@Embed</samp> syntax, |
| as described in <a href="flx_embed_em.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fce_verapache">Embedding |
| assets</a>. </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| |
| |
| <samp class="codeph">[Event]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Defines the MXML property for an event and |
| the data type of the event object that a component emits. For more |
| information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a24_verapache">Event |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[Exclude]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Omits an inherited class element from the |
| Flash Builder tag inspector. The syntax is as follows:</p> |
| |
| <div class="p"> |
| <pre class="codeblock">[Exclude(name="label", kind="property")]</pre> |
| |
| </div> |
| |
| <p>Where <samp class="codeph">kind</samp> can |
| be <samp class="codeph">property</samp>, <samp class="codeph">method</samp>, <samp class="codeph">event</samp>, |
| or <samp class="codeph">style</samp>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[ExcludeClass]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Omits the class from the Flash Builder tag |
| inspector. This is equivalent to the <samp class="codeph">@private</samp> tag |
| in ASDoc when applied to a class. </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[HostComponent]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Specifies the host component for a Spark |
| skin class. For more information, see <a href="flx_metadata_me.html#WS8fdf84466d28f0b0-6fc09fae121f39ef56b-8000_verapache">HostComponent |
| metadata tag</a> |
| </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| |
| <samp class="codeph">[IconFile]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Identifies the filename for the icon that |
| represents the component in the Insert bar of Adobe<sup>®</sup> Flash<sup>®</sup> Builder<sup>®</sup>. |
| For more information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a23_verapache">IconFile |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| |
| <samp class="codeph">[Inspectable]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Defines an attribute exposed to component |
| users in the attribute hints and Tag inspector of Flash Builder. |
| Also limits allowable values of the property. For more information, |
| see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a21_verapache">Inspectable |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[InstanceType]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Specifies the allowed data type of a property |
| of type IDeferredInstance. For more information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a1d_verapache">InstanceType |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| |
| <samp class="codeph">[NonCommittingChangeEvent]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Identifies an event as an interim trigger. |
| For more information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a1b_verapache">NonCommittingChangeEvent |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[RemoteClass]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Maps the ActionScript object to a Java object. |
| For more information on using the <samp class="codeph">[RemoteClass]</samp> metadata |
| tag, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a25_verapache">RemoteClass |
| metadata tag</a>. </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[RichTextContent]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Indicate that the value of a property in |
| MXML should always be interpreted by the compiler as a String. For |
| more information, see <a href="flx_metadata_me.html#WSccb96ffde9c4284e978649121a0df15e8-8000_verapache">RichTextContent |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[SkinPart]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Define a property of a component that corresponds |
| to a skin part. For more information, see <a href="flx_metadata_me.html#WSed21e2b297da693f52150838121df2b8ad7-8000_verapache">SkinPart |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[SkinState]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Defines the view states that a component's |
| skin must support. For more information, see <a href="flx_metadata_me.html#WSed21e2b297da693f52150838121df2b8ad7-7fff_verapache">SkinState |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| |
| |
| <samp class="codeph">[Style]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Defines the MXML property for a style property |
| for the component. For more information on using the <samp class="codeph">[Style]</samp> metadata |
| tag, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a1a_verapache">Style |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[SWF]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>Specifies attributes of the application |
| when you write the main application file in ActionScript. For more |
| information, see <a href="flx_metadata_me.html#WS4b4ddee4904fe7796d38fa291219d46bcb4-8000_verapache">SWF |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e266 "> |
| <p> |
| <samp class="codeph">[Transient]</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e272 "> |
| <p>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 <samp class="codeph">[RemoteClass]</samp>. |
| For more information, see <a href="flx_metadata_me.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a19_verapache">Transient |
| metadata tag</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WSccb96ffde9c4284e8cf0e2a121a112b38d-8000_verapache"><a name="WSccb96ffde9c4284e8cf0e2a121a112b38d-8000_verapache"><!-- --></a> |
| <h3 class="topictitle3">Alternative metadata tag</h3> |
| |
| |
| <div> |
| <p>If you want to replace one class with another, mark the |
| class to be replaced with the <samp class="codeph">[Alternative]</samp> metadata |
| tag. The <samp class="codeph">[Alternative]</samp> metadata tag specifies the |
| replacement class, and a version number that indicates when the replacement |
| occurred. </p> |
| |
| <p>The <samp class="codeph">[Alternative]</samp> metadata tag is not the same |
| a the <samp class="codeph">[Deprecated]</samp> metadata tag. When a class is |
| deprecated, it might not work in a future release. A class marked |
| by the <samp class="codeph">[Alternative]</samp> 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 <samp class="codeph">[Alternative]</samp> metadata |
| tag to indicate that you should use the Spark Button class instead.</p> |
| |
| <p>Insert the <samp class="codeph">[Alternative]</samp> metadata tag before |
| the class definition of the class to be replaced. The <samp class="codeph">[Alternative]</samp> metadata |
| tag has the following syntax:</p> |
| |
| <pre class="codeblock"> [Alternative(replacement="<em>packageAndClassName</em>", since="<em>versionNum</em>")]</pre> |
| |
| <p>The <samp class="codeph">replacement</samp> option specifies the package |
| and class name of the alternate class, and the <samp class="codeph">since</samp> option |
| specifies a version number.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a2c_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a2c_verapache"><!-- --></a> |
| <h3 class="topictitle3">ArrayElementType metadata tag</h3> |
| |
| |
| <div> |
| <p>When you define an Array variable in ActionScript, you |
| specify <samp class="codeph">Array</samp> as the data type of the variable. |
| However, you cannot specify the data type of the elements of the |
| Array. </p> |
| |
| <p>To allow the Flex MXML compiler to perform type checking on Array |
| elements, you can use the <samp class="codeph">[ArrayElementType]</samp> metadata |
| tag to specify the allowed data type of the Array elements, as the |
| following example shows:</p> |
| |
| <pre class="codeblock"> public class MyTypedArrayComponent extends VBox { |
| |
| <strong>[ArrayElementType("String")]</strong> |
| public var newStringProperty:Array; |
| |
| <strong>[ArrayElementType("Number")]</strong> |
| public var newNumberProperty:Array; |
| ... |
| } </pre> |
| |
| <div class="note"><span class="notetitle">Note:</span> The MXML compiler checks for proper usage of |
| the Array only in MXML code; it does not check Array usage in ActionScript |
| code. </div> |
| |
| <p>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:</p> |
| |
| <pre class="codeblock"> <MyComp:MyTypedArrayComponent> |
| <MyComp:newStringProperty> |
| <fx:Number>94062</fx:Number> |
| <fx:Number>14850</fx:Number> |
| <fx:Number>53402</fx:Number> |
| </MyComp:newStringProperty> |
| </MyComp:MyTypedArrayComponent></pre> |
| |
| <p>In this example, you try to use Number objects to initialize |
| the Array, so the compiler issues an error.</p> |
| |
| <p>You can also specify Array properties as tag attributes, rather |
| than using child tags, as the following example shows: </p> |
| |
| <pre class="codeblock"> <MyComp:MyTypedArrayComponent newNumberProperty="[abc,def]"/></pre> |
| |
| <p>This MXML code generates an error because Flex cannot convert |
| the Strings "<samp class="codeph">abc</samp>" and "<samp class="codeph">def</samp>" to |
| a Number. </p> |
| |
| <p>You insert the <samp class="codeph">[ArrayElementType]</samp> metadata tag |
| before the variable definition. The tag has the following syntax: </p> |
| |
| <pre class="codeblock"> [ArrayElementType("<em>elementType</em>")]</pre> |
| |
| <p>The following table describes the property of the <samp class="codeph">[ArrayElementType]</samp> metadata |
| tag:</p> |
| |
| |
| <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"> |
| |
| |
| |
| <thead align="left"> |
| <tr> |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e1005"> |
| <p>Property</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e1011"> |
| <p>Type</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e1017"> |
| <p>Description</p> |
| |
| </th> |
| |
| </tr> |
| |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1005 "> |
| <div class="p"> |
| <pre class="codeblock">elementType</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1011 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1017 "> |
| <p>Specifies the data type of the Array elements, |
| and can be one of the ActionScript data types, such as String, Number, |
| class, or interface.</p> |
| |
| <p>You must specify the type as a fully |
| qualified class name, including the package. </p> |
| |
| </td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a2a_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a2a_verapache"><!-- --></a> |
| <h3 class="topictitle3">Bindable metadata tag</h3> |
| |
| |
| <div> |
| <p>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 <samp class="codeph">[Bindable]</samp> metadata |
| tag to register the property with Flex, and the source property |
| must dispatch an event. </p> |
| |
| <p>The <samp class="codeph">[Bindable]</samp> metadata tag has the following |
| syntax:</p> |
| |
| <pre class="codeblock"> [Bindable] |
| [Bindable(event="<em>eventname</em>")]</pre> |
| |
| <p>If you omit the event name, Flex automatically creates an event |
| named <samp class="codeph">propertyChange</samp>.</p> |
| |
| <p>For more information on data binding and on this metadata tag, |
| see <a href="flx_databinding_db.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fe7_verapache">Data binding</a>.</p> |
| |
| </div> |
| |
| <div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf680e1-7ff2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf680e1-7ff2_verapache"><!-- --></a> |
| <h4 class="topictitle4">Working with bindable property |
| chains</h4> |
| |
| |
| <div> |
| <p>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 <em>bindable property chain</em>. |
| In the following example, <samp class="codeph">firstName.text</samp> is a bindable |
| property chain that includes both a <samp class="codeph">firstName</samp> object |
| and its <samp class="codeph">text</samp> property:</p> |
| |
| <pre class="codeblock"> <first>{<strong>firstName.text</strong>}</first></pre> |
| |
| <p>You should raise an event when any named property in a bindable |
| property chain changes. If the property is marked with the <samp class="codeph">[Bindable]</samp> metadata |
| tag, the Flex compiler generates the event for you.</p> |
| |
| <p>The following example uses the <samp class="codeph">[Bindable]</samp> metadata |
| tag for a variable and a getter property. The example also shows |
| how to call the <samp class="codeph">dispatchEvent()</samp> function.</p> |
| |
| <pre class="codeblock"> <strong>[Bindable]</strong> |
| public var minFontSize:Number = 5; |
| |
| <strong>[Bindable("textChanged")]</strong> |
| public function get text():String { |
| return myText; |
| } |
| |
| public function set text(t : String):void { |
| myText = t; |
| dispatchEvent( new Event( "textChanged" ) );}</pre> |
| |
| <p>If you omit the event name in the <samp class="codeph">[Bindable]</samp> metadata |
| tag, the Flex compiler automatically generates and dispatches an |
| event named <samp class="codeph">propertyChange</samp> so that the property |
| can be used as the source of a data binding expression.</p> |
| |
| <p>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 <samp class="codeph">myList</samp> List control contains Customer |
| objects, so the <samp class="codeph">selectedItem</samp> property is cast to |
| a Customer object:</p> |
| |
| <pre class="codeblock"> <fx:Model id="selectedCustomer"> |
| <customer> |
| <name>{Customer(myList.selectedItem).name}</name> |
| <address>{Customer(myList.selectedItem).address}</address> |
| ... |
| </customer> |
| </fx:Model></pre> |
| |
| <p>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 <samp class="codeph">dataProvider</samp> property, as the |
| following example shows:</p> |
| |
| <pre class="codeblock"> dataProvider[i] = newItem</pre> |
| |
| <p>Binding also does not execute automatically for subproperties |
| of properties that have <samp class="codeph">[Bindable]</samp> metadata, as |
| the following example shows:</p> |
| |
| <pre class="codeblock"> ... |
| [Bindable] |
| var temp; |
| // Binding is triggered: |
| temp = new Object(); |
| // Binding is <strong>not</strong> triggered, because label not a bindable property |
| // of Object: |
| temp.label = foo; |
| ...</pre> |
| |
| <p>In this code example, the problem with <samp class="codeph">{temp.label}</samp> is |
| that temp is an Object. You can solve this problem in one of the |
| following ways:</p> |
| |
| <ul> |
| <li> |
| <p>Preinitialize the Object.</p> |
| |
| </li> |
| |
| <li> |
| <p>Assign an ObjectProxy to <samp class="codeph">temp</samp>; all of an |
| ObjectProxy's properties are bindable.</p> |
| |
| </li> |
| |
| <li> |
| <p>Make <samp class="codeph">temp</samp> a strongly typed object with a <samp class="codeph">label</samp> property |
| that is bindable. </p> |
| |
| </li> |
| |
| </ul> |
| |
| <p>Binding also does not execute automatically when you are binding |
| data to a property that Flash Player updates automatically, such |
| as the <samp class="codeph">mouseX</samp> property.</p> |
| |
| <p>The <samp class="codeph">executeBindings()</samp> 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 <samp class="codeph">executeChildBindings()</samp> 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.</p> |
| |
| <p>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 <samp class="codeph">executeChildBindings()</samp> method, |
| you can update the user interface after making a change that does |
| not cause bindings to execute. However, you should only use the <samp class="codeph">executeBindings()</samp> method |
| when you are sure that bindings do not execute automatically. </p> |
| |
| </div> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a29_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a29_verapache"><!-- --></a> |
| <h3 class="topictitle3">DefaultProperty metadata tag</h3> |
| |
| |
| <div> |
| <p>The <samp class="codeph">[DefaultProperty]</samp> metadata |
| tag defines the name of the default property of the component when |
| you use the component in an MXML file.</p> |
| |
| <p>The <samp class="codeph">[DefaultProperty]</samp> metadata tag has the following |
| syntax:</p> |
| |
| <pre class="codeblock"> [DefaultProperty("<em>propertyName</em>")]</pre> |
| |
| <p>The <em>propertyName</em> property specifies the name of the default |
| property.</p> |
| |
| <p>You can use the <samp class="codeph">[DefaultProperty]</samp> metadata tag |
| in your ActionScript component to define a single default property. |
| For more information and an example, see <a href="flx_ascomponents_as.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a1c_verapache">Creating |
| a default property</a>.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a6c_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a6c_verapache"><!-- --></a> |
| <h3 class="topictitle3">Deprecated metadata tag</h3> |
| |
| |
| <div> |
| <p>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. </p> |
| |
| <p>The mxmlc command-line compiler supports the <samp class="codeph">show-deprecation-warnings</samp> compiler |
| option, which, when <samp class="codeph">true</samp>, configures the compiler |
| to issue deprecation warnings when your application uses deprecated |
| elements. The default value is <samp class="codeph">true</samp>. </p> |
| |
| <p>Insert the <samp class="codeph">[Deprecated]</samp> metadata tag before |
| a property, method, or class definition to mark that element as |
| deprecated. The <samp class="codeph">[Deprecated]</samp> metadata tag has the |
| following options for its syntax when used with a class, property |
| or method:</p> |
| |
| <pre class="codeblock"> [Deprecated("<em>string_describing_deprecation</em>")] |
| [Deprecated(message="<em>string_describing_deprecation</em>")] |
| [Deprecated(replacement="<em>string_specifying_replacement</em>")] |
| [Deprecated(replacement="<em>string_specifying_replacement</em>", since="<em>version_of_replacement</em>")]</pre> |
| |
| <p>The following uses the <samp class="codeph">[Deprecated]</samp> metadata |
| tag to mark the <samp class="codeph">dataProvider</samp> property as obsolete:</p> |
| |
| <pre class="codeblock"> [Deprecated(replacement="MenuBarItem.data")] |
| public function set dataProvider(value:Object):void |
| { |
| ... |
| }</pre> |
| |
| <p>The <samp class="codeph">[Event]</samp>, <samp class="codeph">[Effect]</samp> and <samp class="codeph">[Style]</samp> metadata |
| tags also support deprecation. These tags support the following |
| options for syntax:</p> |
| |
| <pre class="codeblock"> [Event(... , <strong>deprecatedMessage</strong>="<em>string_describing_deprecation</em>")] |
| [Event(... , <strong>deprecatedReplacement</strong>="change2")] |
| [Event(... , <strong>deprecatedReplacement</strong>="<em>string_specifying_replacement</em>", <strong>deprecatedSince</strong>="<em>version_of_replacement</em>")]</pre> |
| |
| <p>These metadata tags support the <samp class="codeph">deprecatedReplacement</samp> and <samp class="codeph">deprecatedSince</samp> attributes |
| to mark the event, effect, or style as deprecated.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a27_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a27_verapache"><!-- --></a> |
| <h3 class="topictitle3">Effect metadata tag</h3> |
| |
| |
| <div> |
| <p>The <samp class="codeph">[Effect]</samp> 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 <samp class="codeph">[Effect]</samp> metadata |
| tag to specify that property to the Flex compiler.</p> |
| |
| <p>For more information on defining custom effects, see <a href="flx_createeffects_cfx.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fc8_verapache">Custom |
| effects</a>. </p> |
| |
| <p>An effect is paired with a trigger that invokes the effect. A <em>trigger</em> is |
| an event, such as a mouse click on a component, a component getting |
| focus, or a component becoming visible. An <em>effect</em> is a visible |
| or audible change to the component that occurs over a period of |
| time. </p> |
| |
| <p>You insert the <samp class="codeph">[Effect]</samp> metadata tag before |
| the class definition in an ActionScript file or in the <samp class="codeph"><fx:Metadata></samp> block |
| in an MXML file. The <samp class="codeph">[Effect]</samp> metadata tag has |
| the following syntax:</p> |
| |
| <pre class="codeblock"> [Effect(name="<em>eventName</em>Effect", event="<em>eventName</em>")]</pre> |
| |
| <p>The following table describes the properties of the <samp class="codeph">[Effect]</samp> metadata |
| tag:</p> |
| |
| |
| <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"> |
| |
| |
| |
| <thead align="left"> |
| <tr> |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e1513"> |
| <p>Property</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e1519"> |
| <p>Type</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e1525"> |
| <p>Description</p> |
| |
| </th> |
| |
| </tr> |
| |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1513 "> |
| <div class="p"> |
| <pre class="codeblock"><samp class="codeph">eventNameEffect</samp></pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1519 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1525 "> |
| <p>Specifies the name of the effect.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1513 "> |
| <div class="p"> |
| <pre class="codeblock">eventName</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1519 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1525 "> |
| <p>Specifies the name of the event that triggers |
| the effect.</p> |
| |
| </td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| <p>The <samp class="codeph">[Effect]</samp> metadata tag is often paired with |
| an <samp class="codeph">[Event]</samp> metadata tag, where the <samp class="codeph">[Event]</samp> 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 <samp class="codeph">Effect</samp>, |
| as the following example of an ActionScript file shows:</p> |
| |
| <pre class="codeblock"> // Define event corresponding to the effect trigger. |
| [Event(name="darken", type="flash.events.Event")] |
| // Define the effect. |
| <strong>[Effect(name="darkenEffect", event="darken")]</strong> |
| class ModalText extends TextArea { |
| ... |
| }</pre> |
| |
| <p>In an MXML file, you can define the event and effect in an <samp class="codeph"><fx:Metadata></samp> block, |
| as the following example shows: </p> |
| |
| <pre class="codeblock"> <fx:Metadata> |
| [Event(name="darken", type="flash.events.Event")] |
| [Effect(name="darkenEffect", event="darken")] |
| </fx:Metadata></pre> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a24_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a24_verapache"><!-- --></a> |
| <h3 class="topictitle3">Event metadata tag</h3> |
| |
| |
| <div> |
| <p>Use the <samp class="codeph">[Event]</samp> 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 <samp class="codeph"><fx:Metadata></samp> block |
| in an MXML file. </p> |
| |
| <p>For more information on defining custom events, see <a href="flx_createevents_cre.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a22_verapache">Custom |
| events</a>. </p> |
| |
| <p>The <samp class="codeph">[Event]</samp> metadata tag has the following syntax:</p> |
| |
| <pre class="codeblock"> [Event(name="<em>eventName</em>", type=<em>"package.eventType"</em>)]</pre> |
| |
| <p>The following table describes the properties of the <samp class="codeph">[Event]</samp> metadata |
| tag:</p> |
| |
| |
| <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"> |
| |
| |
| |
| <thead align="left"> |
| <tr> |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e1696"> |
| <p>Property</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e1702"> |
| <p>Type</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e1708"> |
| <p>Description</p> |
| |
| </th> |
| |
| </tr> |
| |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1696 "> |
| <div class="p"> |
| <pre class="codeblock"><samp class="codeph">eventName</samp></pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1702 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1708 "> |
| <p>Specifies the name of the event.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1696 "> |
| <div class="p"> |
| <pre class="codeblock">eventType</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1702 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e1708 "> |
| <p>Specifies the package and class that defines |
| the data type of the event object. It is either the base event class, |
| Event, or a subclass of the Event class. You must include the package |
| in the class name.</p> |
| |
| </td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| <p>The following example identifies the <samp class="codeph">myClickEvent</samp> event |
| as an event that the component can dispatch:</p> |
| |
| <pre class="codeblock"> [Event(name="myClickEvent", type="flash.events.Event")]</pre> |
| |
| <p>If you do not identify an event in the class file with the <samp class="codeph">[Event]</samp> 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 <samp class="codeph">addEventListener()</samp> method, |
| even if you omit the <samp class="codeph">[Event]</samp> metadata tag.</p> |
| |
| <p>The following example identifies the <samp class="codeph">myClickEvent</samp> event |
| as an event that an ActionScript component can dispatch:</p> |
| |
| <pre class="codeblock"> [Event(name="myEnableEvent", type="flash.events.Event")] |
| public class MyComponent extends UIComponent |
| { |
| ... |
| }</pre> |
| |
| <p>The following example shows the <samp class="codeph">[Event]</samp> metadata |
| tag in the <samp class="codeph"><fx:Metadata></samp> tag in an MXML file:</p> |
| |
| <pre class="codeblock"> <?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"> |
| |
| <strong><fx:Metadata></strong> |
| <strong>[Event(name="myEnableEvent", type="flash.events.Event")]</strong> |
| <strong></fx:Metadata></strong> |
| |
| .... |
| |
| </mx:TextArea></pre> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS8fdf84466d28f0b0-6fc09fae121f39ef56b-8000_verapache"><a name="WS8fdf84466d28f0b0-6fc09fae121f39ef56b-8000_verapache"><!-- --></a> |
| <h3 class="topictitle3">HostComponent metadata tag</h3> |
| |
| |
| <div> |
| <p>Use the <samp class="codeph">[HostComponent]</samp> metadata tag to |
| identify the host component of a Spark skin class. The <samp class="codeph">[HostComponent]</samp> metadata |
| tag has the following syntax:</p> |
| |
| <pre class="codeblock"><Metadata> |
| [HostComponent(<em>componentName</em>)] |
| </Metadata></pre> |
| |
| <p>For example:</p> |
| |
| <pre class="codeblock"><Metadata> |
| [HostComponent("spark.components.Button")] |
| </Metadata></pre> |
| |
| <p>As a result of this metadata, Flex creates the property <samp class="codeph">hostComponent</samp> 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. </p> |
| |
| <p>For more information, see <a href="flx_gumboskinning_gs.html#WS53116913-F952-4b21-831F-9DE85B647C8A_verapache">Spark |
| Skinning</a>.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a23_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a23_verapache"><!-- --></a> |
| <h3 class="topictitle3">IconFile metadata tag</h3> |
| |
| |
| <div> |
| <p>Use the <samp class="codeph">[IconFile]</samp> metadata tag to identify |
| the filename for the icon that represents the component in the Insert |
| bar of Flash Builder.</p> |
| |
| <p>The <samp class="codeph">[IconFile]</samp> metadata tag has the following |
| syntax:</p> |
| |
| <pre class="codeblock"> [IconFile("<em>fileName</em>")]</pre> |
| |
| <p>The <samp class="codeph">fileName</samp> property specifies a PNG, GIF, |
| or JPEG file that contains the icon, as the following example shows: </p> |
| |
| <pre class="codeblock"> [IconFile("MyButton.png")] |
| public class MyButton extends Button |
| { |
| ... |
| }</pre> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a21_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a21_verapache"><!-- --></a> |
| <h3 class="topictitle3">Inspectable metadata tag</h3> |
| |
| |
| <div> |
| <p>The <samp class="codeph">[Inspectable]</samp> 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 <samp class="codeph">[Inspectable]</samp> metadata tag is not required |
| for either code hints or the Property inspector. The following rules |
| determine how Flash Builder displays this information:</p> |
| |
| <ul> |
| <li> |
| <p>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 <samp class="codeph">[Inspectable]</samp> metadata |
| tag with that information.</p> |
| |
| </li> |
| |
| <li> |
| <p>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.</p> |
| |
| </li> |
| |
| <li> |
| <p>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 <samp class="codeph">public</samp>, <samp class="codeph">protected</samp>, <samp class="codeph">private</samp>, |
| and <samp class="codeph">static</samp> keywords, plus the current scope, to |
| determine which ActionScript code hints to show.</p> |
| |
| </li> |
| |
| </ul> |
| |
| <p>The <samp class="codeph">[Inspectable]</samp> metadata tag must immediately |
| precede the property's variable declaration or the setter and getter |
| methods to be bound to that property. The <samp class="codeph">[Inspectable]</samp> metadata |
| tag has the following syntaxes:</p> |
| |
| <pre class="codeblock"> [Inspectable(<em>attribute=value</em>[<em>,attribute=value,</em>...])] |
| <em>property_declaration name:type;</em> |
| [Inspectable(<em>attribute=value</em>[<em>,attribute=value,</em>...])] |
| <em>setter_getter_declarations;</em></pre> |
| |
| <p>The following table describes the properties of the <samp class="codeph">[Inspectable]</samp> metadata tag:</p> |
| |
| |
| <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"> |
| |
| |
| |
| <thead align="left"> |
| <tr> |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e2023"> |
| <p>Property</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e2029"> |
| <p>Type</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e2035"> |
| <p>Description</p> |
| |
| </th> |
| |
| </tr> |
| |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">category</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Groups the property into a specific subcategory |
| in the Property inspector of the Flash Builder user interface. The |
| default category is <samp class="codeph">"Other"</samp>. Specify a value of <samp class="codeph">"Common"</samp>, <samp class="codeph">"Effects"</samp>, <samp class="codeph">"Events"</samp>, <samp class="codeph">"Layout Constraints"</samp>, <samp class="codeph">"Size"</samp>, <samp class="codeph">"Styles"</samp>, <samp class="codeph">"Text",</samp> or <samp class="codeph">"Other"</samp>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">defaultValue</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>String or</p> |
| |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Sets the initial value in the editor that |
| appears in the Property inspector when you modify the attribute. |
| The default value is determined from the property definition.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">enumeration</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Specifies a comma-delimited list of legal |
| values for the property. Only these values are allowed; for example, <samp class="codeph">item1</samp>,<samp class="codeph">item2</samp>,<samp class="codeph">item3</samp>. |
| Notice the lack of a space character between items so that Flash |
| Builder does not interpret a space as a part of a valid value.</p> |
| |
| <p>This |
| information appears as code hints and in the Property inspector. |
| If you define a Boolean variable, Flash Builder automatically shows <samp class="codeph">true</samp> and <samp class="codeph">false</samp> without |
| you having to specifying them using <samp class="codeph">enumeration</samp>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">environment</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Specifies which inspectable properties should |
| not be allowed (environment<samp class="codeph">=none</samp>), which are used |
| only for Flash Builder (environment<samp class="codeph">=Flash</samp>), and |
| which are used only by Flex and not Flash Builder (environment<samp class="codeph">=MXML</samp>). </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">format</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Determines the type of editor that appears |
| in the Property inspector when you modify the attribute. You can |
| use this property when the data type of the attribute is not specific |
| to its function. For example, for a property of type Number, you |
| can specify <samp class="codeph">format="Color"</samp> to cause Flash Builder |
| to open a color editor when you modify the attribute. Common values |
| for the <samp class="codeph">format</samp> property include <samp class="codeph">"Length"</samp>, <samp class="codeph">"Color"</samp>, <samp class="codeph">"Time"</samp>, <samp class="codeph">"EmbeddedFile"</samp>, |
| and <samp class="codeph">"File"</samp>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">listOffset</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Specifies the default index into a List |
| value. </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">name</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Specifies the display name for the property; |
| for example, <samp class="codeph">Font</samp> |
| <samp class="codeph">Width</samp>. If not |
| specified, use the property's name, such as <samp class="codeph">_fontWidth</samp>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">type</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Specifies the type specifier. If omitted, |
| use the property's type. The following values are valid: </p> |
| |
| <div class="p"> |
| <ul> |
| <li> |
| <p> |
| <samp class="codeph">Array</samp> |
| </p> |
| |
| </li> |
| |
| <li> |
| <p> |
| <samp class="codeph">Boolean</samp> |
| </p> |
| |
| </li> |
| |
| <li> |
| <p> |
| <samp class="codeph">Color</samp> |
| </p> |
| |
| </li> |
| |
| <li> |
| <p> |
| <samp class="codeph">Font Name</samp> |
| </p> |
| |
| </li> |
| |
| <li> |
| <p> |
| <samp class="codeph">List</samp> |
| </p> |
| |
| </li> |
| |
| <li> |
| <p> |
| <samp class="codeph">Number</samp> |
| </p> |
| |
| </li> |
| |
| <li> |
| <p> |
| <samp class="codeph">Object</samp> |
| </p> |
| |
| </li> |
| |
| <li> |
| <p> |
| <samp class="codeph">String</samp> |
| </p> |
| |
| </li> |
| |
| </ul> |
| |
| </div> |
| |
| <p>If the property |
| is an Array, you must list the valid values for the Array.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">variable</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Specifies the variable to which this parameter |
| is bound. </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2023 "> |
| <div class="p"> |
| <pre class="codeblock">verbose</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2029 "> |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2035 "> |
| <p>Indicates that this inspectable property |
| should be displayed in the Flash Builder user interface only when |
| the user indicates that <samp class="codeph">verbose</samp> properties should |
| be included. If this property is not specified, Flash Builder assumes |
| that the property should be displayed. </p> |
| |
| </td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| <p>The following example defines the <samp class="codeph">myProp</samp> parameter |
| as inspectable:</p> |
| |
| <pre class="codeblock"> [Inspectable(defaultValue=true, verbose=1, category="Other")] |
| public var myProp:Boolean;</pre> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a1d_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a1d_verapache"><!-- --></a> |
| <h3 class="topictitle3">InstanceType metadata tag</h3> |
| |
| |
| <div> |
| <p>The <samp class="codeph">[InstanceType]</samp> metadata |
| tag specifies the allowed data type of a property of type IDeferredInstance, |
| as the following example shows:</p> |
| |
| <pre class="codeblock"> // Define a deferred property for the top component. |
| [InstanceType("mx.controls.Label")] |
| public var topRow:IDeferredInstance;</pre> |
| |
| <p>The compiler validates that users assign values only of the specified |
| type to the property. In this example, if the component user sets |
| the <samp class="codeph">topRow</samp> property to a value of a type other |
| than mx.controls.Label, the compiler issues an error message.</p> |
| |
| <p>You use the <samp class="codeph">[InstanceType]</samp> metadata tag when |
| creating template components. For more information, see <a href="flx_templating_tp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a1e_verapache">Template |
| components</a>. </p> |
| |
| <p>The <samp class="codeph">[InstanceType]</samp> metadata tag has the following |
| syntax:</p> |
| |
| <pre class="codeblock"> [InstanceType("<em>package.className</em>")]</pre> |
| |
| <p>You must specify a fully qualified package and class name.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a1b_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a1b_verapache"><!-- --></a> |
| <h3 class="topictitle3">NonCommittingChangeEvent metadata |
| tag</h3> |
| |
| |
| <div> |
| <p>The <samp class="codeph">[NonCommittingChangeEvent]</samp> 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. </p> |
| |
| <p>An example of this is if you tied a validator to the <samp class="codeph">text</samp> property |
| of a TextInput control. The <samp class="codeph">text</samp> 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 <samp class="codeph">NonCommittingChangeEvent</samp> tag lets |
| you dispatch a change event, but that does not trigger validation. </p> |
| |
| <p>You insert the <samp class="codeph">[NonCommittingChangeEvent]</samp> metadata |
| tag before an ActionScript property definition or before a setter |
| or getter method. The <samp class="codeph">[NonCommittingChangeEvent]</samp> metadata |
| tag has the following syntax:</p> |
| |
| <pre class="codeblock"> [NonCommittingChangeEvent("<em>event_name</em>")]</pre> |
| |
| <p>In the following example, the component dispatches the <samp class="codeph">change</samp> event |
| every time the user enters a keystroke, but the <samp class="codeph">change</samp> event |
| does not trigger data binding or data validators. When the user |
| completes data entry by pressing the Enter key, the component broadcasts |
| the <samp class="codeph">valueCommit</samp> event to trigger any data bindings |
| and data validators:</p> |
| |
| <pre class="codeblock"> [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. |
| } |
| }</pre> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a25_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a25_verapache"><!-- --></a> |
| <h3 class="topictitle3">RemoteClass metadata tag</h3> |
| |
| |
| <div> |
| <p>Use the <samp class="codeph">[RemoteClass]</samp> 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 <samp class="codeph">[RemoteClass]</samp> metadata tag before |
| an ActionScript class definition. </p> |
| |
| <p>The <samp class="codeph">[RemoteClass]</samp> metadata tag has the following |
| syntax:</p> |
| |
| <pre class="codeblock"> [RemoteClass]</pre> |
| |
| <p>You can also use this tag to represent a server-side Java object |
| in a client application. You use the <samp class="codeph">[RemoteClass(alias=" ")]</samp> 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 <samp class="codeph">alias</samp>.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WSccb96ffde9c4284e978649121a0df15e8-8000_verapache"><a name="WSccb96ffde9c4284e978649121a0df15e8-8000_verapache"><!-- --></a> |
| <h3 class="topictitle3">RichTextContent metadata tag</h3> |
| |
| |
| <div> |
| <p>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 <samp class="codeph">[RichTextContent]</samp> metadata |
| tag to indicate that the value of a property in MXML should always |
| be interpreted by the compiler as a String.</p> |
| |
| <p>For example, the <samp class="codeph">content</samp> property of the spark.components.TextArea |
| and spark.primitives.RichText classes is typed as Object. However, |
| these classes use the <samp class="codeph">[RichTextContent]</samp> metadata |
| tag to indicate that the value of the property in MXML should always |
| be interpreted as a String. </p> |
| |
| <div class="p">Shown below are two examples that set the <samp class="codeph">content</samp> property |
| of the RichText class: <pre class="codeblock"><!-- 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></pre> |
| |
| </div> |
| |
| <p>Data binding syntax, <samp class="codeph">{}</samp>, and @ functions, such |
| as @<samp class="codeph">Resource</samp> and <samp class="codeph">@Embed</samp>, are supported |
| by properties that use the <samp class="codeph">[RichTextContent]</samp> metadata |
| tag.</p> |
| |
| <p>You insert the <samp class="codeph">[RichTextContent]</samp> metadata tag |
| a property before a property definition in ActionScript. The <samp class="codeph">[RichTextContent]</samp> metadata |
| tag has the following syntax:</p> |
| |
| <pre class="codeblock"> [RichTextContent]</pre> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WSed21e2b297da693f52150838121df2b8ad7-8000_verapache"><a name="WSed21e2b297da693f52150838121df2b8ad7-8000_verapache"><!-- --></a> |
| <h3 class="topictitle3">SkinPart metadata tag</h3> |
| |
| |
| <div> |
| <p>Components can uses skins made up of skin parts. Use the <samp class="codeph">[SkinPart]</samp> 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.</p> |
| |
| <div class="p">Insert the <samp class="codeph">[SkinPart]</samp> metadata tag before any |
| property that corresponds to a skin part. The <samp class="codeph">[SkinPart]</samp> metadata |
| tag has the following syntax: <pre class="codeblock">[SkinPart(type="<em>package.className</em>", required="<em>true_false</em>")] |
| /** |
| * Optional ASDoc comment. |
| */ <em> |
| Property definition</em></pre> |
| |
| </div> |
| |
| <p>The <samp class="codeph">type</samp> and <samp class="codeph">required</samp> attributes |
| are optional. The <samp class="codeph">type</samp> attribute specifies the |
| data type of the skin part, which determines whether the part is |
| static or dynamic. The default value of <samp class="codeph">type</samp> is |
| determined by the data type of the property. </p> |
| |
| <p>The <samp class="codeph">required</samp> attribute specifies if the skin |
| class must define the skin part. The default value of the <samp class="codeph">required</samp> attribute |
| is <samp class="codeph">false</samp>. </p> |
| |
| <p>SkinPart metadata is inherited by subclasses of the component. </p> |
| |
| <p>For more information, see <a href="flx_gumboskinning_gs.html#WS53116913-F952-4b21-831F-9DE85B647C8A_verapache">Spark |
| Skinning</a>.</p> |
| |
| </div> |
| |
| <div class="nested3" id="WSed21e2b297da693f-7174730a121df394f95-8000_verapache"><a name="WSed21e2b297da693f-7174730a121df394f95-8000_verapache"><!-- --></a> |
| <h4 class="topictitle4">Static skin parts</h4> |
| |
| |
| <div> |
| <div class="p">Static skin parts are created once by an instance of a |
| component, and are defined as shown below: <pre class="codeblock">[SkinPart] |
| /** |
| * ASDoc comment for thumb. |
| */ |
| public var thumb:spark.components.Button;</pre> |
| |
| </div> |
| |
| <p>The data type for static parts is the data type of the part property. |
| In this example above, the type is Button. Therefore, static skin |
| parts typically omit the <samp class="codeph">type</samp> attribute of the <samp class="codeph">[SkinPart]</samp> metadata |
| tag.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested3" id="WSed21e2b297da693f-7174730a121df394f95-7fff_verapache"><a name="WSed21e2b297da693f-7174730a121df394f95-7fff_verapache"><!-- --></a> |
| <h4 class="topictitle4">Dynamic skin parts</h4> |
| |
| |
| <div> |
| <p>Some components create multiple instances of a skin part. |
| For example, the Spark ButtonBar control can create any number of |
| buttons. Dynamic skin parts can be created multiple times by a component. |
| The data type of a dynamic skin part property is always IFactory, |
| but the metadata tag can optionally define the data type of the |
| skin part by using the <samp class="codeph">type</samp> property. </p> |
| |
| <div class="p">For example from the spark.components.ButtonBar class: <pre class="codeblock">[SkinPart(required="false", type="mx.core.IVisualElement")] |
| /** |
| * A skin part that defines the first button. |
| */ |
| public var firstButton:IFactory;</pre> |
| |
| </div> |
| |
| <p>Because the data type of the skin part is IFactory, it is a dynamic |
| skin part. Each instance of the skin part is of type mx.core.IVisualElement. </p> |
| |
| </div> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WSed21e2b297da693f52150838121df2b8ad7-7fff_verapache"><a name="WSed21e2b297da693f52150838121df2b8ad7-7fff_verapache"><!-- --></a> |
| <h3 class="topictitle3">SkinState metadata tag</h3> |
| |
| |
| <div> |
| <p>The <samp class="codeph">[SkinState]</samp> 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. </p> |
| |
| <div class="p">The SkinState tag has the following ActionScript syntax: <pre class="codeblock">[SkinState("<em>stateName</em>")]</pre> |
| |
| </div> |
| |
| <p>The following example defines two skin states for a component:</p> |
| |
| <div class="p"> |
| <pre class="codeblock">package spark.components.supportCl asses |
| { |
| /** |
| * Optional ASDoc comment. */ |
| [SkinState("n ormal")] |
| |
| /** |
| * Optional ASDoc comment. */ |
| [SkinState("disabled")] |
| |
| public class MyClass {}</pre> |
| |
| </div> |
| |
| <p>For more information, see <a href="flx_gumboskinning_gs.html#WS53116913-F952-4b21-831F-9DE85B647C8A_verapache">Spark |
| Skinning</a>.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a1a_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a1a_verapache"><!-- --></a> |
| <h3 class="topictitle3">Style metadata tag</h3> |
| |
| |
| <div> |
| <p>Use the <samp class="codeph">[Style]</samp> metadata tag to define |
| the MXML tag attribute for a style property for the component. You |
| insert the <samp class="codeph">[Style]</samp> metadata tag before the class |
| definition in an ActionScript file, or in the <samp class="codeph"><fx:Metadata></samp> block |
| in an MXML file. </p> |
| |
| <p>The <samp class="codeph">[Style]</samp> metadata tag has the following syntax: </p> |
| |
| <pre class="codeblock"> [Style(name=<em>"style_name"[,property="value",...])</em>]</pre> |
| |
| <p>The following table describes the properties for the <samp class="codeph">[Style]</samp> metadata |
| tag:</p> |
| |
| |
| <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"> |
| |
| |
| |
| <thead align="left"> |
| <tr> |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e2959"> |
| <p>Option</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e2965"> |
| <p>Type</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e2971"> |
| <p>Description</p> |
| |
| </th> |
| |
| </tr> |
| |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2959 "> |
| <div class="p"> |
| <pre class="codeblock">name</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2965 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2971 "> |
| <p>(Required) Specifies the name of the style.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2959 "> |
| <div class="p"> |
| <pre class="codeblock">arrayType</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2965 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2971 "> |
| <p>If <samp class="codeph">type</samp> is <samp class="codeph">Array</samp>, <samp class="codeph">arrayType</samp> specifies |
| the data type of the Array elements. If the data type is not an |
| ActionScript type such as Number or Date, use a qualified class |
| name in the form <em>packageName.className</em>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2959 "> |
| <div class="p"> |
| <pre class="codeblock">enumeration</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2965 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2971 "> |
| <p>Specifies an enumerated list of possible |
| values for the style property.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2959 "> |
| <div class="p"> |
| <pre class="codeblock">format</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2965 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2971 "> |
| <p>Specifies the units of the property. For |
| example, if you specify <samp class="codeph">type</samp> as <samp class="codeph">"Number"</samp>, you |
| might specify <samp class="codeph">format="Length"</samp> if the style defines |
| a length measured in pixels. Or, if you specify <samp class="codeph">type="uint"</samp>, |
| you might set <samp class="codeph">format="Color"</samp> if the style defines an |
| RGB color. The possible values are <samp class="codeph">Boolean</samp>, <samp class="codeph">Color</samp>, <samp class="codeph">Number</samp>, <samp class="codeph">Length</samp>, <samp class="codeph">uint</samp>, <samp class="codeph">Time</samp>, <samp class="codeph">File</samp>, <samp class="codeph">EmbeddedFile</samp>, <samp class="codeph">int</samp>, <samp class="codeph">ICollectionView</samp>, <samp class="codeph">Array</samp>, <samp class="codeph">Class</samp>, <samp class="codeph">String</samp>, |
| and <samp class="codeph">Object</samp>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2959 "> |
| <div class="p"> |
| <pre class="codeblock">inherit</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2965 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2971 "> |
| <p>Specifies whether the property is inheriting. |
| Valid values are <samp class="codeph">yes</samp> and <samp class="codeph">no</samp>. This |
| property refers to CSS inheritance, not object-oriented inheritance. |
| All subclasses automatically use object-oriented inheritance to |
| inherit the style property definitions of their superclasses. </p> |
| |
| <p>Some |
| style properties are inherited using CSS inheritance. If you set |
| an inheritable style property on a parent container, its children |
| inherit that style property. For example, if you define <samp class="codeph">fontFamily</samp> as |
| Times for a Panel container, all children of that container will |
| also use Times for <samp class="codeph">fontFamily</samp>, unless they override |
| that property. </p> |
| |
| <p>If you set a noninheritable style, such as <samp class="codeph">textDecoration</samp>, |
| on a parent container, only the parent container and not its children |
| use that style. For more information on inheritable style properties, |
| see <a href="flx_styles_st.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e83_verapache">About |
| style inheritance</a>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2959 "> |
| <div class="p"> |
| <pre class="codeblock">states</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2965 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2971 "> |
| <p>For skin properties, specifies that you |
| can use the style to specify a stateful skin for multiple states |
| of the component. For example, the definition of the <samp class="codeph">Slider.thumbSkin</samp> style |
| uses the following <samp class="codeph">[Style]</samp> metadata tag:</p> |
| |
| <div class="p"> |
| <pre class="codeblock">[Style(name="thumbSkin", type="Class", inherit="no", states="disabled, down, over, up")]</pre> |
| |
| </div> |
| |
| <p>This |
| line specifies that you can use the <samp class="codeph">Slider.thumbSkin</samp> style |
| to specify a stateful skin for the disabled, down, over, and up |
| states of the Slider control. For more information, see <a href="flx_skinning_sk.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fed_verapache">Skinning |
| MX components</a>. </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2959 "> |
| <p> |
| <samp class="codeph">theme</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2965 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2971 "> |
| <p>If the style is only valid for a specific |
| theme, specifies the name of the theme. For example, some styles |
| on Flex components are only valid if you are using the Spark or Halo |
| theme. For more information, see <a href="flx_styles_st.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f85_verapache">About |
| themes</a> |
| </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2959 "> |
| <div class="p"> |
| <pre class="codeblock">type</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2965 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e2971 "> |
| <p>Specifies the data type of the value that |
| you write to the style property. If the type is not an ActionScript |
| type such as Number or Date, use a qualified class name in the form <em>packageName.className</em>.</p> |
| |
| </td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| <p>The following example shows the definition of the <samp class="codeph">textSelectedColor</samp> style property:</p> |
| |
| <pre class="codeblock"> [Style(name="textSelectedColor",type="Number",format="Color",inherit="yes")]</pre> |
| |
| <p>The next example shows the definition of the <samp class="codeph">verticalAlign</samp> style |
| property:</p> |
| |
| <pre class="codeblock"> [Style(name="verticalAlign", type="String", enumeration="bottom,middle,top", inherit="no")]</pre> |
| |
| <p>For more information on the <samp class="codeph">[Style]</samp> metadata |
| tag, see <a href="flx_skinstyle_ss.html#WS2db454920e96a9e51e63e3d11c0bf69084-7a20_verapache">Custom |
| style properties</a>. </p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS4b4ddee4904fe7796d38fa291219d46bcb4-8000_verapache"><a name="WS4b4ddee4904fe7796d38fa291219d46bcb4-8000_verapache"><!-- --></a> |
| <h3 class="topictitle3">SWF metadata tag</h3> |
| |
| |
| <div> |
| <p>Use the <samp class="codeph">[SWF]</samp> 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 <samp class="codeph"><s:Application></samp> tag when you write the |
| main application file in MXML. </p> |
| |
| <p>The <samp class="codeph">[SWF]</samp> tag has the following syntax:</p> |
| |
| <div class="p"> |
| <pre class="codeblock">[SWF(option="value"[,option="value",...])]</pre> |
| |
| </div> |
| |
| <p>You can specify several options the <samp class="codeph">[SWF]</samp> metadata |
| tag. The following table describes these options:</p> |
| |
| |
| <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"> |
| |
| |
| |
| <thead align="left"> |
| <tr> |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e3387"> |
| <p>Option</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e3393"> |
| <p>Type</p> |
| |
| </th> |
| |
| <th class="cellrowborder" valign="top" width="NaN%" id="d296857e3399"> |
| <p>Description</p> |
| |
| </th> |
| |
| </tr> |
| |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3387 "> |
| <div class="p"> |
| <pre class="codeblock">frameRate</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3393 "> |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3399 "> |
| <p>Specifies the frame rate of the application, |
| in frames per second. The default value is 24.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3387 "> |
| <p> |
| <samp class="codeph">height</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3393 "> |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3399 "> |
| <p>The height of the application, in pixels.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3387 "> |
| <p> |
| <samp class="codeph">heightPercent</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3393 "> |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3399 "> |
| <p>The height of the application, as a percentage |
| of the browser window. Include the percent sign (<samp class="codeph">%</samp>) |
| in the value.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3387 "> |
| <div class="p"> |
| <pre class="codeblock">pageTitle</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3393 "> |
| <p>String</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3399 "> |
| <p>Specifies a String that appears in the title |
| bar of the browser. This property provides the same functionality |
| as the HTML <samp class="codeph"><title></samp> tag. </p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3387 "> |
| <div class="p"> |
| <pre class="codeblock">scriptRecursionLimit</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3393 "> |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3399 "> |
| <p>Specifies the maximum depth of Flash Player |
| or AIR call stack before Flash Player or AIR stops. This is essentially |
| the stack overflow limit.</p> |
| |
| <p>The default value is 1000.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3387 "> |
| <div class="p"> |
| <pre class="codeblock">scriptTimeLimit</pre> |
| |
| </div> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3393 "> |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3399 "> |
| <p>Specifies the maximum duration, in seconds, |
| that an ActionScript event listener can execute before Flash Player |
| or AIR assumes that it has stopped processing and aborts it.</p> |
| |
| <p>The |
| default value is 60 seconds, which is also the maximum allowable |
| value that you can set.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3387 "> |
| <p> |
| <samp class="codeph">width</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3393 "> |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3399 "> |
| <p>The width of the application, in pixels.</p> |
| |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3387 "> |
| <p> |
| <samp class="codeph">widthPercent</samp> |
| </p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3393 "> |
| <p>Number</p> |
| |
| </td> |
| |
| <td class="cellrowborder" valign="top" width="NaN%" headers="d296857e3399 "> |
| <p>The width of the application, as a percentage |
| of the browser window. Include the percent sign (<samp class="codeph">%</samp>) |
| in the value.</p> |
| |
| </td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| |
| <p>For more information on these options, see <a href="flx_app_container_apc.html#WS2db454920e96a9e51e63e3d11c0bf62d75-7ff8_verapache">Specifying |
| options of the Application container</a>.</p> |
| |
| </div> |
| |
| </div> |
| |
| <div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7a19_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7a19_verapache"><!-- --></a> |
| <h3 class="topictitle3">Transient metadata tag</h3> |
| |
| |
| <div> |
| <p>Use the <samp class="codeph">[Transient]</samp> 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 <samp class="codeph">[RemoteClass]</samp> metadata tag. </p> |
| |
| <p>The <samp class="codeph">[Transient]</samp> metadata |
| tag has the following syntax: </p> |
| |
| <pre class="codeblock"> [Transient] |
| public var count:Number = 5;</pre> |
| |
| </div> |
| |
| </div> |
| |
| <div> |
| <p><strong>Navigation</strong></p> |
| <p><a href="index.html">Using Flex</a> » <a href="flx_p8a_custom_components.html">Custom components</a></p> |
| </div> |
| |
| <p>Adobe, Adobe Flash, Adobe Flash Builder and Adobe Flash Player are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries and are used by permission from Adobe. No other license to the Adobe trademarks are granted.</p> |
| </div> |
| |
| |
| </body> |
| </html> |
