An application domain is a container for class definitions. Applications have a single, top-level application domain called the system domain. Application domains are then defined as child nodes of the system domain. When you load a sub-application into another, main application, you can load it into one of three application domains: sibling, child, and current. When you load a sub-application into a sibling application domain, the sub-application's application domain has the same parent as the main application's application domain. In addition, it is a peer of all other sibling applications.

When you load a sub-application into a child application domain, the sub-application's application domain is a child of the main application's application domain. When you load a sub-application into a current application domain, the sub-application is loaded into the same application domain as the main application. Each of these locations defines where the sub-application can get its class definitions from.

The default behavior of the SWFLoader and Loader controls is to load a sub-application into a child application domain. If the sub-application and the main application are compiled with different versions of the Flex framework, runtime errors can result. These errors occur because the applications are sometimes compiled against different definitions of the same classes.

You specify the application domain of a sub-application by setting the value of the loadForCompatibility property on the SWFLoader. If you set the value of this property to true, then the sub-application is loaded into a sibling application domain. If you set the value of this property to false, then the sub-application is loaded into a child application domain. The default value of this property is false, so by default, sub-applications are not multi-versioned.

You can also specify the application domain on the LoaderContext object. You do this if you specify the value of the loaderContext property when using the SWFLoader control. For more information, see Specifying a LoaderContext.

Security domains define the level of trust between applications. The greater the trust between applications, the greater the amount of possible interoperability between those applications. In general, if a sub-application is loaded into the same security domain as the main application, then the applications have the highest level of interoperability.

If a sub-application is loaded into a different security domain (as is the case with many remote or multi-versioned applications), then the sub-application is allowed a limited amount of interaction with the main application. Sub-applications in separate security domains are also restricted in their ability to communicate with one another. They are known as sandboxed applications.

You determine whether a sub-application is loaded into the same security domain as the main application when you load it. You can set the value of the trustContent property to true to load a remote sub-application into the same security domain as the main application. This behavior only applies if that application is loaded from a different web domain or subdomain than the main application. If the sub-application is loaded from the same web domain as the main application, then it is by default loaded into the same security domain. Setting the value of the loadForCompatibility property does not affect the trustContent property.

In some cases, you want to load a sub-application that is on the same domain as the main application into a separate security domain. This might be because the sub-application is from a third party or you want you applications to have the same level of interoperability as a sandboxed application. One way to do this is to set up a different sub domain name on the same server, and load the sub-application from that sub domain. For more information, see Loading same-domain and cross-domain applications.

When using AIR, you cannot set the value of the trustContent property to true.

If you do not set the value of the trustContent property to true, then a sub-application on a remote server is loaded into a separate security domain by default.

You can also specify the security domain on the LoaderContext object. You do this if you specify the value of the loaderContext property when using the SWFLoader control. You can only do this if you want to load the sub-application into the same security domain. For more information, see Specifying a LoaderContext.

Sandboxed applications have the greatest number of limitations on application interoperability. These restrictions include the following:

Stage

Access to the stage from the sub-application is limited to some stage properties and methods.

Mouse

You cannot receive mouse events from objects in other security domains.

Pixels

Applications cannot access the pixels drawn in applications that are in other security domains.

Properties

While applications can get references to objects in other security domains, avoid doing this for security reasons. Some properties are restricted, such as the Stage or any parent of a DisplayObject that another application instantiates. In addition to these restrictions, applications that are in separate security domains are also in separate application domains by definition. As a result, they are subject to all restrictions of that architecture. However, they can also benefit from this situation because they can then be multi-versioned.

For more information about working with sandboxed applications, see Developing sandboxed applications

Common types of applications that load sub-applications include:

• Large applications that are or are not multi-versioned

• Mashups

• Portals

• Dashboards

The manager classes handle various tasks of the application. For example, the DragManager handles all the drag-and-drop functionality; this manager class is responsible for marshaling data, creating the DragProxy, and triggering drag-related events.

When sub-applications are loaded into the same application domain as the main application, the application domain contains only a single instance of each manager. When applications are in different application domains, though, there can be more than one instance of a manager in the system domain.

Depending on the type of task, the manager classes are sometimes allowed to communicate through event passing when a main application loads a sub-application. For example, the FocusManager in a sub-application receives control from the FocusManager in the main application when the focus shifts to the sub-application. When the focus shifts away from the sub-application, the sub-application's FocusManager passes control back to the main application's FocusManager.

In other cases, there can only be one active instance of a manager in the system domain. Flex ensures that the sub-application's manager is disabled. For example, the BrowserManager cannot have multiple instances. Only the main application can access it, and only the main application can communicate with it, unless the sub-application is in a child application domain of the main application. If a sub-application in a separate application domain wants to communicate with the BrowserManager, it must do so through the main application.

In this case you would have to create custom logic that handles interaction with manager classes. For example, if you want a sub-application to use the main application's deep linking, you can create a custom class. This custom class passes messages from the sub-application to the main application, where the BrowserManager can be communicated with.

What typically happens is that the top-level manager handles the user interaction. This manager receives messages from the sub-application's manager that instructs it on what to do.

The following manager classes are linked in by all applications:

• SystemManager

• LayoutManager

• StyleManager

• EffectManager

• ResourceManager (which links in ModuleManager)

• FocusManager

• CursorManager

• ToolTipManager

The following manager classes are linked in only when used in an application:

• DragManager

• BrowserManager

• HistoryManager (deprecated)

• PopUpManager (note that if a sub-application uses pop-up controls, the main application must include a definition of this manager)

If a main application loads sub-applications that are compiled with the same version of the framework, only one definition of each manager is stored in the SWF file. However, if you have a sandboxed or multi-versioned sub-application, both the main application and the sub-application store their own definitions. In many cases, the manager classes in the sub-application pass messages to the main application's instance of the manager. The main application's manager can then handle the task.

With sandboxed or multi-versioned applications, both the main application and the sub-application have their own versions of the manager classes. In single-versioned applications, only one version of most manager classes is necessary. You can externalize the definition of a manager in many cases for applications that are not multi-versioned.

All applications have an instance of the SystemManager class. If an application is loaded into another application, a SystemManager for the sub-application is still created. The SystemManager still manages the sub-application's application window, but it might not manage pop-up controls, tool tips, and cursors, depending on the way in which the sub-application was loaded. The content of the SWFLoader that loaded the sub-application contains a reference to the sub-application.

The SystemManager of the main application is important because it gives you access to many aspects of the entire application. For example, the top-level SystemManager does the following:

• Parents all pop-up controls, ToolTip objects, and cursors in the main application and all trusted sub-applications

• Handles focus for all applications that are trusted

You can use a reference to the top-level SystemManager to register to listen for events in a sub-application. For example, your sub-application can listen for mouse events that are outside its application domain by adding listeners to the top-level SystemManager.

The way you access the top-level SystemManager from a sub-application depends on the type of sub-application that you are using.

To get access to the top-level SystemManager in an architecture where sub-applications are loaded into child application domains, you use the topLevelSystemManager property of the SystemManager. The following image shows that the sub-applications use the systemManager.topLevelSystemManager to access the SystemManager in the main application.

For a code example that uses the topLevelSystemManager property to access the main application's SystemManager, see Listening for mouse events with loaded applications.

For single-versioned applications, the topLevelSystemManager property always refers to the top-level SystemManager in an application domain. If your applications are in separate application domains (as sandboxed or multi-versioned applications are), use the getSandboxRoot() method to get the top-level SystemManager for that security domain.

