Flex container components define the content, sizing, and positioning for a specific part of an application. For AIR applications, Flex includes two specific window components that serve as containers whose content area is an operating system window. Both the WindowedApplication and the Window components can be used to define the contents of an operating system window. They also provide the means to define and control characteristics of the window itself, such as the window's size, its position on the user's screen, and the presence of window chrome.

Contents

• Controlling window chrome
• WindowedApplication container
• Window container

Controlling window chrome

The WindowedApplication component and the Window component allow you to control the presence and the appearance of the window chrome.

These components provide the following window controls:

• A title bar
• A minimize button
• A maximize button
• A close button

How these controls are represented depends on the setting of the systemChrome value, which is defined in the application.xml file for a WindowedApplication component, or in the Window component's systemChrome property. If systemChrome is set to "standard" in the application.xml file (or flash.display.NativeWindowSystemChrome.STANDARD in ActionScript) the operating system renders the chrome for the title bar and border of the window. However, if systemChrome is set to "none" (NativeWindowSystemChrome.NONE) the Flex Window or WindowedApplication component draws its own title bar, including the buttons listed previously.

The title bar area of the window chrome (either the operating system or Flex chrome) includes a title message and an icon that can be set and modified programmatically. In addition to the operating system chrome, Flex adds additional common window chrome elements including a status bar with a definable status message and a resize gripper in the bottom-right corner of the window. All the Flex-drawn chrome can be hidden as a group by setting the showFlexChrome property to false. A single chrome element can be hidden by setting the showTitleBar, showGripper or showStatusBar property to false.

The window that a WindowedApplication or Window component defines conforms to the standard behavior of the operating system. The user can move the window by dragging the title bar and resize the window by dragging on any side or corner of the window. The components also include a set of properties that allow to control window sizing, including minimumHeight, minimumWidth, maximumHeight, and maximumWidth.

WindowedApplication container

The WindowedApplication container defines an application container that you use to create Flex applications for AIR that use the native operating system chrome. The WindowedApplication container adds window-related functionality and desktop application-specific functionality to the Flex Application container, which you can use when you build AIR applications.

The WindowedApplication container serves two roles. On one hand, it provides the entry point into the main application, which in turn executes other application logic. In that sense it serves as the core of the entire application, just as the Application component does for a browser-based Flex application. On the other hand, the WindowedApplication container represents the first native window of the application. If the application only uses one native window, the WindowedApplication is the base stage that contains all other content. If your application opens additional native windows, each window has its own stage and display list. The native window defined by the WindowedApplication is no different than any other application window in this respect. This is different from a browser-based Flex application, where all of an application's windows are drawn by Flex within the same stage (the Application container). For example, in a Flex AIR application, registering a keyDown event listener on the WindowedApplication component only dispatches events when a key is pressed while the initial window has focus. If the application has multiple native windows and another of the windows has focus when the key is pressed, the event is not dispatched. This behavior differs from a non-AIR Flex application, in which a keyDown listener registered with the Application container receives notification of all keypresses while the application has focus.

For more information on the WindowedApplication container, see the Flex 3 Language Reference.

Creating and using a WindowedApplication container

The <mx:WindowedApplication> container component defines an AIR application object that includes its own window controls. In an MXML AIR application, a <mx:WindowedApplication> tag replaces the <mx:Application> tag.

By default, the WindowedApplication component creates an application window for which systemChrome is set to NativeWindowSystemChrome.STANDARD and visible is set to true. These settings are made in the application.xml file for the AIR application. To eliminate the system chrome and window controls that the WindowedApplication component creates by default, in the <mx:WindowedApplication> tag set the useFlexChrome attribute to false, and in the application.xml file set systemChrome to none.

WindowedApplication container example

The following application shows a simple use of the WindowedApplication container:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication 
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="absolute">
    <mx:Text text="Hello World" />
</mx:WindowedApplication>

Window container

The Window component is a Flex container that is used to define the content and layout of operating system windows that are opened after an application launches. In other words, it is used for windows other than the initial or main window of the application, which is a WindowedApplication component. In addition to the functionality that the Window component shares with the WindowedApplication component, a Window component allows you to define the main characteristics of the window. The characteristics you can specify include the type of window, the type of chrome, whether certain actions (such as resizing and maximizing) are permitted for the window, and more. These characteristics are accessed as properties that can be set when the component is initially created, before the actual operating system window is displayed. However, once the actual window is opened, the properties can no longer be set and can only be read.

