About the application object

Flex compiles your application into a SWF file that contains a single application object, of type spark.components.Application or mx.core.Application. In most cases, your application has one application object. Some applications use the SWFLoader control to add more applications.

An application object has the following characteristics:

  • The file defining the application object is the first file loaded by the application.

  • You can refer to the application object as mx.core.FlexGlobals.topLevelApplication from anywhere in the 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 documents

Every MXML file used in an application is referred to as a document class. For example, you define an MXML file named MyForm.mxml that contains the following code:
<?xml version="1.0"?> 
<mx:Form xmlns:mx="library://ns.adobe.com/flex/mx"> 
    … 
</mx:Form>

MyForm.mxml is the document class and instances of MyForm.mxml are referred to as documents. An MXML file that includes the <s:Application> or <mx:Application> tag is the document class that defines the application object. MXML files that omit the <s:Application> or <mx:Application> tag are custom controls.

A document has the following characteristics:

  • All MXML files that an application uses are document classes, including the MXML file that includes the <s:Application> or <mx:Application> tag.

  • Custom ActionScript component files are document classes.

  • The Flex compiler cannot compile a SWF file from a file that does not contain the <s:Application> or <mx:Application> tag.

  • 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.

Accessing document and application scopes

In your application’s main MXML file, the file that contains the <s:Application> or <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 and not to 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.FlexGlobals.topLevelApplication
The top-level application object, regardless of where in the document tree your object executes. This object is of type spark.components.Application or mx.core.Application.

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. Applications can load other 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.FlexGlobals.topLevelApplication property

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

<?xml version="1.0"?>
<!-- containers\application\AppDoSomething.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:MyComps="myComponents.*">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout> 
    
    <fx:Script>
        <![CDATA[
            import mx.controls.Alert;
        
            // Open an Alert control.
            public function doSomething():void {
                Alert.show("The doSomething() method was called.");
            }
        ]]>
    </fx:Script>
    
    <!-- Include the ButtonMXML.mxml component. -->
    <MyComps:ButtonMXML/>
</s:Application>

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

You can then use the FlexGlobals.topLevelApplication 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 -->
<s:SkinnableContainer xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">
    <s:layout>
        <s:HorizontalLayout/>
    </s:layout>
    
    <fx:Script>
        <![CDATA[
            // To refer to the members of the Application class, 
            // you must import mx.core.Application.
            import mx.core.FlexGlobals;
        ]]>
    </fx:Script>

    <s:Button  label="MXML Button"
        click="FlexGlobals.topLevelApplication.doSomething();"/>
</s:SkinnableContainer>

The topLevelApplication 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 -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:MyComps="myComponents.*">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    
    <fx:Script>
        <![CDATA[
            public var userName:String="SMG";
            
            public function getSalutation():String {
                return "Hi, " + userName;
            }
        ]]>
    </fx:Script>

    <!-- Include the ButtonGetSalutation.mxml component. -->
    <MyComps:ButtonGetSalutation/>    
    
</s: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 topLevelApplication property, as the following example from the MyComponent.mxml component shows:

<?xml version="1.0"?>
<!-- containers\application\myComponents\ButtonGetSalutation.mxml -->
<s:SkinnableContainer xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    width="100%" height="100%">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

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

    <mx:Label id="myL"/>
    <s:Button label="Click Me" 
        click="myL.text=FlexGlobals.topLevelApplication.getSalutation();"/>
</s:SkinnableContainer>

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 -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:MyComps="myComponents.*"
    width="100%" height="100%">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

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

</s: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:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    width="{parentDocument.width*.80}" 
    height="{parentDocument.height*.50}">
    
    <mx:HBox label="Child 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.