The following image shows that the sub-applications use the systemManager.getSandboxRoot() to get a reference to the main application's SystemManager, which is in a separate application domain.

For a code example that uses the getSandboxRoot() method to access the main application's SystemManager, see Listening for mouse events in multi-versioned applications.

When a sub-application is in a different security domain as the main application (or not trusted, such as in a sandboxed application), you cannot get a reference to the main application's SystemManager from the sub-application. In this case, you can listen for a SandboxMouseEvent and InterDragManagerEvent for inter-application communication. Any application can trigger these events. The sub-application's SystemManager gets notification of them, at which point you can handle them in the sub-application.

The following image shows an architecture where two applications, in separate security domains, communicate through event passing. The sub-application calls the getSandboxRoot() method to get a reference to its own SystemManager. The SystemManager can then listen for events that the main application's SystemManager dispatched.

The properties of a SandboxMouseEvent object are not the same as the properties in a typical event object. For example, the target and currentTarget properties are the SandboxBridge that dispatched the event, or the SystemManager that redispatched it. These properties are not the specific object that dispatched the event. Untrusted child applications should not be able to get references to objects that are typically specified by these properties. Similarly, the stageX, stageY, localX, and localY properties are not available.

For an example that uses the SandboxMouseEvent object to handle mouse events outside a sub-application's security domain, see Listening for mouse events with sandboxed applications.

When you design a large application, give some consideration to its architecture. If the application has one main application that loads and unloads subordinate applications, then weigh the benefits of using either modules or sub-application when deciding which approach to take.

Consider the example of an application composed of many forms. In a modular application, a main application loads each form as a module with the ModuleManager. In an application that uses sub-applications, each form is a separate application that the SWFLoader loads into the main application. These two approaches are similar in many ways, but also have many differences.

Many of the reasons to use modules also apply to sub-applications. Main applications usually load sub-applications rather than embed their functionality. The result is generally a smaller initial download size and shorter load time for the main application. In addition, this promotes better encapsulation of related functionality, which can make development and maintenance easier.

Modules and sub-applications have the following similarities:

• Are compiled SWF files

• Can be loaded and unloaded at run time

• Promote encapsulation of related functionality

• Allow for an asynchronous development environment

• Can be recompiled without having to recompile the main application

• Support debugging

• Can be loaded locally or remotely (with the appropriate permissions)

• Are cached by the browser

• Can be preloaded

• Support progress events for getting the status while loading

• Can dynamically access methods and properties of the main application

Modules and sub-applications are also different. The main difference is that modules typically share classes with their host application. This sharing of classes creates a dependency between the module and the main application. Sub-applications, on the other hand, typically have their own versions of the classes, so less dependency exists between them and the main application.

Other differences between modules and sub-applications include the following:

File size

Modules and their host applications are often smaller in file size because you can externalize shared classes. You can't always externalize shared classes for sub-applications. In cases where the versions of the applications are different, each application must have its own set of classes.

Reuse

Modules are more tightly bound to the host application. They use interfaces to communicate with the loading application. This means that as your application changes, if your application uses modules, you'll probably need to recompile all of them if you move the main application to a later version of Flex.

Versioning

Modules do not support multi-versioning. The main application and all modules must be compiled by the same version of the Flex framework. In a mult-versioned application, the sub-applications can be compiled with different versions of the compiler, as long as the compiler is the same or older than the compiler used to compile the main application.

Manager classes

Modules and their host applications typically share manager classes. The modules are in a child application domain, whereas sub-applications often have their own instance of the manager class so that they can be multi-versioned. An exception is the StyleManager class; modules each define their own instance of type IStyleManager2.

ActionScript-only

Modules can be either MXML-based or ActionScript-only; applications and sub-applications are not typically pure ActionScript.

Application domains

sub-applications can be loaded into sibling application domains or child application domains, whereas modules must be loaded into a child application domain of the host application.

Security domains

Modules must be loaded into the same security domain as their host application. Sub-applications can be loaded into either the same security domain or a different security domain.

For more information about modules, see Modular applications.

You can use the SWFLoader and Loader classes to load sub-applications into a main application. In most circumstances, use the SWFLoader class. This class wraps the Loader class and provides additional functionality that makes it easier to use for loading sub-applications into main applications.

The SWFLoader control has the following features:

• Supports Flex styles and effects; the Loader class does not have any inherent support for styles and effects.

• Lets you monitor the progress of a load inherently (if you use the Loader class, you have to first get a reference to a LoaderInfo object).

• Is a UIComponent. As a result, the SWFLoader control participates in the display list and adds children to the display list without having to write additional code.

• Resizes and scales the contents automatically.

• Does not require that the SWF file be an instance of the Application class, it just checks if an Application exists, and handles sizing differently.

• Can be multi-versioned. The Loader class does not have built-in support for multi-versioning.

Whenever you have a main application and sub-applications that are in different application domains, the recommended way to communicate between the applications is through event passing. If something that happens in the sub-application affects the main application, the sub-application triggers an event. This event can be caught in the main application. The event defines the properties necessary to respond to the event. For example, suppose a user moves the mouse pointer over a control in a sub-application that has a ToolTip. The sub-application's ToolTipManager creates the ToolTip and sends an event that requests the main application's ToolTipManager to display it. This interaction works across application domains that are within the same security domain.

Communication across security domains use the LoaderInfo.sharedEvents dispatcher and custom events. This process is largely transparent to you; you only need to know which events to register with event listeners. The LoaderInfo.sharedEvents class dispatches events in a sub-application that should be handled by a manager in the main application. The event contains data that define it, and that data is marshaled across the security domain. It is important to note that custom event classes cannot be strongly typed across the security domain by the receiver. Only classes defined by Flash Player can be strongly typed.

In many cases, communicating across security domains is transparent to the developer. The Flex framework handles the details of event passing and data marshaling for you. For example, when using functionality managed by the FocusManager or PopUpManager, you do not generally write additional code to make application interoperability work. The underlying Flex classes trigger the events and marshal the data across the domains so that the experience is seamless. In some cases, such as when you use custom classes to define objects, you must write custom code to marshal the data across the security domain.

The level of interaction that a main application and sub-application have depends on the level of trust between them. They can be trusted or untrusted. By default, applications that are loaded from a different web domain are untrusted, and applications that are loaded from the same web domain are trusted. You can, however, make a cross-domain application trusted.

Same-domain applications are applications that are loaded into the main application from the same web domain as the main application. By default, they are loaded into the same security domain and are trusted. Trusted applications can be loaded into the same application domain as the main application, which means they share their class definitions with the main application. They can also be loaded into a different, sibling application domain, which means that they contain their own definitions for all their classes and can be multi-versioned (as long as they are compiled with the same or older version of the compiler that the main application was compiled with).

Cross-domain applications are applications that are loaded into a main application from a different web domain as the main application. For example, if the main application is located at domainA.com, and the sub-application is located at domainB.com, then the sub-application is a cross-domain application. Cross-domain applications are often known as untrusted applications, although you can specify that a remote application be trusted (except when using AIR).

Untrusted applications are loaded into a different security domain as the main application. As a result, Flash Player provides only limited interoperability between applications that do not trust each other because of the security concerns.

You can load the content of any SWF file from any web domain regardless of whether target web server has a policy file, but you need permissions to read the SWF file's data. To load a cross-domain application and access its data, the target server that hosts the remote sub-application must have a policy file called crossdomain.xml on it. This file must specifically allow access from the source server. In the previous example, if you wanted to access the loaded application's data, domainB must have a policy file on it that lets domainA load from it. Without a policy file, Flash Player throws a security error if it tries to access the application's data. A policy file must be in the root of the domain, or its location must be specified explicitly in the loading application. For more information about the crossdomain.xml file, see Using cross-domain policy files.

