Embedding asset types

You can import various types of media, including images, SWF files, and sound files.

Embedding JPEG, GIF, and PNG images

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>

The executing SWF file for the previous example is shown below:

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.

Embedding SVG images

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.

Embedding sounds

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>

The executing SWF file for the previous example is shown below:

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.

Embedding SWF files

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

Embedding SWF files for Flash Player 8 and earlier, and for static Flash Player 9 or later assets

You can embed SWF files created for Flash Player 8 and earlier and for Flash Player 9 or later static assets. Use static assets for simple artwork or skins that do not contain any ActionScript 3.0 code. When embedded, your Flex application cannot interact with the embedded SWF file. That is, you cannot use ActionScript in a Flex application to access the properties or methods of a SWF file created for Flash Player 8 or earlier or for static Flash Player 9 or later assets.

Note: You can use the flash.net.LocalConnection class to communicate between a Flex application and a SWF file.

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

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

In this example, you define a class named imgCls that represents the embedded SWF file. Flex defines imgCls as a reference to a subclass of the mx.core.MovieClipAsset class, which is a subclass of the flash.display.MovieClip class. Therefore you can manipulate the image by using the methods and properties of the MovieClipAsset class.

Embedding SWF symbols

Flex lets you reference exported symbols in an embedded SWF file. If the symbol has dependencies, Flex embeds them also; otherwise, Flex embeds only the specified symbol from the SWF file. To reference a symbol, you specify the symbol parameter:

[Embed(source='SWFFileName.swf', symbol='symbolName')]
Note: Flash defines three types of symbols: Button, MovieClip, and Graphic. You can embed Button and MovieClip symbols in a Flex application, but you cannot embed a Graphic symbol because it cannot be exported for ActionScript.

This capability is useful when you have a SWF file that contains multiple exported symbols, but you want to load only some of them into your Flex application. Loading only the symbols that your application requires makes the resulting Flex SWF file smaller than if you imported the entire SWF file.

A Flex application can import any number of SWF files. However, if two SWF files have the same filename and the exported symbol names are the same, you cannot reference the duplicate symbols, even if the SWF files are in separate directories.

If the SWF file contains any ActionScript code, Flex prints a warning during compilation and then strips out the ActionScript from the embed symbol. This means that you can only embed the symbol itself.

The following example imports a green square from a SWF file that contains a library of different shapes:

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

The executing SWF file for the previous example is shown below:

If you use the [Embed] metadata tag in ActionScript to embed the symbol, you can access the object that represents the symbol, as the following code shows:

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

In this example, you define a class named imgCls that represents the embedded symbol. Internally, Flex defines imgCls as a reference to a subclass of either one of the following classes:

SpriteAsset 
For single-frame SWF files

MovieClipAsset
For multiframe SWF files

Embedding SWF files that represent Flex applications

You can embed SWF files that represent Flex applications. For example, you use the [Embed] metadata tag in ActionScript to embed a SWF file, as the following code shows:

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

In this example, you define a class named flexAppCls that represents the embedded SWF file. Flex defines flexAppCls as a reference to a subclass of the mx.core.MovieClipAsset class, which is a subclass of the flash.display.MovieClip class. Therefore you can manipulate the embedded SWF file by using the methods and properties of the MovieClipAsset class.

You typically embed a Flex application when you do not require the embedding application to interact with the embedded application. If the embedding application requires interactivity with the embedded application, you might consider implementing it as a custom component, rather than as a separate application.

Alternatively, if you use the SWFLoader control to load the Flex application at run time, the embedding application can interact with the loaded application to access its properties and methods. For more information and examples, see Interacting with a loaded Flex application.

Using 9-slice scaling with embedded images

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:

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 executing SWF file for the previous example is shown below:

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:

Omitting the 9-slice scaling means the scaled image appears exactly like the unscaled image

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.

Embedding all other file types

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>

The executing SWF file for the previous example is shown below: