One of the most common uses of the embed mechanism is to import an image for a Flex control by using the @Embed() directive in an MXML tag definition. For example, many controls support icons or skins that you can embed in the application. The Button control lets you specify label text, as well as an optional icon image, as the following example shows:

<?xml version="1.0"?> 
<!-- embed\ButtonIcon.mxml --> 
<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"> 
 
    <s:Button label="Icon Button" 
        height="30" 
        icon="@Embed(source='logo.gif')"/> 
</s:Application>

Another option for embedding is to associate the embedded image with a variable by using the [Embed] metadata tag. In this way, you can reference the embedded image from multiple locations in your application, as the following example shows:

<?xml version="1.0"?> 
<!-- embed\ButtonIconClass.mxml --> 
<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"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            [Embed(source="logo.gif")] 
            [Bindable] 
            public var imgCls:Class; 
        ]]> 
    </fx:Script> 
    <s:Button label="Icon Button 1" 
        height="30" 
        icon="{imgCls}"/> 
    <s:Button label="Icon Button 2" 
        height="30" 
        icon="{imgCls}"/> 
</s:Application>

For style properties, you can embed an asset as part of a style sheet definition by using the Embed() directive, as the following example shows:

<?xml version="1.0"?> 
<!-- embed\ButtonIconCSS.mxml --> 
<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"> 
 
    <fx:Style>  
        .myCustomButton { 
            icon:Embed(source="logo.gif"); 
        } 
    </fx:Style> 
 
    <s:Button label="Icon Button Style Def" 
        styleName="myCustomButton"/> 
</s:Application>

The alternative to embedding an asset is to load the asset at run time. You can load an asset from the local file system in which the SWF file runs, or you can access a remote asset, typically through an HTTP request over a network.

Embedded assets load immediately, because they are already part of the Flex SWF file. However, they add to the size of your application and slow down the application initialization process. Embedded assets also require you to recompile your applications whenever your asset changes.

Assets loaded at run time exist as separate, independent files on your web server (or elsewhere) and are not compiled into your Flex applications. The referenced assets add no overhead to an application's initial load time. However, you might experience a delay when you use the asset and load it in Adobe^® Flash^® Player or Adobe^® AIR™. These assets are independent of your Flex application, so you can change them without causing a recompile operation, as long as the names of the modified assets remain the same.

For examples that load an asset at run time, see Image controland SWFLoader control.

For security, by default Flash Player does not allow an application to access some types of remote data (such as SWF files) at run time from a domain other than the domain from which the application was served. Therefore, a server that hosts data must be in the same domain as the server hosting your application, or the server must define a crossdomain.xml file. A crossdomain.xml file is an XML file that provides a way for a server to indicate that its data and documents are available to SWF files served from specific domains, or from all domains. For more information on application security, see Security.

You can embed the following types of files in a Flex application.

You can use the slash character (\) to escape the at sign character (@) when you want to use a literal @ character. For example, the string "\@Embed(foo)" means the literal string "@Embed(foo)"). You use two slash characters (\\) to escape a single backslash character. For example, use the character string "\@" to specify the literal strings "\@".

Each form of the embed syntax takes one or more optional parameters. The exact syntax that you use to embed assets depends on where they are embedded. Some of these parameters are available regardless of what type of asset you are embedding, and others are specific to a particular type of media. For example, you can use the source and mimeType parameters with any type of media, but the scaleGridRight parameter applies only to images.

The following table describes the parameters that are available for any type of embedded asset. For more information, see About the source parameter and About the MIME type.

source=asset

mimeType=type

The following table describes the parameters that are specific for images and Sprite objects. For more information, see Using 9-slice scaling with embedded images.

scaleGridTop

scaleGridBottom

scaleGridLeft

scaleGridRight

The following table describes the parameter that is specific to SWF files. For more information, see Embedding SWF files.

symbol

In almost all cases, you must specify the source parameter, or nothing is embedded.

The source parameter is the default parameter of the [Embed] metadata tag; therefore, if you are not specifying any other parameters, you can just supply its value without explicitly including the parameter name or assigning it the desired value, as the following example shows:

 <fx:Style>	 
 	.myCustomButton1 { 
 		icon:Embed("logo.gif"); 
	} 
 	.myCustomButton2 { 
		icon:Embed(source="logo.gif"); 
	} 
  </fx:Style>