Sub-domains that are not the same, such as www1.domainA.com and www2.domainA.com, also apply when deciding if a sub-application is cross-domain or not. In this example, if the main application is on www1.domainA.com, and the sub-application is on www2.domainA.com, then the sub-application is considered untrusted by default. To load data from the sub-application, the sub-application's domain would require a policy file.

Cross-domain applications can be "import loaded," which means that they are loaded into the same security domain as the main application. You do this by setting the trustContent flag to true on the SWFLoader, or by specifying that the application load into the same security domain domain on the LoaderContext. You should only import load a cross-domain application if you know for sure that it can be trusted. For more information on using the LoaderContext to load sub-applications, see Specifying a LoaderContext.

Another way to load cross-domain applications into the same security domain is to use the Security.allowDomain() method. You first load the application as a sandboxed application (from a different web domain, without setting the trustContent property to true). In the main application, you call the allowDomain() method on the sub-application's domain in the SWFLoader control's complete event handler. In the sub-application, you call the allowDomain() method on the main application's domain. You must make this call early in the sub-application's lifecycle. For example, in the application's preinitialize event. If you use the allowDomain() method to load applications, you do not need a crossdomain.xml file on the target domain.

You can load a local (or same-domain) application into a different security domain. To do this, you can use a URL string for the SWFLoader's source property that is different from the path to the main application. For example, you could specify an IP address for the source property. When Flash Player compares the domain names, they are recognized as different, and the sub-application loads as an untrusted application. This is a common approach if you want to the loaded application to be sandboxed, but deploy the applications into the same web domain. You could also create separate sub domains on the same server to ensure that the sub-application is loaded into a separate security domain.

Sub-applications access remote data based on the way that they were loaded. If you import load an application, the sub-application is effectively running from within the main application's security domain. As a result, it would now need permissions to access data on its domain of origin. If you load a sub-application into a separate security domain, it runs within its original domain and can access resources on that domain as normal.

The SWFLoader control lets you load one application into another application. 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.

To load a SWF file into a SWFLoader control, you set the value of the SWFLoader control's source property. This property defines the location of the sub-application's SWF file. After you set the value of the source property, Flex imports the specified SWF file and runs it. For simple examples of using the SWFLoader tag in an application, see Creating a SWFLoader control.

In addition to SWF files, the SWFLoader control can also load several types of images (such as JPG, PNG, and GIF files) as SWF files. You cannot load a module, RSL, or style module with the SWFLoader control.

The default behavior for the SWFLoader control depends on the location of the loaded SWF file. If the loaded application is loaded locally, the default is to load the SWF file into the same security domain, and a child application domain. This loads an application that is trusted but single-versioned.

If the loaded application is loaded from a different server or in a separate sub domain than the main application, then the default is to load the application into a separate security domain and a separate, sibling application domain. The result is a multi-versioned application, but one that has some restrictions on it because it is untrusted by default. This is the recommended approach for all third-party applications, or any multi-versioned applications that use RPC classes or DataServices-related functionality.

When loading any application, you can explicitly set the values of properties on the SWFLoader control that set the application domain and the security domain. These properties define the trust level between the main application and the sub-application, and determine whether the applications are multi-versioned. The following table describes these properties of the SWFLoader control.

myLoader.unloadAndStop(true);

You can also set the SWFLoader's source property to null. This results in a call to the SWFLoader.content.loaderInfo.loader.unload() method. You can call this method explicitly, but only for trusted applications.

To free up the memory that was used by the loaded sub-application, ensure that no references to objects or classes in the sub-application exist. The unload() method frees the loader's reference to the sub-application's bytes, but if code in the sub-application is still in use, then it is not garbage collected.

Flash Player also unloads a sub-application when the same SWFLoader control loads a new sub-application. The original content is removed before the new application is loaded.

Typically, you load a style module into the main application's application domain. If the sub-application contains any user interface classes (such as skins) that are not in the main application, the styles for those classes are loaded into the main application's StyleManager. When you unload the sub-application, the sub-application's memory is not freed up. In this case, load style modules into the sub-application's application domain.

There are several ways to access the methods and properties of the main application from the sub-application. These ways only work for sub-applications that are loaded as children into a main application's application domain. You cannot use these for sandboxed applications, or for multi-versioned applications.

These methods include:

• Using the application property of the Application class. This property accesses the root application from anywhere in the application. For more information, see Accessing document and application scopes.

• Using the parentDocument property of the Application class. This is useful if you have multiple applications embedded and want to just access the immediate parent. For more information, see Accessing document and application scopes.

Be aware that you might encounter security errors if you try to access members that should not be accessed.

Although you can access the sub-application from the main application, you cannot directly reference methods and properties. This is because the members of the sub-application, unless it is embedded at compile-time, are not known by the compiler when the main application compiles.

You can, however, get a reference to the sub-application's SystemManager. You can then treat members of the sub-application as dynamic properties and methods of the sub-application's object.

The following example loads a remote sub-application into the SWFLoader. It sets the value of the trustContent property to true so that the sub-application is loaded into the same security domain as the main application. It casts the content property of the SWFLoader to a SystemManager so that the application's members can be accessed dynamically. It then calls a method and accesses a property of the sub-application.

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/MainAppUsingSubAppMembers.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.managers.SystemManager; 
 
               private function getValueFromSubApp():void { 
                    /* Cast the SWFLoader's content as a SystemManager 
                      to access the sub-application. */ 
                    var subApp:SubApp2 = 
                         (contentLoader.content as SystemManager).application as SubApp2; 
 
                    /* Call a method and access a property of the 
                      sub-application. */ 
                    label1.text = subApp.doSomething() + subApp.answer; 
               } 
          ]]> 
     </fx:Script> 
     
     <mx:SWFLoader id="contentLoader" visible="false" 
          height="0" width="0" 
          trustContent="true" 
          source="http://yourdomain.com/SubApp2.swf"/>   
     <mx:Panel id="myPanel2" 
          paddingLeft="10" paddingBottom="10" 
          paddingTop="10" paddingRight="10"> 
          <s:Label id="label1"/> 
          <s:Button id="b2" label="Call SubApp2" click="getValueFromSubApp()"/> 
     </mx:Panel> 
     
</s:Application>

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/SubApp2.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[ 
               // Define a public property. 
               public var answer:int = 42; 
          
               // Define a public method that returns a String. 
               public function doSomething():String { 
                    return "The answer is "; 
               } 
          ]]> 
     </fx:Script> 
</s:Application>

If the sub-application is loaded remotely, you can access its members only if it is in the same security domain as the main application, or if you and the sub-application call the Security. allowDomain() method. In this case, you must call the Security.allowDomain() method from the main application on the sub-application's domain, and the sub-application must call this method on the main application's domain. You must also call the allowDomain() method early in the sub-application's lifecycle. For example, call it in a preinitialize event handler.

You can create instances in a main application of classes that are defined in a loaded sub-application. You can then add these objects to your main application and interact with them as you would interact with any other object in the display list. To access class definitions in a sub-application, you get the definitions from the sub-application's application domain.

Each application domain contains definitions of all the classes within it. There is an applicationDomain object that you access with a reference to the loaded application's LoaderContext. The ApplicationDomain object has two methods, hasDefinition() and getDefiniton(). The hasDefinition() method lets you detect if a class definition exists. If a class definition exists, the getDefinition() method lets you create an instance of that class in your main application.

