Flex compiles your application into a SWF file that contains a single Application object, defined by the <mx:Application> tag. In most cases, your Flex application has one Application object. Some applications use the SWFLoader control to add more applications.

An Application object has the following characteristics:

• Application objects are MXML files with an <mx:Application> tag.
• Most Flex applications have a single Application object.
• The Application file is the first file loaded.
• An Application object is also a Document object, but a Document object is not always an Application object. For more information on the Document object, see About the Document object.
• You can refer to the Application object as mx.core.Application.application from anywhere in the Flex application.
• If you load multiple nested applications by using the SWFLoader control, you can access the scope of each higher application in the nesting hierarchy by using parentApplication, parentApplication.parentApplication, and so on.

About the Document object

Flex creates a Document object for every MXML file used in a Flex application. For example, you can have a document, which is also an Application object, and from there, use other MXML files that define custom controls.

A Document object has the following characteristics:

• All MXML files that a Flex application uses are Document objects, including the Application object's file.
• Custom ActionScript component files are Document objects.
• The Flex compiler cannot compile a SWF file from a file that does not contain an <mx:Application> tag.
• Documents usually consist of MXML custom controls that you use in your Flex application.
• You can access the scope of a document's parent document by using parentDocument, parentDocument.parentDocument, and so on.
• Flex provides a UIComponent.isDocument property so that you can detect if any given object is a Document object.

Accessing Document and Application object scopes

In your application's main MXML file, the file that contains the <mx:Application> tag, you can access the methods and properties of the Application object by using the this keyword. However, in custom ActionScript and MXML components, event listeners, or external ActionScript class files, Flex executes in the context of those components and classes, and the this keyword refers to the current Document object and not the Application object. You cannot refer to a control or method in the application from one of these child documents without specifying the location of the parent document.

Flex provides the following properties that you can use to access parent documents:

mx.core.Application.application The top-level Application object, regardless of where in the document tree your object executes.

mx.core.UIComponent.parentDocument The parent document of the current document. You can use parentDocument.parentDocument to walk up the tree of multiple documents.

mx.core.UIComponent.parentApplication The Application object in which the current object exists. Flex applications can load applications into applications, therefore, you can access the immediate parent application by using this property. You can use parentApplication.parentApplication to walk up the tree of multiple applications.

Using the mx.core.Application.application property

To access properties and methods of the top-level Application object from anywhere in your application, you can use the application property of the Application class. For example, you define an application that contains the method, as the following code shows:

<?xml version="1.0"?>
<!-- containers\application\AppDoSomething.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:MyComps="myComponents.*"
>
    <mx:Script>
        <![CDATA[
            import mx.controls.Alert;
        
            // Open an Alert control.
            public function doSomething():void {
                Alert.show("The doSomething() method was called.");
            }
        ]]>
    </mx:Script>
    
    <!-- Include the ButtonMXML.mxml component. -->
    <MyComps:ButtonMXML/>
</mx:Application>
The executing SWF file for the previous example is shown below:

You can then use the Application.application property in the ButtonMXML.mxml component to reference the doSomething() method, as the following example shows:

<?xml version="1.0"?>
<!-- containers\application\myComponents\ButtonMXML.mxml -->
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml">
    
    <mx:Script>
        <![CDATA[
            // To refer to the members of the Application class, 
            // you must import mx.core.Application.
            import mx.core.Application;            
        ]]>
    </mx:Script>

    <mx:Button  label="MXML Button"
        click="Application.application.doSomething();"/>
</mx:HBox>

The application property is especially useful in applications that have one or more custom MXML or ActionScript components that each use a shared set of data. At the application level, you often store shared information and provide utility functions that any of the components can access.

For example, suppose that you store the user's name at the application level and implement a utility function, getSalutation(), which returns the string "Hi, userName". The following example MyApplication.mxml file shows the application source that defines the getSalutation() method:

<?xml version="1.0"?>
<!-- containers\application\AppSalutation.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:MyComps="myComponents.*"
>
    <mx:Script>
        <![CDATA[
            public var userName:String="SMG";
            
            public function getSalutation():String {
                return "Hi, " + userName;
            }
        ]]>
    </mx:Script>

    <!-- Include the ButtonGetSalutation.mxml component. -->
    <MyComps:ButtonGetSalutation/>    
    
</mx:Application>
The executing SWF file for the previous example is shown below:

To access the userName and call the getSalutation() method in your MXML components, you can use the application property, as the following example from the MyComponent.mxml component shows:

<?xml version="1.0"?>
<!-- containers\application\myComponents\ButtonGetSalutation.mxml -->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" width="100%" height="100%">

    <mx:Script>
        <![CDATA[
            /* To refer to the members of the Application class, 
               you must import mx.core.Application. */
            import mx.core.Application;            
        ]]>
    </mx:Script>

    <mx:Label id="myL"/>
    <mx:Button label="Click Me" click="myL.text=Application.application.getSalutation();"/>
</mx:VBox>

In this example, clicking the Button control executes the getSalutation() function to populate the Label control.

Using the parentDocument property

To access the parent document of an object, you can use the parentDocument property. The parent document is the object that contains the current object. All classes that inherit from the UIComponent class have a parentDocument property.

In the following example, the application references the custom AccChildObject.mxml component:

<?xml version="1.0"?>
<!-- containers\application\AppParentDocument.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:MyComps="myComponents.*">

    <!-- Include the AccChildObject.mxml component. -->
    <MyComps:AccChildObject/>

</mx:Application>
The executing SWF file for the previous example is shown below:

In this example, the application is the parent document of the AccChildObject.mxml component. The following code from the AccChildObject.mxml component uses the parentDocument property to define an Accordion container that is slightly smaller than the Application container:

<?xml version="1.0"?>
<!-- containers\application\myComponents\AccChildObject.mxml -->
<mx:Accordion xmlns:mx="http://www.adobe.com/2006/mxml" 
    width="{parentDocument.width*.80}" 
    height="{parentDocument.height*.50}">
    
    <mx:HBox/>
    
</mx:Accordion> 

You use the parentDocument property in MXML scripts to go up a level in the chain of parent documents. You can use the parentDocument to walk this chain by using multiple parentDocument properties, as the following example shows:

parentDocument.parentDocument.doSomething();

The parentDocument property of the Application object is a reference to the application.

The parentDocument is typed as Object so that you can access properties and methods on ancestor Document objects without casting.

Every UIComponent class has an isDocument property that is set to true if that UIComponent class is a Document object, and false if it is not.

If a UIComponent class is a Document object, it has a documentDescriptor property. This is a reference to the descriptor at the top of the generated descriptor tree in the generated Document class.

For example, suppose that AddressForm.mxml component creates a subclass of the Form container to define an address form, and the MyApp.mxml component creates two instances of it: <AddressForm id="shipping"> and <AddressForm id="billing">.

In this example, the shipping object is a Document object. Its documentDescriptor property corresponds to the <mx:Form> tag at the top of the AddressForm.mxml file (the definition of the component), while its descriptor corresponds to the <AddressForm id="shipping"> tag in MyApp.mxml file (an instance of the component).

Walking the document chain by using the parentDocument property is similar to walking the application chain by using the parentApplication property.

Using the parentApplication property

Applications can load other applications; therefore, you can have a hierarchy of applications, similar to the hierarchy of documents within each application. Every UIComponent class has a parentApplication read-only property that references the Application object in which the object exists. The parentApplication property of an Application object is never itself; it is either the Application object into which it was loaded, or it is null (for the Application object).

Walking the application chain by using the parentApplication property is similar to walking the document chain by using the parentDocument property.