You can optionally specify a MIME type for the imported asset by using the mimeType parameter. If you do not specify a mimeType parameter, Flex makes a best guess about the type of the imported file based on the file extension. If you do specify it, the mimeType parameter overrides the default guess of the asset type.

Flex supports the following MIME types.

• application/octet-stream

• application/x-font

• application/x-font-truetype

• application/x-shockwave-flash

• audio/mpeg

• image/gif

• image/jpeg

• image/png

• image/svg

• image/svg-xml

You can use the [Embed] metadata tag to import JPEG, GIF, PNG, SVG, SWF, TTF, and MP3 files.

You must use the [Embed] metadata tag before a variable definition, where the variable is of type Class. The following example loads an image file, assigns it to the imgCls variable, and then uses that variable to set the value of the source property of an Image control:

<?xml version="1.0"?> 
<!-- embed\ImageClass.mxml --> 
<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" 
    width="100" height="80"> 
    
    <fx:Script> 
        <![CDATA[ 
            [Embed(source="logo.gif")] 
            [Bindable] 
            public var imgCls:Class; 
        ]]> 
    </fx:Script> 
 
    <s:Image source="{imgCls}"/> 
</s:Application>

Notice that Flex uses data binding to tie the imgCls variable to the source property. If you omit the [Bindable] metadata tag preceding the imgCls variable definition, Flex can perform the data binding operation only once, at application startup. When you include the [Bindable] metadata tag, Flex recognizes any changes to the imgCls variable and updates any components that use that variable when a change to it occurs.

Generally, this method of embedding assets provides more flexibility than other methods because you can import an asset once and then use it in multiple places in your application, and because you can update the asset and have the data binding mechanism propagate that update throughout your application.

Many Flex components, such as Button and TabNavigator, take an icon property or other property that lets you specify an image to the control. You can embed the image asset by specifying the property value by using the @Embed() directive in MXML. You can use any supported graphic file with the @Embed() directive, including SWF files and assets inside SWF files.

You can use the @Embed() directive to set an MXML tag property, or to set a property value by using a child tag. The @Embed() directive returns a value of type Class or String. If the component's property is of type String, the @Embed() directive returns a String. If the component's property is of type Class, the @Embed() directive returns a Class. Using the @Embed() directive with a property that requires a value of any other data type results in an error.

The following example creates a Button control and sets its icon property by using the @Embed() directive:

<?xml version="1.0"?> 
<!-- embed\ButtonAtEmbed.mxml --> 
<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"> 
 
    <s:Button label="Icon Button" 
        height="30" 
        icon="@Embed(source='logo.gif')"/> 
    
</s:Application>

Many style properties of Flex components support imported assets.

You can also use these style properties to set the skins for a component. Skinning is the process of changing the appearance of a component by modifying or replacing its visual elements. These elements can be made up of images, SWF files, or class files that contain drawing API methods.

For more information on skinning and on embedding assets by using style sheets, see Skinning MX components.

Flex supports embedding JPEG, GIF, and PNG files. You can use these images for icons, skins, and other types of application assets.

You might want to manipulate an embedded image at run time. To manipulate it, you determine the data type of the object representing the image and then use the appropriate ActionScript methods and properties of the object.

For example, you use the [Embed] metadata tag in ActionScript to embed a GIF image, as the following code shows:

 [Embed(source="logo.gif")] 
 [Bindable] 
 public var imgCls:Class;

In this example, you define a class named imgCls that represents the embedded image. When embedding JPEG, GIF, and PNG files, Flex defines imgCls as a reference to a subclass of the mx.core.BitmapAsset class, which is a subclass of the flash.display.Bitmap class.

In ActionScript, you can create and manipulate an object that represents the embedded image before passing it to a control. To do so, you create an object with the type of the embedded class, manipulate it, and then pass the object to the control, as the following example shows:

<?xml version="1.0"?> 
<!-- embed/EmbedAccessClassObject.mxml --> 
<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"> 
    
    <fx:Script> 
        <![CDATA[        
            import mx.core.BitmapAsset; 
        
            [Embed(source="logo.gif")] 
            [Bindable] 
            public var imgCls:Class; 
 
            private function modImage():void {            
                // Create an object from the embed class. 
                // Since the embedded image is a GIF file, 
                // the data type is BitmapAsset. 
                var imgObj:BitmapAsset = new imgCls() as BitmapAsset; 
                
                // Modify the object. 
                imgObj.bitmapData.noise(4); 
 
                // Write the modified object to the Image control. 
                myImage.source=imgObj; 
            } 
        ]]> 
    </fx:Script> 
    
    <s:HGroup> 
        <s:Image id="myImageRaw" source="{imgCls}"/> 
        <s:Image id="myImage" creationComplete="modImage();"/> 
    </s:HGroup> 
</s:Application>

In this example, the first Image control displays the unaltered image and the second Image control displays the modified image. You use the bitmapData property of the mx.core.BitmapAsset class to modify the object. The bitmapData property is of type flash.display.BitmapData; therefore you can use all of the methods and properties of the BitmapData class to manipulate the object.

Flex supports importing Scalable Vector Graphics (SVG) images, or a GZip compressed SVG image in a SVGZ file, into an application. This lets you import SVG images and use SVG images as icons for Flex controls.

Flex supports a subset of the SVG 1.1 specification to let you import static, two-dimensional scalable vector graphics. This includes support for basic SVG document structure, Cascading Style Sheets (CSS) styling, transformations, paths, basic shapes, colors, and a subset of text, painting, gradients, and fonts. Flex does not support SVG animation, scripting, or interactivity with the imported SVG image.

For example, you use the [Embed] metadata tag in ActionScript to embed an SVG image, as the following code shows:

 [Embed(source="logo.svg")] 
 [Bindable] 
 public var imgCls:Class;

In this example, you define a class named imgCls that represents the embedded image. When embedding an SVG image, Flex defines imgCls as a reference to a subclass of the mx.core.SpriteAsset class, which is a subclass of the flash.display.Sprite class. Therefore, you can manipulate the image by using the methods and properties of the SpriteAsset class. For an example that manipulates an imported image, see Embedding JPEG, GIF, and PNG images.

Flex supports embedding MP3 sound files for later playback. The following example creates a simple media player with Play and Stop buttons:

<?xml version="1.0"?> 
<!-- embed/EmbedSound.mxml --> 
<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"> 
 
    <fx:Script> 
        <![CDATA[ 
        
            import flash.media.*; 
        
            [Embed(source="sample.mp3")] 
            [Bindable] 
            public var sndCls:Class; 
            
            public var snd:Sound = new sndCls() as Sound; 
            public var sndChannel:SoundChannel; 
            
            public function playSound():void { 
                sndChannel=snd.play(); 
            }   
            
            public function stopSound():void { 
                sndChannel.stop(); 
            }   
        ]]> 
    </fx:Script> 
 
    <s:HGroup> 
        <s:Button label="play" click="playSound();"/> 
        <s:Button label="stop" click="stopSound();"/> 
    </s:HGroup> 
</s:Application>

In this example, you define a class named sndCls that represents the embedded MP3 file. When embedding MP3 files, Flex defines sndCls as a reference to a subclass of the mx.core.SoundAsset, which is a subclass of the flash.media.Sound class.

Flex can handle any legal filename, including filenames that contain spaces and punctuation marks. If the MP3 filename includes regular quotation marks, be sure to use single quotation marks around the filename.

You do not have to embed the sound file to use it with Flex. You can also use the Sound class to load a sound file at run time. For more information, see the Sound class in the ActionScript 3.0 Reference for the Adobe Flash Platform .

Flex fully supports embedding Flash SWF files. You can embed different types of SWF files.

 [Embed(source="icon.swf")] 
 [Bindable] 
 public var imgCls:Class;

 [Embed(source='SWFFileName.swf', symbol='symbolName')]

<?xml version="1.0"?> 
<!-- embed\EmbedSWFSymbol.mxml --> 
<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" > 
 
    <s:Image id="image0" 
        source="@Embed(source='circleSquare.swf', symbol='greenSquare')"/> 