You can't add a UIComponent that is defined in another application domain to the main application's display list. As a result, to create an instance of a class that is defined in another application domain, the sub-application must be loaded into a child application domain of the main application's application domain (you cannot set the value of the SWFLoader's loadForCompatibility property to true). The sub-application must also be in the same security domain as the main application (trustContent must be true).

You can only create the instance of the class dynamically when the class is defined in an application that is loaded at run time. This is because the compiler does not have access to classes in loaded applications at compile time, so it cannot check linkages. If the sub-application was embedded at compile time, then you would not have to create the instance dynamically, the class definition would be available to the compiler. In this case, you could instead use the new keyword with the specific class type rather than a generic Class type.

The following example main application loads a sub-application with the SWFLoader control. It sets the value of the trustContent property to true and defines a method, createClassInstance(). This method gets the definition of the custom class from its loaded application's application domain. The example then creates an instance of this class and sets a property on it before adding it to the display list.

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/MainAppUsingSubAppDefinitions.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; 
               public function createClassInstance():void { 
                    // Check that the definition exists. 
                    if (contentLoader.loaderContext.applicationDomain.hasDefinition('MyRedButton')) { 
                         var objClass:Class = contentLoader.loaderContext.applicationDomain.getDefinition('MyRedButton') as Class; 
                         if (objClass != null) { 
                              var newObject:UIComponent = UIComponent(new objClass()); 
 
                              // Set properties on the custom class as an associative array. 
                              newObject["label"] = "Click Me";   
                              
                              // Add the new instance to the second panel in this application. 
                              myPanel2.addChild(newObject); 
                         } 
                    }                   
               } 
          ]]> 
     </fx:Script> 
 
     <!-- The SWFLoader in the first panel loads the 
           sub-application that contains a definition of MyRedButton. --> 
     <mx:Panel id="myPanel" title="SubApp1 Loaded by main application"> 
          <mx:SWFLoader id="contentLoader" 
            trustContent="true" 
            source="SubApp1.swf"/>     
     </mx:Panel> 
 
     <!-- This application adds an instance of the MyRedButton 
           class to the second panel after the content is loaded. --> 
     <mx:Panel id="myPanel2" title="Instance of a Class Defined By SubApp1"/> 
     
</s:Application>

Also notice that the createClassInstance() method is public. If it were private, the sub-application would not be able to call it.

The sub-application, SubApp1.swf, statically links a custom class called MyRedButton. It also calls the parent application's method when it is done. You cannot call that method in the parent application's applicationComplete event, because that event will likely be triggered too early in the initialization process. Wait for the sub-application to complete its loading and initialization before you create an instance of a class that is defined in it.

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/SubApp1.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" 
    xmlns:custom="*" 
    creationComplete="initApp()" 
    applicationComplete="mx.core.FlexGlobals.topLevelApplication.createClassInstance()"> 
 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
     <fx:Script> 
          <![CDATA[ 
               private function initApp():void { 
                    var child:DisplayObject = getChildAt(0); 
                    var childClassName:String = getQualifiedClassName(child); 
                    
                    // Show that the qualified class name of the custom button is MyRedButton. 
                    trace(childClassName); 
               } 
          ]]> 
     </fx:Script> 
 
     <custom:MyRedButton id="myRedButtonId" label="Click Me"/> 
 
</s:Application>

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/MyRedButton.mxml --> 
<s:Button 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    color="red"> 
</s:Button>

It is possible to listen for mouse events in a main application from a loaded sub-application that is in a child application domain. To listen for these events, you listen for events such as MOUSE_UP and MOUSE_MOVE on the sub-application's systemManager.topLevelSystemManager. When the sub-application is in a child application domain, the topLevelSystemManager property refers to the main application's SystemManager.

The following application shows how to access mouse events on the topLevelSystemManager in a sub-application that was loaded into a child application domain. If the sub-application is not in a child application domain, then you must handle access to the SystemManagers differently. For more information, see the examples in Listening for mouse events with sandboxed applications and Listening for mouse events in multi-versioned applications.

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/ZoomerPattern2.mxml --> 
<s:Application 
    creationComplete="setup()" 
    height="250" 
    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.managers.PopUpManager; 
 
          [Bindable] 
          public var data1:Array = ["Ice Cream", "Fudge", "Whipped Cream", "Nuts"]; 
 
          public var zoomTool:UIComponent; 
 
          public function setup():void { 
               // Draw the zoom rectangle. 
               zoomWidget.graphics.lineStyle(1); 
               zoomWidget.graphics.beginFill(0, 0); 
               zoomWidget.graphics.drawRect(0, 0, 17, 17); 
               zoomWidget.graphics.endFill(); 
 
               // Listen for mouse down events. 
               zoomWidget.addEventListener(MouseEvent.MOUSE_DOWN, zoom_mouseDownHandler); 
          } 
 
          private var lastX:int; 
          private var lastY:int; 
 
          private function zoom_mouseDownHandler(event:MouseEvent):void { 
               // When the mouse is down, listen for the move and up events.              
               systemManager.topLevelSystemManager.addEventListener( 
                    MouseEvent.MOUSE_MOVE, zoom_mouseMoveHandler, true); 
               systemManager.topLevelSystemManager.addEventListener( 
                    MouseEvent.MOUSE_UP, zoom_mouseUpHandler, true); 
 
               // Update the last position of the mouse. 
               lastX = event.stageX; 
               lastY = event.stageY; 
 
               // Create and pop up the zoomTool. This is what is dragged around. 
               // It must be a popup so that it can float over other content. 
               zoomTool = new UIComponent(); 
               PopUpManager.addPopUp(zoomTool, this); 
               var pt:Point = new Point(zoomWidget.transform.pixelBounds.x, 
                    zoomWidget.transform.pixelBounds.y); 
               pt = zoomTool.parent.globalToLocal(pt); 
               zoomTool.x = pt.x; 
               zoomTool.y = pt.y; 
               zoomTool.graphics.lineStyle(1); 
               zoomTool.graphics.beginFill(0, 0); 
               zoomTool.graphics.drawRect(0, 0, 17, 17); 
               zoomTool.graphics.endFill(); 
 
               // Hide the rectangle that was the target. 
               zoomWidget.visible = false; 
          } 
 
          private function zoom_mouseMoveHandler(event:MouseEvent):void { 
               // Update the position of the dragged rectangle. 
               zoomTool.x += event.stageX - lastX; 
               zoomTool.y += event.stageY - lastY; 
               lastX = event.stageX; 
               lastY = event.stageY; 
 
               var bm:BitmapData = new BitmapData(16, 16); 
               
               // Capture the bits on the screen. 
               bm.draw(DisplayObject(systemManager.topLevelSystemManager), new 
                    Matrix(1, 0, 0, 1,  -zoomTool.transform.pixelBounds.x - 2, 
                    -zoomTool.transform.pixelBounds.y - 2)); 
 
               // Create a Bitmap to hold the bits. 
               if (zoomed.numChildren == 0) { 
                    var bmp:Bitmap = new Bitmap(); 
                    zoomed.addChild(bmp); 
               } else 
                    bmp = zoomed.getChildAt(0) as Bitmap; 
 
               // Set the bits. 
               bmp.bitmapData = bm; 
 
               // Zoom in on the bits. 
               bmp.scaleX = bmp.scaleY = 8; 
          } 
 
          private function zoom_mouseUpHandler(event:Event):void { 
               // Remove the listeners. 
               systemManager.topLevelSystemManager.removeEventListener( 
                    MouseEvent.MOUSE_MOVE, zoom_mouseMoveHandler, true); 
               systemManager.topLevelSystemManager.removeEventListener( 
                    MouseEvent.MOUSE_UP, zoom_mouseUpHandler, true); 
 
               // Replace the target rectangle. 
               zoomWidget.visible = true; 
 
               // Remove the dragged rectangle. 
               PopUpManager.removePopUp(zoomTool); 
          } 
 
     ]]> 
     </fx:Script> 
     
     <mx:HBox> 
          <mx:HBox backgroundColor="0x00eeee" height="140" paddingTop="4" paddingRight="4"> 
               <mx:Label text="Drag Rectangle"/> 
               <mx:UIComponent id="zoomWidget" width="17" height="17"/> 
               <mx:Canvas id="zoom" 
                    borderStyle="solid" 
                    width="132" 
                    height="132" 
               > 
                    <mx:UIComponent id="zoomed" width="128" height="128"/> 
               </mx:Canvas> 
          </mx:HBox> 
          <mx:List dataProvider="{data1}"/> 
     </mx:HBox> 
</s:Application>

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/MainZoomerPattern2.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> 
 
     <mx:Text text="Default (trusted application in child ApplicationDomain):"/> 
     
     <mx:SWFLoader id="swf1" source="ZoomerPattern2.swf"/> 
     
</s:Application>

This example application uses the systemManager.topLevelSystemManager property to get a reference to the main application's SystemManager. If the application were a stand-alone application, you could use the systemManager property to register event listeners, as the following example shows:

 systemManager.addEventListener(MouseEvent.MOUSE_MOVE, zoom_mouseMoveHandler, true); 
 systemManager.addEventListener(MouseEvent.MOUSE_UP, zoom_mouseUpHandler, true);

This works when the application is a stand-alone application, but not when the application is loaded as a child. The top-level SystemManager, which is not the sub-application's SystemManager, parents the zoomTool class.

Applications and modules in the same application domain are able to use the same embedded fonts by specifying the font name. For example, a font embedded in the main application can be used by a sub-application, as long as the applications are in the same application domain.

Models that are implemented as singletons, and other singletons that the main application and its sub-applications share, do not work if the sub-application and main application are in separate application domains.

To share models and other singletons, you can write your own marshaling code or create a bootstrap loader that stores definitions of those classes.

You should not share data models and other singletons with untrusted applications.

Single-versioned applications can share RSLs with other sub-applications and the main application to minimize the number of classes that are loaded. This results in faster load times and smaller file sizes. Multi-versioned or sandboxed applications cannot share RSLs.

Starting with Flex 4.5, sub-applications work much more efficiently with RSLs. The main application only loads those framework RSLs that are needed at startup, and creates placeholders for all remaining framework RSLs. The sub-application does not try to load RSLs that are already loaded by the main application. If the sub-application needs one of the framework RSLs that are not initially loaded by the main application, then the sub-application loads the RSL.

In addition, when a sub-application loads an RSL, you can specify which domain the RSL is loaded into with the application-domain compiler argument. This applies to both framework RSLs and custom RLSs. This lets you load an RSL into the parent, current, or top-level application domains.

When you develop sandboxed or multi-versioned applications, you cannot always externalize overlapping class definitions, because the class definitions might be different. For example, if two applications are compiled with different versions of the Flex framework, then each application must have its own definition of the manager classes (such as the LayoutManager or the CursorManager) and other classes in the framework. As a result, do not externalize those classes by compiling the applications against the same RSLs.

In previous versions of Flex, you were required to initialize certain manager classes such as the FocusManager if you loaded a module or sub-application into a main application that did not use those manager classes. You are no longer required to do this if you load the sub-application into a sibling application domain where each application has its own class definitions. However, each security domain must include a definition of the PopUpManager class in case an untrusted sub-application displays a modal dialog box.

For information on using RSLs with sub-applications, see Using RSLs with modules and sub-applications.

Pop-up controls are parented by the application at the sandbox root of their security domain. This is because the sandbox root handles requests to display a modal window from its children.

Because pop-up controls are parented by the sandbox root, centering a popup in a sandboxed application centers it in the area of the screen occupied by the sub-application and not the entire application. It also means that pop-up controls are sometimes clipped by scroll bars and masks on the sub-application.

A sub-application in a separate security domain from the main application has the following behavior:

• Launching a modal dialog box dims the entire application, but the pop-up can only be dragged within the boundaries of the sub-application.

• Centering a pop-up centers it over the sub-application, not the main application.

• Dragging pop-up controls works over the sub-application only. If you drag a pop-up outside the sub-application, it is clipped.

• Focus shifts to the pop-up control when you first launch a pop-up.

A sandboxed application cannot display a window or dialog box outside the bounds of its application. This rule prevents an untrusted application from phishing for passwords by displaying a dialog box on top of all the applications. When displaying a popup window, the PopUpManager checks if the parent application trusts it and if it trusts the parent application before asking the parent to host the window. If the parent hosts a window it is displayed over the parent's content as well as the child's content. If no mutual trust exists between a main and sub-application, then the PopUpManager hosts the dialog box locally so that it can only be displayed over the content of the application itself. But if the parent trusts the child, the dialog box is not clipped by the boundaries of the child's application.

When a main application does not trust a sub-application, the main application's SWFLoader uses masking with a scrollRect and scroll bars to keep the sandboxed application's content restricted to its own application space.

Pop-up-related controls such as ColorPicker, ComboBox, DateField, PopUpButton, PopUpMenuButton, and Menu sometimes display their contents in unexpected ways if their normal position would cause them to be clipped.

Alerts, like other pop-up controls in sandboxed applications, are clipped at the edge of the loaded application. When an Alert is being displayed, the main application and all sub-applications are covered with a modal dialog box to prevent interaction with their controls. The blur effect only applies to the sub-application that launched the Alert box, and its child applications. The blur effect is not applied to the parent application or sibling applications.

The StyleManager does not pass styles from a parent application to a child in a different application domain or security domain. Similarly, a main application does not inherit styles from a sub-application. Therefore, either define styles within your sub-application and do not depend on the sub-application inheriting styles from the main application, or load a style module into the main application's application domain.

Sub-applications each have their own StyleManager. When you load a style module in a sub-application, the classes themselves should be loaded into the child ApplicationDomain. The styles are loaded into the sub-application's StyleManager.

If you want a main application and a sub-application to use the same runtime style sheets, load the style module into the main application's application domain. Sub-application's styles are merged with the main application's styles. Main applications do not inherit styles that are defined in style modules that are loaded into sub-applications.

A style module must be compiled with the same version of the Flex framework as the application into which it is loaded. The main application and sub-application might not be able to load the same style module, unless they are compiled with the same version of the framework.

When loading a style module into a sub-application, if you don't specify an application domain, the module is loaded into a sibling application domain of the sub-application. This can result in an error when the sub-application tries to use classes that are defined in the style module.

To load a style module into a sub-application, load the style module into a child application domain of the sub-application. The loadStyleDeclarations() method has two optional parameters, applicationDomain and securityDomain. You use these properties to control the application domain and the security domain into which style modules get loaded.

The following example loads a style module into a child application domain of the sub-application:

 private function loadStyle():void {  
 	/* Load style module into a child ApplicationDomain by specifying 
 	   ApplicationDomain.currentDomain. */ 
 	var eventDispatcher:IEventDispatcher = styleManager.loadStyleDeclarations( 
 		currentTheme + ".swf", true, false, ApplicationDomain.currentDomain);  
 	eventDispatcher.addEventListener(StyleEvent.COMPLETE, completeHandler);  
 }  

