About the Application container

Sizing an application container and its children
Using scroll bars with the application container
Overriding the default Application container styles
Adding a control bar area to the application container
Application events
Viewing the application source code
Specifying options of the Application container

The first tag in an MXML application is either the <s:Application> tag for the Spark application container, or the <mx:Application> tag for an MX application container. The application container then becomes the default container for any content that you add to your application.

The application object, of type spark.components.Application or mx.core.Application, is the default scope for any ActionScript code in the file. Therefore, the ActionScript keyword this refers to the application object.

You also use the application container to define the initial size of the application. By default, the application sets its height to 375 pixels and its width to 500 pixels.

Although you might find it convenient to use an application container as the only container in your application, usually you explicitly define at least one more container before you add any controls to your application. For example, you might use a Panel container as the first child container of the application.

The application containers have the following default layout characteristics:

Characteristic	Spark Application container	MX Application container
Default size	375 pixels high and 500 pixels wide in the Standalone Flash Player, and all available space in a browser.	375 pixels high and 500 pixels wide in the Standalone Flash Player, and all available space in a browser.
Child layout	BasicLayout, meaning that you have to explicitly size and position all children.	Vertical column arrangement of children centered in the Application container.
Default padding	0 pixels.	24 pixels for the `paddingTop`, `paddingBottom`, `paddingLeft`, and `paddingRight` properties.
Scroll bars	Added by skinning the container.	Built into the container.

Sizing an application container and its children

You can set the height and width of an application container by using explicit pixel values or by using percentage values, where the percentage values are relative to the size of the browser window. By default, the application container sets its height to 375 pixels and its width to 500 pixels in the Standalone Flash Player, and sizes itself to use all available space in a browser.

The following example sets the size of the Application container to one-half of the width and height of the browser window:

<?xml version="1.0"?> 
<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" 
    height="50%" width="50%"> 
    ... 
</Application>

The advantage of using percentages to specify the size is that Flex can resize your application as the user resizes the browser window. Flex maintains the application container size as a percentage of the browser window as the user resizes it.

If you set the width and height properties of the child components to percentage values, your components can also resize as your application resizes, as the following example shows:

<?xml version="1.0"?>
<!-- containers\application\AppSizePercent.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"
    width="100%" height="100%">    
    <s:layout>
        <s:VerticalLayout/>
    </s:layout> 

    <s:Panel title="Main Application" width="100%" height="100%">
        <mx:HDividedBox width="100%" height="100%">
            <s:TextArea text="TA1" width="50%" height="100%"/>
            <mx:VDividedBox width="50%" height="100%">
                <s:TextArea text="TA2" width="100%" height="75%"/>
                <s:TextArea text="TA3" width="100%" height="75%"/>
            </mx:VDividedBox>
        </mx:HDividedBox>
    </s:Panel>
</s:Application>The executing SWF file for the previous example is shown below:

The following example uses explicit pixel values to size the application container:

<?xml version="1.0"?>
<!-- containers\application\AppSizePixel.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"
    width="200" height="150">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <mx:Panel title="Main Application">
        <mx:TextInput id="mytext" text="Hello"/>
        <mx:Button id="mybutton" label="Get Weather"/>
    </mx:Panel>
</s:Application>The executing SWF file for the previous example is shown below:

If you want to set a child container to fill the entire application container, the easiest method is to set the child’s width and height properties to 100% in MXML. In ActionScript, set the percentWidth and percentHeight properties to 100.

Because the Spark Application container defines 0 pixels of padding around its content area, a child sized to 100% fills the entire area of the container. In the following example, the child VBox container fills the entire application container:

<?xml version="1.0"?>
<!-- containers\application\AppNoPadding.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"
    width="100%" height="100%">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout> 
    
    <mx:VBox width="100%" height="100%" backgroundColor="#A9C0E7">
        <!-- ... -->
    </mx:VBox>
</s:Application>The executing SWF file for the previous example is shown below:

The MX Application container defines 24 pixels of padding around all four sides of its content area. Therefore, if you want a child to occupy the entire area of the Application container, set the container’s padding properties (paddingTop, paddingBottom, paddingLeft, paddingRight) to 0.

Using scroll bars with the application container

The MX Application container has built in support for scroll bars. Therefore, if the children of the MX Application container are sized or positioned such that some or all the component is outside the visible area of the MX Application container, Flex adds scroll bars to the container.

In the following example, the VBox container in the MX Application container is larger than the available space within the Application container, which results in scroll bars:

<?xml version="1.0"?>
<!-- containers\application\AppVBoxSizeScroll.mxml -->
<mx: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" 
    width="100" height="100">

    <mx:VBox width="200" height="200" backgroundColor="#A9C0E7">
        <!-- ... --> 
    </mx:VBox>
</mx:Application>The executing SWF file for the previous example is shown below:

To add scroll bars to the Spark Application container, define a skin that supports scroll bars. The following example shows a skin in the file MyAppSkin.mxml. This skin modifies the default skin for the Spark Application container, spark.skins.default.ApplicationSkin, to add the Spark Scroller component:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\application\mySkins\MyAppSkin.mxml -->
<s:Skin xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

    <fx:Metadata>
        [HostComponent("spark.components.Application")]
    </fx:Metadata> 
    
    <s:states>
        <s:State name="normal" />
        <s:State name="disabled" />
    </s:states>
    
    <!-- fill -->
    <s:Rect id="backgroundRect" left="0" right="0" top="0" bottom="0">
        <s:fill>
            <s:SolidColor color="0xFFFFFF" />
        </s:fill>
    </s:Rect>
        
    <s:Scroller height="100%" width="100%">
        <s:Group id="contentGroup" left="0" right="0" top="0" bottom="0" />        
    </s:Scroller>
</s:Skin>

The following application uses this skin:

<?xml version="1.0"?>
<!-- containers\application\AppSparkScroll.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" 
    width="150" height="150"
    skinClass="mySkins.MyAppSkin">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <mx:VBox width="200" height="200" backgroundColor="#A9C0E7">
        <!-- ... --> 
    </mx:VBox>  
    
    <mx:VBox width="200" height="200" backgroundColor="#000000">
        <!-- ... --> 
    </mx:VBox> 
</s:Application>The executing SWF file for the previous example is shown below:

For more information, see Adding scroll bars to Spark containers.

Overriding the default Application container styles

By default, the application containers have the following properties and style properties that define the visual aspects of the application and differ from the default container values:

Property	Spark Application default value	MX Application default value
backgroundColor	The color of the Stage area of Adobe® Flash® Player or Adobe® AIR™, which is visible during application loading and initialization. This color is also visible if the application skin does not define any other background color or image. The default value is `0xFFFFFF` (white).	The color of the Stage area of Adobe® Flash® Player or Adobe® AIR™, which is visible during application loading and initialization. This color is also visible if the application background is transparent. The default value is `0xFFFFFF` (white).
backgroundGradientAlphas	Not implemented; define in the container skin.	`[1.0, 1.0]`, a fully opaque background.
backgroundGradientColors	Not implemented; define in the container skin.	undefined, which means background gradient is generated based on the `backgroundColor` property. By default, the `backgroundColor` property defines a white background.
backgroundImage	Not implemented; define in the container skin.	A gradient controlled by the `backgroundGradientAlphas` and `backgroundGradientColors` styles. The default value is `mx.skins.halo.ApplicationBackground`.
backgroundSize	Not implemented; define in the container skin.	100%. When you set this property at 100%, the background image takes up the entire Application container.
horizontalAlign	Not implemented; set in the layout class associated with the Application container.	Centered.
paddingBottom	0 pixels.	24 pixels.
paddingLeft	0 pixels.	24 pixels.
paddingRight	0 pixels.	24 pixels.
paddingTop	0 pixels.	24 pixels.

Changing the Spark Application container background

The Spark Application.backgroundColor style defines the default background color of the Application container during application loading and initialization. If the Application skin does not set a different color, the backgroundColor style also defines the background color of the application when it is running. The default value is 0xFFFFFF (white).

To set the background color of the Spark Application container to something other than a solid color, or to set a background image, you define a skin for the container. For example, the following skin defines a gradient fill for the background of the Application container that goes from blue to gray:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\application\mySkins\MyAppBackgroundSkin.mxml -->
<s:Skin xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

    <fx:Metadata>
        [HostComponent("spark.components.Application")]
    </fx:Metadata> 
    
    <s:states>
        <s:State name="normal" />
        <s:State name="disabled" />
    </s:states>

    <!-- Define a gradient fill for the background of the Application container. -->    
    <s:Rect id="backgroundRect" left="0" right="0" top="0" bottom="0">
        <s:fill>
            <s:LinearGradient>
                <s:entries>
                    <s:GradientEntry color="0x0000FF" ratio="0.00" alpha="0.5"/>
                    <s:GradientEntry color="0xCCCCCC" ratio="0.5" alpha="0.5"/>
                </s:entries>
            </s:LinearGradient>
        </s:fill>
    </s:Rect>
                
    <s:Group id="contentGroup" left="0" right="0" top="0" bottom="0" />
