SWFLoader control

The SWFLoader control is part of the MX component set. There is no Spark equivalent of this control.

The SWFLoader control lets you load one Flex application into another Flex application as a SWF file. It has properties that let you scale its contents. It can also resize itself to fit the size of its contents. By default, content is scaled to fit the size of the SWFLoader control. The SWFLoader control can also load content on demand programmatically, and monitor the progress of a load operation.

When loading an applications into a main application, you should be aware of the following factors:

Versioning
SWF files produced with earlier versions of Flex or ActionScript may not work properly when loaded with the SWFLoader control. You can use the loadForCompatibility property of the SWFLoader control to ensure that applications loaded into a main application works, even if the applications were compiled with a different version of the compiler.

Security
When loading applications, especially ones that were created by a third-party, you should consider loading them into their own SecurityDomain. While this places additional limitations on the level of interoperability between the main application and the application, it ensures that the content is safe from attack.

For more information about creating and loading applications, see Developing and loading sub-applications.

The SWFLoader control also lets you load the contents of a GIF, JPEG, PNG, SVG, or SWF file into your application, where the SWF file does not contain a Flex application, or a ByteArray representing a SWF, GIF, JPEG, or PNG.

For more information, see Image control. For more information on using the SWFLoader control to load a Flex application, see Externalizing application classes.

Note: Flex also includes the Image control for loading GIF, JPEG, PNG, SVG, or SWF files. You typically use the Image control for loading static graphic files and SWF files, and use the SWFLoader control for loading Flex applications as SWF files. The Image control is also designed to be used in custom cell renderers and item editors.

A SWFLoader control cannot receive focus. However, content loaded into the SWFLoader control can accept focus and have its own focus interactions.

Creating a SWFLoader control

You define a SWFLoader control in MXML by using the <mx:SWFLoader> tag, as the following example shows. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block:

<?xml version="1.0"?>
<!-- controls\swfloader\SWFLoaderSimple.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:VGroup>
        <mx:SWFLoader id="loader1" source="FlexApp.swf"/> 
    </s:VGroup>
 
</s:Application>

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

Like the Image control, you can also use the Embed statement with the SWFLoader control to embed the image in your application, as the following example shows:

<?xml version="1.0"?>
<!-- controls\swfloader\SWFLoaderSimpleEmbed.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">

    <mx:SWFLoader id="loader1" source="@Embed(source='FlexApp.swf')"/> 
     
</s:Application>

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

When using the SWFLoader control with an SVG file, you can only load it by using an Embed statement; you cannot load an SVG file at run time. For more information about embedding resources, see the description for the Image control at Image control, and Embedding assets.

This technique works well with SWF files that add graphics or animations to an application but are not intended to have a large amount of user interaction. If you import SWF files that require a large amount of user interaction, you should build them as custom components.

Interacting with a loaded Flex application

The following example, in the file FlexApp.mxml, shows a simple Flex application that defines two Label controls, a variable, and a method to modify the variable:

<?xml version="1.0"?>
<!-- controls\swfloader\FlexApp.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="100" width="200">

    <fx:Script>
        <![CDATA[
            [Bindable]
            public var varOne:String = "This is a public variable.";

            public function setVarOne(newText:String):void {
                varOne=newText;
            }
        ]]>
    </fx:Script>
    <s:VGroup>
        <s:Label id="lblOne" text="I am here."/>
        <s:Label text="{varOne}"/>
        <s:Button label="Nested Button" click="setVarOne('Nested button pressed.');"/>
    </s:VGroup>
</s:Application>

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

You compile this example into the file FlexApp.SWF, and then use the SWFLoader control to load it into another Flex application, as the following example shows:

<?xml version="1.0"?>
<!-- controls\swfloader\SWFLoaderInteract.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"
    backgroundColor="gray"
    height="200">

    <fx:Script>
        <![CDATA[
            import mx.managers.SystemManager;
            
            [Bindable]
            public var loadedSM:SystemManager;

            // Initialize variables with information from
            // the loaded application.
            private function initNestedAppProps():void {
                loadedSM = SystemManager(myLoader.content);
                
                // Enable the buttons after the application loads.
                b1.enabled = true;
                b2.enabled = true;
                b3.enabled = true;
            }

            // Update the Label control in the outer application
            // from the Label control in the loaded application.
            public function updateLabel():void {
                lbl.text=loadedSM.application["lblOne"].text;
            }

            // Write to the Label control in the loaded application.
            public function updateNestedLabels():void {
                loadedSM.application["lblOne"].text = "I was just updated.";
                loadedSM.application["varOne"] = "I was just updated.";
            } 
            
            // Write to the varOne variable in the loaded application
            // using the setVarOne() method of the loaded application.
            public function updateNestedVarOne():void {
                loadedSM.application["setVarOne"]("Updated varOne!");
            }
        ]]>
    </fx:Script>
    <s:VGroup> 
        <s:Label id="lbl"/>
        <mx:SWFLoader id="myLoader" width="300"
            source="FlexApp.swf"
            complete="initNestedAppProps();"/>
        <s:Button id="b1" label="Update Label Control in Outer Application" 
            click="updateLabel();"
            enabled="false"/>
        <s:Button id="b2" label="Update Nested Controls" 
            click="updateNestedLabels();"
            enabled="false"/>    
        <s:Button id="b3" label="Update Nested varOne" 
            click="updateNestedVarOne();"
            enabled="false"/>
    </s:VGroup>
</s:Application>

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

In this example, the FlexApp.swf file is in the same directory as the main application. Modify the path to the file appropriately for your application.

Notice that this application loads the SWF file at run time; it does not embed it. For information on embedding a Flex application by using the SWFLoader tag, see Embedding assets.

You use the complete event of the SWFLoader control to initialize a variable with a reference to the SystemManager object for the loaded Flex application.

When a user clicks the first Button control in the outer application, Flex copies the text from the Label control in the loaded application to the Label control in the outer application.

When a user clicks the second Button control, Flex writes the text to the Label control and to the varOne variable defined in the loaded application.

When a user clicks the third Button control, the setVarOne() method of the loaded application writes to the varOne variable defined in the loaded application.

Note: When working with loaded SWF files, consider using modules rather than the SWFLoader control. For more information on creating modular applications, see Modular applications.

The level of interoperability between a main application and a loaded application depends on the type of loaded application:

Sandboxed
Sandboxed applications are loaded into their own security domains, and can be multi-versioned. Using sandboxed applications is the recommended practice for third-party applications. In addition, if your loaded applications use RPC or DataServices-related functionality, you should load them as sandboxed. For more information, see Developing sandboxed applications.

Multi-versioned
Multi-versioned applications are those that can be compiled with different versions of the Flex framework than the main application that loads them. Their interoperability with the main application and other loaded applications is more limited than single-versioned applications. For more information, see Developing multi-versioned applications.

Single-versioned
Single-versioned applications are applications that are guaranteed to have been compiled with the same version of the compiler as the main application. They have the greatest level of interoperability with the main application, but they also require that you have complete control over the source of the loaded applications. For more information, see Creating and loading sub-applications.

Externalizing application classes

To reduce the size of the applications that you load by using the SWFLoader control, you can instruct the loaded application to externalize framework classes that are also included by the loading application. The result is that the loaded application is smaller because it only includes the classes it requires, while the framework code and other dependencies are included in the loading application.

To externalize framework classes, you generate a linker report from the loading application by using link-report option to the mxmlc command. You then use the load-externs option to the mxmlc compiler to specify this report when you compile the loaded application.

Externalize framework classes

  1. Generate the linker report for the loading application:

    mxmlc -link-report=report.xml MyApplication.mxml
  2. Compile the loaded application by using the link report:

    mxmlc -load-externs=report.xml MyLoadedApplication.mxml
  3. Compile the loading application:

    mxmlc MyApplication.mxml
Note: If you externalize the loaded application’s dependencies by using the load-externs option, your loaded application might not be compatible with future versions of Adobe Flex. Therefore, you might be required to recompile the application. To ensure that a future Flex application can load your application, compile that module with all the classes it requires.

For more information, see Flex compilers.

Sizing a SWFLoader control

You use the SWFLoader control’s scaleContent property to control the sizing behavior of the SWFLoader control. When the scaleContent property is set to true, Flex scales the content to fit within the bounds of the control. However, images will still retain their aspect ratio by default.

Styling loaded applications

When you use the SWFLoader control to load a loaded application, the loaded application uses the same rules for applying styles as modules.

For more information, see Using styles with modules.