For more information on using style modules, see Loading style sheets at run time.

Applications that are in the same application domain are able to use the same embedded fonts by specifying the font name. However, if the sub-application is loaded into a different application domain (as is the case with sandboxed applications), then the sub-application must embed the font to use it.

The FocusManager class in the main application and sub-application integrate to create a seamless focus scheme. Users can "tab through" the sub-application, regardless of whether the application is in the same or a different security domain as the main application. Shift tabbing also works. The FocusManager class is one of the few manager classes that supports interoperability even across security domains.

When an application is loaded, the main application keeps track of that SWF file in a list of focus candidates. When the user moves focus into the sub-application, the sub-application's FocusManager takes over focus duties until the user moves focus outside the sub-application. At that time, the main application's FocusManager resumes control.

When a pop-up is dismissed, the focus is moved to the last place that had focus. This behavior can be another pop-up or it can be in the main application.

When focus is on a control that is in a different security sandbox, calls to the getFocus() method on that application's FocusManager return null. Calls to the UIComponent.getFocus() method also return null.

The FocusManager's moveFocus() method lets you programmatically transfer focus to a control under the jurisdiction of another FocusManager. It also lets you transfer the control of focus to another FocusManager.

Focus management across application domains works even with modal dialog boxes. When a different top-level window is activated, the SystemManager deactivates the FocusManager in the formerly active top-level window. The SystemManager also activates the FocusManager in the other window and changes the depth level (z-order) of the windows.

If the applications are in different security domains, then a custom cursor in the sub-application only appears over the area of the screen that is allocated to that sub-application. Moving the mouse outside the bounds of the sub-application passes control of the cursor to the main application's CursorManager.

These rules apply to the busy cursor as well. If a busy cursor is visible and you move the cursor to the main application that is in a different security domain, the cursor changes back to the last used cursor in the main application.

As with style modules, the main application cannot access resource modules used in a sub-application, and vice versa. Each sub-application must load its own resource modules.

Each multi-versioned application has its own ResourceManager instance. As a result, each sub-application has its own localeChain.

If more than one sub-application has resource bundles for the same locale with the same name, then the first one in wins. The contents of all resource bundles of that name in other sub-applications are ignored. Those sub-applications use the one that was defined first.

Like style modules, load resource modules into the child application domain of a sub-application. You control the application domain and the security domain into which resource bundles are loaded. The loadResourceModule() method of IResourceManager has two optional parameters, applicationDomain and securityDomain.

Also like style modules, all resource modules in an application must be compiled with the same version of the Flex framework. Do this whether that application is a main application or a sub-application. You cannot use multiple resource modules that were compiled with two different versions of the framework in the same main application or sub-application.

The following example loads a resource module into a child application domain of the sub-application:

 private function loadBundle():void {  
 	/* Load resource module into a child ApplicationDomain by specifying 
 	   ApplicationDomain.currentDomain. */ 
 	var eventDispatcher:IEventDispatcher = ResourceManager.loadResourceModule( 
 		"MyBundle.swf", true, false, ApplicationDomain.currentDomain);  
 	eventDispatcher.addEventListener(StyleEvent.COMPLETE, completeHandler);  
 } 

If you use run-time resource bundles with sub-applications, you should consider setting the addResourceBundle() method's useWeakReferences parameter to true. For more information, see Preventing memory leaks in modules and sub-applications.

When in a different security domain, ToolTip objects are parented by the sub-application's SystemManager and are therefore clipped and masked by the main application. The ToolTipManager styles and positions the tip in a sub-application so that it fits within the sub-application's area of the screen only. If the ToolTip object is larger than the area of the sub-application, the ToolTip object is clipped.

ToolTip styles in the main application are not inherited by ToolTip objects in the sub-application.

This applies to error tips and data tips on List objects in sandboxed sub-applications as well.

For controls that have pop-up or drop-down menus, when they are in a separate security domain, they are initially displayed unclipped. These controls are restricted to the sub-application's space, so if they try to go outside that bounding area, they are clipped.

The BrowserManager controls deep linking support in applications built with Flex. It is a singleton within its security domain. Sub-applications in sibling application domains cannot access the main application's BrowserManager, regardless of whether a sub-application is trusted or untrusted. As a result, a sub-application in a separate security domain or application domain cannot modify the URL nor can it access the URL.

If the sub-application is untrusted, do not give it access to the URL. If the sub-application is trusted (such as with a multi-versioned application that is not sandboxed), you can write custom code that handles the interaction between the sub-application and the main application's BrowserManager. Typically, you call this method in the main application that accesses the URL, or create an interface that acts as a gatekeeper for this interaction.

If you try to get an instance of the BrowserManager from within a sub-application, Flash Player throws an error.

When the sub-application is in a different security domain from the main application, the user cannot drag data between the applications. The DragProxy lets the user drag an item to the edge of the sub-application's area of the screen. At that point, the mouse cursor changes back to whatever mouse cursor is correct for the new security domain.

The proxy for the item stays at the boundary of the sub-application, and might be clipped.

Mouse interaction between sub-applications and main applications can be confusing, especially when those events occur in different application domains. This interaction is further muddied when the applications are in different security domains. To listen for mouse events outside the security domain, you use the SandboxMouseEvent object. You can listen for this event in a main application for a mouse event that is triggered from the sub-application, and vice versa.