</s:Application>

 [Embed(source='shapes.swf', symbol='greenSquare')] 
 [Bindable] 
 public var imgCls:Class;

 [Embed(source="flex2.swf")] 
 [Bindable] 
 public var flexAppCls:Class;

Flex supports the 9-slice scaling of embedded images. This feature lets you define nine sections of an image that scale independently. The nine regions are defined by two horizontal lines and two vertical lines running through the image, which form the inside edges of a 3 by 3 grid. For images with borders or fancy corners, 9-slice scaling provides more flexibility than full-graphic scaling.

The following example show an image, and the same image with the regions defined by the 9-slice scaling borders:

When you scale an embedded image that uses 9-slice scaling, all text and gradients are scaled normally. However, for other types of objects the following rules apply:

• Content in the center region is scaled normally.

• Content in the corners is not scaled.

• Content in the top and bottom regions is scaled only horizontally. Content in the left and right regions is scaled only vertically.

• All fills (including bitmaps, video, and gradients) are stretched to fit their shapes.

If you rotate the image, all subsequent scaling is normal, as if you did not define any 9-slice scaling.

To use 9-slice scaling, define the following four parameters in your embed statement: scaleGridTop, scaleGridBottom, scaleGridLeft, and scaleGridRight. For more information on these parameters, see Embed parameters.

An embedded SWF file may already contain 9-slice scaling information specified by using Adobe Flash Professional. In that case, the SWF file ignores any 9-slice scaling parameters that you specify in the embed statement.

The following example uses 9-slice scaling to maintain a set border, regardless of how the image itself is resized.

<?xml version="1.0"?> 
<!-- embed\Embed9slice.mxml --> 
<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" 
    height="1200" width="600"> 
    <fx:Script> 
        <![CDATA[ 
            [Embed(source="slice_9_grid.gif", 
                scaleGridTop="25", scaleGridBottom="125", 
                scaleGridLeft="25", scaleGridRight="125")] 
            [Bindable] 
            public var imgCls:Class;            
        ]]> 
    </fx:Script> 
    
    <s:VGroup> 
        <s:Image source="{imgCls}"/> 
        <s:Image source="{imgCls}" width="300" height="300"/> 
        <s:Image source="{imgCls}" width="450" height="450"/> 
    </s:VGroup> 
</s:Application>

The original image is 30 by 30 pixels. The preceding code produces a resizable image that maintains a 5-pixel border:

If you had omitted the 9-slice scaling, the scaled image would have appeared exactly like the unscaled image, as the following image shows:

In this example, you define a class named imgCls that represents the embedded image. If the image is a SWF file that uses 9-slice scaling, Flex defines imgCls as a subclass of the mx.core.SpriteAsset class, which is a subclass of the flash.display.Sprite class. Therefore you can use all of the methods and properties of the SpriteAsset class to manipulate the object.

You can embed any file type in a Flex application as a bit map array. However, Flex does not recognize or process files other than those described previously. If you embed any other file type, you must provide the transcode logic to properly present it to the application user.

To load a file type that is not specifically supported by Flex, use the [Embed] metadata tag to define the source file and MIME type "application/octet-stream". Then define a new class variable for the embedded file. The embedded object is a ByteArrayAsset type object.

The following code embeds a bitmap (.bmp) file and displays properties of the embedded object when you click the Show Properties button. To display or use the object in any other way, you must provide code to create a supported object type.

<?xml version="1.0"?> 
<!-- embed\EmbedOtherFileTypes.mxml --> 
<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"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            import mx.core.UIComponent; 
            import mx.core.BitmapAsset; 
   
            [Embed(source="logo.bmp",mimeType="application/octet-stream")] 
            private var FileClass : Class; 
   
            private function captureEmbeddedImage():void { 
                var fileByteArray:Object = new FileClass(); 
                myTA.text+= "File length:  " + String(fileByteArray.length) + "\n"; 
                myTA.text+="File type:  " + 
                    String(getQualifiedSuperclassName(fileByteArray)) + "\n"; 
            }   
        ]]> 
    </fx:Script> 
 
    <s:Button 
        id="showProperties" 
        label="Show Properties" 
        click="captureEmbeddedImage();"/> 
        
    <s:TextArea id="myTA" 
        width="75%" 
        height="100"/>                
</s:Application>