</s:Skin>

You then use the skinClass style property to apply the skin to the Application, as the following example shows:

<?xml version="1.0"?>
<!-- containers\application\AppSparkBackground.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" 
    skinClass="mySkins.MyAppBackgroundSkin">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    
</s:Application>The executing SWF file for the previous example is shown below:

The next skin example uses the Image control to embed an image for the background of the Application container:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\application\mySkins\MyAppBackgroundImageSkin.mxml -->
<s:Skin xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

    <fx:Metadata>
        [HostComponent("spark.components.Application")]
    </fx:Metadata> 
    
    <s:states>
        <s:State name="normal" />
        <s:State name="disabled" />
    </s:states>
    
    <!-- Use an Image control to embed an image for the 
            background of the Application container. -->    
    <mx:Image source="@Embed(source='logo.jpg')" 
        left="0" right="0" top="0" bottom="0"
        maintainAspectRatio="false" />
        
    <s:Group id="contentGroup" left="0" right="0" top="0" bottom="0" />        
</s:Skin>

For more information on skinning, see Spark Skinning.

Changing the MX Application container background

The Application container backgroundGradientAlphas, backgroundGradientColors, and backgroundImage styles control the container background. By default, these properties define an opaque gray gradient background.

You specify an image for the application background by using the backgroundImage property. If you set both the backgroundImage property and the backgroundGradientColors property, Flex ignores backgroundGradientColors.

You can specify a gradient background for the application in two ways:

Set the backgroundGradientColors property to two values, as in the following example:
```
<mx:Application xmlns="http://ns.adobe.com/mxml/2009" 
    backgroundGradientColors="[0x0000FF, 0xCCCCCC]">
```
Flex calculates the gradient pattern between the two specified values.
Set the backgroundColor property to the desired value, as in the following example:
```
<mx:Application xmlns="http://ns.adobe.com/mxml/2009" 
    backgroundColor="red">
```
Flex sets the gradient background to solid red.

To set a solid background to the application by using the backgroundGradientColors property, specify the same two values to the backgroundGradientColors property, as the following example shows:
```
<mx:Application xmlns="http://ns.adobe.com/mxml/2009" 
    backgroundGradientColors="[#FFFFFF, #FFFFFF]">
```
This example defines a solid white background.

The backgroundColor property specifies the background color of the Stage area in Flash Player, which is visible during application loading and initialization, and a background gradient while the application is running. By default, the backgroundColor property is set to 0xFFFFFF (white).

If you use the backgroundGradientColors property to set the application background, set the backgroundColor property to compliment the backgroundGradientColors property, as the following example shows:
```
<mx:Application xmlns="http://ns.adobe.com/mxml/2009" 
    backgroundGradientColors="[0x0000FF, 0xCCCCCC]"  
    backgroundColor="0x0000FF">
```
In this example, you use the backgroundGradientColors property to set a gradient pattern from a dark blue to gray, and the backgroundColor property to set the Stage area in Flash Player to dark blue, which is visible during application loading and initialization.

Adding a control bar area to the application container

An application control bar contains a group of controls outside of the main content area of an application container. The control bar is always visible, and cannot be scrolled like other container children.

For the MX Application container, create a control bar area by adding the ApplicationControlBar container as a child of the MX Application container. For more information and examples, see MX ApplicationControlBar layout container.

For the Spark Application container, use the controlBarContent property to define the controls that appear in the control bar area, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\application\AppSparkCB.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"
    width="600">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>
    <s:controlBarContent>
        <mx:MenuBar height="100%" 
            dataProvider="{menuXML}" 
            labelField="@label" 
            showRoot="true"/>
        <mx:HBox paddingBottom="5" 
            paddingTop="5">
            <mx:ComboBox dataProvider="{cmbDP}"/>
            <mx:Spacer width="100%"/>
            <mx:TextInput id="myTI" text=""/>
            <mx:Button id="srch1" 
                label="Search" 
                click="Alert.show('Searching');"/>
        </mx:HBox>
    </s:controlBarContent>
    
    <fx:Script>
        <![CDATA[
            import mx.controls.Alert;
        ]]>
    </fx:Script>
    
    <fx:Declarations>
        <fx:XMLList id="menuXML">
            <fx:menuitem label="File">
                <fx:menuitem label="New" data="New"/>
                <fx:menuitem label="Open" data="Open"/>
                <fx:menuitem label="Save" data="Save"/>
                <fx:menuitem label="Exit" data="Exit"/>
            </fx:menuitem>
            <fx:menuitem label="Edit">
                <fx:menuitem label="Cut" data="Cut"/>
                <fx:menuitem label="Copy" data="Copy"/>
                <fx:menuitem label="Paste" data="Paste"/>
            </fx:menuitem>
            <fx:menuitem label="View"/>
        </fx:XMLList>
        
        <fx:Array id="cmbDP">
            <fx:String>Item 1</fx:String>
            <fx:String>Item 2</fx:String>
            <fx:String>Item 3</fx:String>
        </fx:Array>
    </fx:Declarations>
    
    <s:Button label="Button"/>
    <mx:TextArea width="300" height="200"/>        
</s:Application>The executing SWF file for the previous example is shown below:

The location and appearance of the control bar area of the Spark Application container is determined by the spark.skins.spark.ApplicationSkin class, the skin class for the Spark Application container. By default, the ApplicationSkin class defines the control bar area to appear at the top of the content area of the Application container with a grey background. Create a custom skin to change the default appearance of the control bar.

By default, the controls in the control bar area use horizontal layout. Use the Application.controlBarLayout property to specify a different layout, as the following example shows:

<s:controlBarLayout> 
    <s:HorizontalLayout paddingLeft="12" gap="5"/> 
</s:controlBarLayout>

Application events

The following events are dispatched only by the application containers:

applicationComplete Dispatched after the application has been initialized, processed by the LayoutManager, and attached to the display list. This is the last event dispatched during an application’s startup sequence. It is later than the application’s creationComplete event, which gets dispatched before the preloader has been removed and the application has been attached to the display list.
error Dispatched when an HTTPService call fails.

Viewing the application source code

You can use the viewSourceURL property of the application containers to specify a URL to the application’s source code. If you set this property, Flex adds a View Source menu item to the application’s context menu, which you open by right-clicking anywhere in your application. Select the View Source menu item to open the URL specified by the viewSourceURL property in a new browser window.

Set the viewSourceURL property by using MXML, not ActionScript, as the following example shows:

<?xml version="1.0"?>
<!-- containers\application\AppSourceURL.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"
    viewSourceURL="assets/AppSourceURL.txt">
    <s:layout>
        <s:VerticalLayout/>
    </s:layout> 
 
    <s:Button label="Click Me"/>
</s:Application>The executing SWF file for the previous example is shown below:

You typically deploy your source code not as an MXML file, but as a text or HTML file. In this example, the source code is in the file AppSourceURL.txt. If you use an HTML file to represent your source code, you can add formatting and coloring to make it easier to read.

Specifying options of the Application container

You can specify several options of the application container to control your application. The following table describes these options:

Option	Type	Description
frameRate	Number	Specifies the frame rate of the application, in frames per second. The default value is 24.
pageTitle	String	Specifies a String that appears in the title bar of the browser. This property provides the same functionality as the HTML `<title>` tag.
preloader	String	Specifies the path of a SWC component class or ActionScript component class that defines a custom progress bar. A SWC component must be in the same directory as the MXML file or in the WEB-INF/flex/user_classes directory of your Flex web application. For more information, see Showing the download progress of an application.
scriptRecursionLimit	Number	Specifies the maximum depth of Flash Player or AIR call stack before Flash Player or AIR stops. This is essentially the stack overflow limit. The default value is 1000.
scriptTimeLimit	Number	Specifies the maximum duration, in seconds, that an ActionScript event listener can execute before Flash Player or AIR assumes that it has stopped processing and aborts it. The default value is 60 seconds, which is also the maximum allowable value that you can set.
`useDirectBlit`	Boolean	Specifies whether hardware acceleration is used to copy graphics to the screen (if such acceleration is available). This option only applies to applications running in the standalone Flash Player. For applications running in a browser, setting `useDirectBlit` to `true` is equivalent to setting `wmode` to `"direct"` in the HTML wrapper. For AIR applications, use the `renderMode` application descriptor tag. The default value is `false`.
`useGPU`	Boolean	Specifies whether GPU (Graphics Processing Unit) acceleration is used when drawing graphics (if such acceleration is available). This option only applies to applications running in the standalone Flash Player. For applications running in a browser, setting `useGPU` to `true` is equivalent to setting `wmode` to `"gpu"` in the HTML wrapper. For AIR applications, use the `renderMode` application descriptor tag. The default value is `false`.
usePreloader	Boolean	Specifies whether to disable the application preloader (`false`) or not (`true`). The default value is `true`. To use the default preloader, your application must be at least 160 pixels wide. For more information, see Showing the download progress of an application.

Note: Properties frameRate, pageTitle, preloader, scriptRecursionLimit, and usePreloader, cannot be set in ActionScript; they must be set in MXML code.