The following application is like the application in the topic, Listening for mouse events in multi-versioned applications, with some exceptions. For example, while the MouseEvent.MOUSE_MOVE and MouseEvent.MOUSE_UP events are registered, the SandboxMouseEvent.MOUSE_UP_SOMEWHERE event is also registered. This event can be registered by any SystemManager within the security domain. All applications can then receive notification if this event is triggered. To get the mouse position, this application uses the globalToLocal() method. You can see how to determine the absolute position of an object in a sub-application when you don't have access to the stage.

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/ZoomerPattern4.mxml --> 
<s:Application 
    creationComplete="setup()" 
    height="250" 
    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.events.SandboxMouseEvent; 
          import mx.managers.PopUpManager; 
 
          [Bindable] 
          public var data1:Array = ["Ice Cream", "Fudge", "Whipped Cream", "Nuts"]; 
 
          public var zoomTool:UIComponent; 
 
          public function setup():void { 
               // Draw the zoom rectangle. 
               zoomWidget.graphics.lineStyle(1); 
               zoomWidget.graphics.beginFill(0, 0); 
               zoomWidget.graphics.drawRect(0, 0, 17, 17); 
               zoomWidget.graphics.endFill(); 
               
               // Listen for mouse down events. 
               zoomWidget.addEventListener(MouseEvent.MOUSE_DOWN, zoom_mouseDownHandler); 
          } 
 
          private var lastX:int; 
          private var lastY:int; 
 
          private function zoom_mouseDownHandler(event:MouseEvent):void { 
               // When the mouse is down, listen for the move and up events.              
               // The getSandboxRoot() method lets you listen to all mouse activity in your 
               // SecurityDomain. 
               
               systemManager.getSandboxRoot().addEventListener( 
                    MouseEvent.MOUSE_MOVE, zoom_mouseMoveHandler, true); 
               systemManager.getSandboxRoot().addEventListener( 
                    MouseEvent.MOUSE_UP, zoom_mouseUpHandler, true); 
 
               // The SandboxMouseEvents provide you with some mouse information, 
               // but not its position 
               systemManager.getSandboxRoot().addEventListener( 
                    SandboxMouseEvent.MOUSE_UP_SOMEWHERE, zoom_mouseUpHandler); 
 
               
               // Update last position of the mouse. 
               lastX = event.stageX; 
               lastY = event.stageY; 
 
               // Create and pop up the zoomTool. This is the rectangle that is dragged around. 
               // It must be a popup so that it can float over other content. 
               zoomTool = new UIComponent(); 
               PopUpManager.addPopUp(zoomTool, this); 
               
               var pt:Point = new Point(zoomWidget.transform.pixelBounds.x, 
                    zoomWidget.transform.pixelBounds.y); 
               pt = zoomTool.parent.globalToLocal(pt); 
               zoomTool.x = pt.x; 
               zoomTool.y = pt.y; 
               zoomTool.graphics.lineStyle(1); 
               zoomTool.graphics.beginFill(0, 0); 
               zoomTool.graphics.drawRect(0, 0, 17, 17); 
               zoomTool.graphics.endFill(); 
 
               // Hide the rectangle that was the target. 
               zoomWidget.visible = false; 
          } 
 
          private function zoom_mouseMoveHandler(event:MouseEvent):void { 
               // Update the position of the dragged rectangle. 
               zoomTool.x += event.stageX - lastX; 
               zoomTool.y += event.stageY - lastY; 
               lastX = event.stageX; 
               lastY = event.stageY; 
 
               var bm:BitmapData = new BitmapData(16, 16); 
               
               // Capture the bits on the screen.  
               // Use the globalToLocal() method to get the coordinates of the rectangle. 
               // Untrusted sub-applications do not have access to the stage so you have 
               // to call the globalToLocal() method on a point. 
               var pt:Point = new Point(zoomTool.transform.pixelBounds.x + 2, 
                    zoomTool.transform.pixelBounds.y + 2); 
               pt = DisplayObject(systemManager.getSandboxRoot()).globalToLocal(pt); 
               bm.draw(DisplayObject(systemManager.getSandboxRoot()), 
                    new Matrix(1, 0, 0, 1, -pt.x, -pt.y)); 
 
               // Create a Bitmap to hold the bits. 
               if (zoomed.numChildren == 0) { 
                    var bmp:Bitmap = new Bitmap(); 
                    zoomed.addChild(bmp); 
               } else 
                    bmp = zoomed.getChildAt(0) as Bitmap; 
 
               // Set the bits. 
               bmp.bitmapData = bm; 
 
               // Zoom in on the bits. 
               bmp.scaleX = bmp.scaleY = 8; 
          } 
 
          private function zoom_mouseUpHandler(event:Event):void { 
               // Remove the listeners. 
               systemManager.getSandboxRoot().removeEventListener( 
                    MouseEvent.MOUSE_MOVE, zoom_mouseMoveHandler, true); 
               systemManager.getSandboxRoot().removeEventListener( 
                    MouseEvent.MOUSE_UP, zoom_mouseUpHandler, true);            
               systemManager.getSandboxRoot().removeEventListener( 
                    SandboxMouseEvent.MOUSE_UP_SOMEWHERE, zoom_mouseUpHandler, true); 
 
               // Replace the target rectangle.             
               zoomWidget.visible = true; 
               
               // Remove the dragged rectangle. 
               PopUpManager.removePopUp(zoomTool); 
          } 
 
     ]]> 
     </fx:Script> 
  
    <mx:HBox> 
          <mx:HBox backgroundColor="0x00eeee" height="140" paddingTop="4" paddingRight="4"> 
               <mx:Label text="Drag Rectangle"/> 
               <mx:UIComponent id="zoomWidget" width="17" height="17"/> 
               <mx:Canvas id="zoom" 
                    borderStyle="solid" 
                    width="132" 
                    height="132" 
               > 
                    <mx:UIComponent id="zoomed" width="128" height="128"/> 
               </mx:Canvas> 
          </mx:HBox> 
          <mx:List dataProvider="{data1}"/> 
     </mx:HBox> 
</s:Application>

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/MainZoomerPattern4.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[ 
               /* The PopUpManager must be linked in to all applications that are 
                  at the same security sandbox root. Because the sub-application 
                  in this example uses the PopUpManager, the main application must also 
                  link it it. */ 
               import mx.managers.PopUpManager; PopUpManager; 
          ]]> 
     </fx:Script> 
 
     <mx:Text text="Portal (untrusted versioning application):"/> 
     
     <mx:SWFLoader id="swf1" 
          loadForCompatibility="true" 
          trustContent="false" 
          source="ZoomerPattern4.swf"/> 
          
</s:Application>

You can access application parameters that were passed into the sub-application as flashVars variables. To do this, you access the Array of parameters on the application object by using the getSandboxRoot() method.

The following example gets a reference to the root application and accesses the parameters:

var app:DisplayObject = DisplayObject( 
	SystemManager.getSandboxRoot()["application"]); 
var parameters:Object = app["parameters"];

When you use RPC classes (such as WebService and HTTPService) without a proxy server, you do not need to load the sub-application as a sandboxed application or externalize the classes in a bootstrap class loader. Applications that use these classes without a proxy server should work as well as any multi-versioned application. Be sure to that either the URLs for the target services are on the same server as the main application, or that the target server has a crossdomain.xml file on it that allows access.

When a sub-application launches a pop-up control, it floats over the entire application, and can be dragged anywhere on the stage. Pop-up controls are created in the sub-application's application domain and passed to the main application's PopUpManager. Pop-up controls cannot be strongly-typed as IUIComponent, so they are marshaled from the sub-application to the main application for display.

Pop-up windows behave as follows in a multi-versioned sub-application (these behaviors are the same for single-versioned sub-applications):

• Launching a modal dialog box dims the entire application, not just the sub-application that launched it

• Centering a pop-up centers it over the entire application, not just the sub-application

• Dragging pop-up controls works over the entire application, not just the sub-application

• Focus shifts to the pop-up when you first launch a pop-up from the sub-application

The PopUpManager must be linked in to all applications that are sandbox roots. When using the PopUpManager in a child application, there must also be an instance of the PopUpManager in the main application. To link the PopUpManager to a main application that doesn't use it, you can add the following code:

import mx.managers.PopUpManager;   
private var popupManager1:PopUpManager;

No class registered for interface 'mx.managers::IPopUpManager'.

<mx:List visible="false" includeInLayout="false" dataProvider="[]"/>

Applications that are in the same application domain are able to use the same embedded fonts by specifying the font name. However, if the sub-application is loaded into a different application domain (as is the case with multi-versioned applications), then the sub-application must embed the font to use it.

Using styles and style modules in multi-versioned sub-applications is the same as using them in sandboxed sub-applications. For more information on using styles and style modules in sub-applications, see Styles and style modules in sandboxed applications.

Using the FocusManager in multi-versioned sub-applications is the same as using the FocusManager in sandboxed sub-applications. (See Focus in sandboxed applications.)

The CursorManager class in the main application and sub-application communicate much like the PopupManager class. If the sub-application changes the cursor to a custom cursor, this custom cursor continues to appear when the cursor is moved outside the sub-application and over the main application. Calling a method or setting a property on the CursorManager in the sub-application bubbles up to the main application, and vice versa.

If a busy cursor is visible while the mouse is over the sub-application, and you move the cursor to the main application, the cursor remains as a busy cursor.

Using resource bundles in multi-versioned sub-applications is the same as using them in sandboxed sub-applications. For more information on using resource bundles in sub-applications, see Localizing sandboxed applications.

ToolTip objects are created in the sub-application's application domain and are passed to the main application's ToolTipManager. This is an example of marshaling a class across application boundaries.

This behavior applies to error tips and data tips on List objects in multi-versioned applications as well.