For more information about the Window container, see the Flex 3 Language Reference.

Creating and using a Window container

The <mx:Window> container component defines an AIR application object that includes its own window controls. In an MXML AIR application, a <mx:Window> tag is used as the top-level tag of an MXML component, with the window's content defined in the body of the MXML component document. However, unlike other MXML components, a Window-based component cannot be used in another MXML document. Instead, you create an instance of the MXML component in ActionScript.

Because several of the properties of the Window component can only be set before the window is opened, they can be set as properties in the <mx:Window> MXML tag. They can also be set using ActionScript, either in an <mx:Script> block in the window's MXML document or in code that creates an instance of the window.

Once the window's initial properties are set, you call the Window component's open() method to cause the operating system window to appear on the user's display.

Window container example

The following example shows a basic use of the Window component. The example includes two MXML files. The first uses a WindowedApplication container and is the initial window of the application. The second uses the Window container to define a secondary window for the application. In this example, the main window simulates a "splash screen" for the application. After a set time (4 seconds) it closes the splash screen and opens the second window. In order to make a splash screen window with no window chrome, in the application.xml file the systemChrome tag is set to none.

The following code defines the main application MXML file, which contains the initial window (the splash screen) that opens automatically when the application is run:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" showFlexChrome="false" creationComplete="init();">
    <mx:Script>
        <![CDATA[
            private const LOAD_DELAY:int = 4;
            private var timeElapsed:int = 0;
            private var loadTimer:Timer;
            
            private var docWindow:DocumentWindow;
            
            private function init():void
            {
                // center the window on the screen
                var screenBounds:Rectangle = Screen.mainScreen.bounds;
                nativeWindow.x = (screenBounds.width - nativeWindow.width) / 2;
                nativeWindow.y = (screenBounds.height - nativeWindow.height) / 2;
                
                // start the timer, which simulates a loading delay
                loadTimer = new Timer(1000);
                loadTimer.addEventListener(TimerEvent.TIMER, incrementTime);
                loadTimer.start();
                
                updateStatus();
            }
            
            private function incrementTime(event:TimerEvent):void
            {
                timeElapsed++;
                
                updateStatus();
                
                // if the loading delay has passed, stop the timer, 
                // close the splash screen, and open the document window
                if ((LOAD_DELAY - timeElapsed) == 0)
                {
                    loadTimer.stop();
                    loadTimer.removeEventListener(TimerEvent.TIMER, incrementTime);
                    loadTimer = null;
                    
                    nativeWindow.close();
                    
                    // open a new instance of the document window
                    docWindow = new DocumentWindow();
                    docWindow.open();
                }
            }
            
            private function updateStatus():void
            {
                var timeRemaining:uint = LOAD_DELAY - timeElapsed;
                var timeRemainingMsg:String = timeRemaining.toString() + " second";
                if (timeRemaining != 1) { timeRemainingMsg += "s"; }
                timeRemainingMsg += " remaining.";
                
                loadStatusMessage.text = "initializing... " + timeRemainingMsg;
            }
        ]]>
    </mx:Script>
    <mx:VBox horizontalCenter="0" verticalCenter="0">
        <mx:Text text="My Splash Screen" fontFamily="Courier New" fontSize="36"/>
        <mx:Text id="loadStatusMessage" text="initializing..."/>
    </mx:VBox>
</mx:Application>

The incrementTime() method is called each second and when the appropriate time is reached, a DocumentWindow instance is created and its open() method is called. The DocumentWindow class is defined in a separate MXML document. Its base MXML tag is the <mx:Window> tag so it is a subclass of the Window class (the Window component). Here is the source code for the DocumentWindow MXML file:

<?xml version="1.0" encoding="utf-8"?>
<mx:Window xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="absolute" 
    title="Document window" 
    width="550" height="450">
    <mx:Text text="This is a document window." horizontalCenter="0" verticalCenter="0"/>
</mx:Window>