The main application dictates the area of the screen that is available to the sub-application for screen layout.

LayoutManagers in different applications run independent of one another. The applications are not clipped.

You cannot access the main application's BrowserManager directly from a sub-application that is in a different application domain. The sub-application's BrowserManager is disabled. This is the same for sandboxed and multi-versioned sub-applications. For more information, see Deep linking in sandboxed applications.

When the sub-application is in the same security domain as the main application, but in a different application domain, you can drag list items from a sub-application to a list in the main application, and vice versa. For this to work across applications, the class that defines the drop target must be public.

The DragProxy maintains the item's appearance during the entire event, regardless of which application the mouse is over. Drag events are triggered for all source and destination controls, as if they are in the same application.

In the background, the DragManager generates the DragProxy in the sub-application's application domain then passes that DragProxy to the main application's DragManager during the drag operation.

Strongly-typed objects cannot be passed from the main application to the sub-application or vice versa. As a result, the DragManager accepts a DragProxy that is not strongly typed.

All properties and methods defined by the IDragManager interface are handled through delegation to the main application's DragManager.

If you drag a generic type object, the object will be of generic type Object in Flash Player's application domain. Flex marshals the properties so that the drag and drop operation works without having to write any custom code.

If you use a custom class as part of the drop data, that class cannot be shared as strongly-typed. In that case, override the drop events and add logic to marshall the data from the drag source to the drop target.

Mouse interaction between a main application and a sub-application can be confusing, especially when those events occur in different application domains. For example, when you click and drag an object in a sub-application, and then release the button over the main application, typical Flex mouse events such as MOUSE_UP, MOUSE_DOWN_OUTSIDE, or MOUSE_LEAVE are triggered but cannot be listened to directly in the sub-application.

To listen for mouse events across application domains, listen to all mouse activity in the security domain. To listen, get a reference to the sandbox root and register your event listeners with that SystemManager.

When loaded into a separate application domain, the topLevelSystemManager property refers to the sub-application's SystemManager because the main application's SystemManager is in another application domain. As a result, you do not use the topLevelSystemManager property to get a reference to the main application's SystemManager. Instead, you use the systemManager.getSandboxRoot() method to get a reference to the top-level SystemManager in the security domain. From this SystemManager, you can access all mouse activity in the current security domain.

The following example uses calls to the getSandboxRoot() method to get references to the top-level SystemManager in the security domain.

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/ZoomerPattern3.mxml --> 
<s:Application 
    creationComplete="setup()" 
    height="250" 
    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.managers.PopUpManager; 
 
          [Bindable] 
          public var data1:Array = ["Ice Cream", "Fudge", "Whipped Cream", "Nuts"]; 
 
          public var zoomTool:UIComponent; 
 
          public function setup():void { 
               // Draw the zoom rectangle. 
               zoomWidget.graphics.lineStyle(1); 
               zoomWidget.graphics.beginFill(0, 0); 
               zoomWidget.graphics.drawRect(0, 0, 17, 17); 
               zoomWidget.graphics.endFill(); 
               
               // Listen for mouse down events. 
               zoomWidget.addEventListener(MouseEvent.MOUSE_DOWN, zoom_mouseDownHandler); 
          } 
 
          private var lastX:int; 
          private var lastY:int; 
 
          private function zoom_mouseDownHandler(event:MouseEvent):void { 
               // When the mouse is down, listen for the move and up events.              
               // The getSandboxRoot() method lets you listen to all mouse activity in your 
               // SecurityDomain. 
               systemManager.getSandboxRoot().addEventListener( 
                    MouseEvent.MOUSE_MOVE, zoom_mouseMoveHandler, true); 
               systemManager.getSandboxRoot().addEventListener( 
                    MouseEvent.MOUSE_UP, zoom_mouseUpHandler, true); 
 
               // Update last position of the mouse. 
               lastX = event.stageX; 
               lastY = event.stageY; 
 
               // Create and pop up the zoomTool. This is the rectangle that is dragged around. 
               // It must be a popup so that it can float over other content. 
               zoomTool = new UIComponent(); 
               PopUpManager.addPopUp(zoomTool, this); 
               
               var pt:Point = new Point(zoomWidget.transform.pixelBounds.x, 
                    zoomWidget.transform.pixelBounds.y); 
               pt = zoomTool.parent.globalToLocal(pt); 
               zoomTool.x = pt.x; 
               zoomTool.y = pt.y; 
               zoomTool.graphics.lineStyle(1); 
               zoomTool.graphics.beginFill(0, 0); 
               zoomTool.graphics.drawRect(0, 0, 17, 17); 
               zoomTool.graphics.endFill(); 
 
               // Hide the rectangle that was the target. 
               zoomWidget.visible = false; 
          } 
 
          private function zoom_mouseMoveHandler(event:MouseEvent):void { 
               // Update the position of the dragged rectangle. 
               zoomTool.x += event.stageX - lastX; 
               zoomTool.y += event.stageY - lastY; 
               lastX = event.stageX; 
               lastY = event.stageY; 
 
               var bm:BitmapData = new BitmapData(16, 16); 
 
               // Capture the bits on the screen.  
               // You must use the getSandboxRoot() method here, too, because it gets 
               // the parent of all of the pixels you are allowed to access. 
               bm.draw(DisplayObject(systemManager.getSandboxRoot()), 
                    new Matrix(1, 0, 0, 1, -zoomTool.transform.pixelBounds.x - 2, 
                    -zoomTool.transform.pixelBounds.y - 2)); 
 
               // Create a Bitmap to hold the bits. 
               if (zoomed.numChildren == 0) { 
                    var bmp:Bitmap = new Bitmap(); 
                    zoomed.addChild(bmp); 
               } else 
                    bmp = zoomed.getChildAt(0) as Bitmap; 
 
               // Set the bits. 
               bmp.bitmapData = bm; 
 
               // Zoom in on the bits. 
               bmp.scaleX = bmp.scaleY = 8; 
          } 
 
          private function zoom_mouseUpHandler(event:Event):void { 
               // Remove the listeners. 
               systemManager.getSandboxRoot().removeEventListener( 
                    MouseEvent.MOUSE_MOVE, zoom_mouseMoveHandler, true); 
               systemManager.getSandboxRoot().removeEventListener( 
                    MouseEvent.MOUSE_UP, zoom_mouseUpHandler, true); 
 
               // Replace the target rectangle. 
               zoomWidget.visible = true; 
 
               // Remove the dragged rectangle. 
               PopUpManager.removePopUp(zoomTool); 
          } 
 
     ]]> 
     </fx:Script> 
     
     <mx:HBox> 
          <mx:HBox backgroundColor="0x00eeee" height="140" paddingTop="4" paddingRight="4"> 
               <mx:Label text="Drag Rectangle"/> 
               <mx:UIComponent id="zoomWidget" width="17" height="17"/> 
               <mx:Canvas id="zoom" 
                    borderStyle="solid" 
                    width="132" 
                    height="132" 
               > 
                    <mx:UIComponent id="zoomed" width="128" height="128"/> 
               </mx:Canvas> 
          </mx:HBox> 
          <mx:List dataProvider="{data1}"/> 
     </mx:HBox> 
</s:Application>

<?xml version="1.0" encoding="utf-8"?> 
<!-- apploading/MainZoomerPattern3.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> 
 
    <mx:Text text="Cross-Versioning (trusted versioning application):"/> 
 
    <mx:SWFLoader id="swf1" loadForCompatibility="true" source="ZoomerPattern3.swf"/> 
     
</s:Application>