AIR automatically creates the first window for an application, but you can create any additional windows you need. To create a native window, use the NativeWindow constructor method. To create a Flex window, use the mx:Window class. To create an HTML window, either use the HTMLLoader createRootWindow() method or, from an HTML document, call the JavaScript window.open() method.

Contents

• Specifying window initialization properties
• Creating the initial application window
• Creating a new mx:Window
• Creating a new NativeWindow
• Creating a new HTML window
• Adding content to a window
• Example: Creating a native window

Specifying window initialization properties

The initialization properties of a window cannot be changed after the desktop window is created. These immutable properties and their default values include:

Set the properties for the initial window created by AIR in the application descriptor file. The main window of an AIR application is always type, normal. (Additional window properties can be specified in the descriptor file, such as visible, width, and height, but these properties can be changed at any time.)

When you create a window with the Flex mx:Window class, specify the initialization properties on the window object itself, either in the MXML declaration for the window, or in the code that creates the window. The desktop window is not created until you call the window open() method. Once a window is opened, these initialization properties cannot be changed.

Set the properties for other native and HTML windows created by your application using the NativeWindowInitOptions class. When you create a window, you must pass a NativeWindowInitOptions object specifying the window properties to either the NativeWindow constructor function or the HTMLLoader createRootWindow() method.

The following code creates a NativeWindowInitOptions object for a utility window:

var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.systemChrome = NativeWindowSystemChrome.STANDARD;
options.type = NativeWindowType.UTILITY
options.transparent = false;
options.resizable = false;
options.maximizable = false;

Setting systemChrome to standard when transparent is true or type is lightweight is not supported.

Creating the initial application window

AIR creates the initial application window based on the properties specified in the application descriptor and loads the file referenced in the content element. The content must be a SWF or an HTML file.

The initial window can be the main window of your application or it can merely serve to launch one or more other windows. You do not have to make it visible at all.

Creating the initial window with Flex

When creating an AIR application with the Flex framework, use the mx:WindowedApplication as the root element of your main MXML file. (You can use the mx:Application component, but it does not support all the window features available in AIR.) The WindowedApplication component serves as the initial entry point for the application.

When you launch the application, AIR creates a native window, initializes the Flex framework, and adds the WindowedApplication object to the window stage. When the launch sequence finishes, the WindowedApplication dispatches an applicationComplete event. Access the desktop window object with the nativeWindow property of the WindowedApplication instance.

The following example creates a simple WindowedApplication component that sets its x and y coordinates:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" 
    applicationComplete="placeWindow()">
    <mx:Script>
        <![CDATA[
            private function placeWindow():void{
                this.nativeWindow.x = 300;
                this.nativeWindow.y = 300;
            }
        ]]>
    </mx:Script>
    <mx:Label text="Hello World" horizontalCenter="0" verticalCenter="0"/>
</mx:WindowedApplication>

Creating the initial window with ActionScript

When you create an AIR application using the Flex 3 SDK and ActionScript, the main class of your application must extend the Sprite class (or a subclass of the Sprite class). This class serves as the main entry point for the application.

When your application launches, AIR creates a window, creates an instance of the main class, and adds the instance to the window stage. To access the window, you can listen for the addedToStage event and then use the nativeWindow property of the Stage object to get a reference to the NativeWindow object.

The following example illustrates the basic skeleton for the main class of an AIR application built with ActionScript:

package {
    import flash.display.NativeWindow;
    import flash.display.Sprite;
    import flash.events.Event;

    public class Main extends Sprite
    {
        private var mainWindow:NativeWindow;
        public function Main(){
            this.addEventListener(Event.ADDED_TO_STAGE, initialize);
        }
        
        private function initialize(event:Event):void{
            mainWindow = this.stage.nativeWindow;
            //perform initialization...
            mainWindow.activate(); //show the window
        }
    }
}

Creating a new mx:Window

To create a new mx:Window, you can create an MXML file using mx:Window as the root tag, or you can call the Window class constructor directly.

The following example creates and shows an mx:Window by calling the Window constructor:

var newWindow:Window = new Window();
newWindow.systemChrome = NativeWindowSystemChrome.NONE;
newWindow.transparent = true;
newWindow.title = "New Window";
newWindow.width = 200;
newWindow.height = 200;
newWindow.open(true);

Creating a new NativeWindow

To create a new NativeWindow, pass a NativeWindowInitOptions object to the NativeWindow constructor:

var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.systemChrome = NativeWindowSystemChrome.STANDARD;
options.transparent = false;
var newWindow:NativeWindow = new NativeWindow(options);

The window is not shown until you set the visible property to true or call the activate() method

Once the window is created, you can initialize its properties and load content into the window using the stage property and Flash display list techniques.

In almost all cases, you should set the stage scaleMode property of a new native window to noScale (use the StageScaleMode.NO_SCALE constant). The Flash scale modes are designed for situations in which the application author does not know the aspect ratio of the application display space in advance. The scale modes let the author choose the least-bad compromise: clip the content, stretch or squash it, or pad it with empty space. Since you control the display space in AIR (the window frame), you can size the window to the content or the content to the window without compromise. The scale mode for Flex and HTML windows is set to noScale automatically.

var maxOSSize:Point = NativeWindow.systemMaxSize;
var minOSSize:Point = NativeWindow.systemMinSize;

Creating a new HTML window

To create a new HTML window, you can either call the JavaScript window.open() function, or you can call the AIR HTMLLoader class createRootWindow() function.

HTML content in any security sandbox can use the standard JavaScript Window.open() method. If the content is running outside the application sandbox, the open() method can only be called in response to user interaction, such as a mouse click or keypress. When open() is called, a window with system chrome will be created to display the content at the specified URL. For example:

newWindow = window.open("xmpl.html", "logWindow", "height=600, width=400, top=10, left=10");

Content in the application security sandbox has access to the more powerful method of creating windows, HTMLLoader.createRootWindow(). With this method you can specify all the creation options for a new window. For example, the following code creates a lightweight type window without system chrome that is 300x400 pixels in size.

var options = new air.NativeWindowInitOptions();
options.systemChrome = "none";
options.type = "lightweight";

var windowBounds = new air.Rectangle(200,250,300,400);
newHTMLLoader = air.HTMLLoader.createRootWindow(true, options, true, windowBounds);
newHTMLLoader.load(new air.URLRequest("xmpl.html"));

Windows created with the createRootWindow() method remain independent from the opening window. The parent and opener properties of the JavaScript Window object are null. The opening window can access the Window object of the new window using the HTMLLoader reference returned by the createRootWindow() function. In the context of the previous example, the statement newHTMLLoader.window would reference the Javascript Window object of the created window.

Adding content to a window

How you add content to an AIR window depends on the type of window. MXML and HTML let you declaratively define the basic content of the window. You can embed resources in the application SWF or you can load them from separate application files. Flex, Flash and HTML content can all be created on the fly and added to a window dynamically.

When you load SWF content, or HTML content containing JavaScript, you must take the AIR security model into consideration. Any content in the application security sandbox, that is, content installed with your application and loadable with the app: URL scheme, will have full privileges to access all the AIR APIs. Any content loaded from outside this sandbox cannot access the AIR APIs. JavaScript content outside the application sandbox will not be able to use the runtime, nativeWindow or htmlLoader properties of the JavaScript Window object.

To allow safe cross-scripting, you can use a sandbox bridge to provide a limited interface between application content and non-application content. In HTML content, you can also map pages of your application into a non-application sandbox to allow the code on that page to cross-script external content. See AIR security.

Loading a SWF or image

You can load Flash or images into the display list of a native window using the flash.display.Loader class.

package {
    import flash.display.Sprite;
    import flash.events.Event;
    import flash.net.URLRequest;
    import flash.display.Loader;

    public class LoadedSWF extends Sprite
    {
        public function LoadedSWF(){
            var loader:Loader = new Loader();
            loader.load(new URLRequest("visual.swf"));                   
            loader.contentLoaderInfo.addEventListener(Event.COMPLETE,loadFlash);
        }

        private function loadFlash(event:Event):void{
            addChild(event.target.loader); 
        }
    }
}

You can load a SWF file that contains library code for use in an HTML-based application. The simplest way to load a SWF in an HTML window is to use the script tag, but you can also use the Loader API directly.

Loading HTML content into a NativeWindow

To load HTML content into a NativeWindow, you can either add an HTMLLoader object to the window stage and load the HTML content into the HTMLLoader, or create a new window that already contains an HTMLLoader object by using the HTMLLoader.createRootWindow()method. The following example displays HTML content within a 300 by 500 pixel display area on the stage of a native window:

//newWindow is a NativeWindow instance
var htmlView:HTMLLoader = new HTMLLoader();
html.width = 300;
html.height = 500;

//set the stage so display objects are added to the top-left and not scaled
newWindow.stage.align = "TL";
newWindow.stage.scaleMode = "noScale";
newWindow.stage.addChild( htmlView );

//urlString is the URL of the HTML page to load
htmlView.load( new URLRequest(urlString) );

To load an HTML page into a Flex application, you can use the Flex HTML component.

Loading Flash content within an HTML page

You can load Flash or Flex SWF files in an HTML page using standard <object> tags. The SWF content is loaded into its own environment with an independent stage. The following tag can be used to display a SWF file on a page:

<object type="application/x-shockwave-flash" width="100%" height="100%">
    <movie movie="app:/SWFFile.swf"/>
</object>

You can also use a script to load content dynamically:

<script>
function showSWF(urlString){
    var display = document.getElementById("flexDisplay");
    display.appendChild(createSWFObject(urlString,650,650)); 
}

function createSWFObject(urlString, width, height){
    var SWFObject = document.createElement("object");
     SWFObject.setAttribute("type","application/x-shockwave-flash");
     SWFObject.setAttribute("width","100%"); 
     SWFObject.setAttribute("height","100%");
     var movieParam = document.createElement("param");
     movieParam.setAttribute("name","movie");
     movieParam.setAttribute("value",urlString);
     SWFObject.appendChild(movieParam);
     return SWFObject;
}
</script>

Adding Flash content as an overlay on an HTML window

Because HTML windows are contained within a NativeWindow instance, you can add Flash display objects both above and below the HTML layer in the display list.

To add a display object above the HTML layer, use the addChild() method of the window.nativeWindow.stage property. The addChild() method will add content layered above any existing content in the window.

To add a display object below the HTML layer, use the addChildAt() method of the window.nativeWindow.stage property, passing in a value of zero for the index parameter. Placing an object at the zero index will move existing content, including the HTML display, up one layer and insert the new content at the bottom. For content layered underneath the HTML page to be visible, you must set the paintsDefaultBackground property of the HTMLlLoader object to false. In addition, any elements of the page that set a background color, will not be transparent. If, for example, you set a background color for the body element of the page, none of the page will be transparent.

The following example illustrates how to add a Flash display objects as overlays and underlays to an HTML page. The example creates two simple shape objects, adds one below the HTML content and one above. The example also updates the shape position based on the enterFrame event.

<html>
<head>
<title>Bouncers</title>
<script src="AIRAliases.js" type="text/javascript"></script>
<script language="JavaScript" type="text/javascript">
air.Shape = window.runtime.flash.display.Shape;

function Bouncer(radius, color){
    this.radius = radius;
    this.color = color;

    //velocity 
    this.vX = -1.3;
    this.vY = -1;

    //Create a Shape object and draw a circle with its graphics property
    this.shape = new air.Shape();    
    this.shape.graphics.lineStyle(1,0);
    this.shape.graphics.beginFill(this.color,.9);
    this.shape.graphics.drawCircle(0,0,this.radius);
    this.shape.graphics.endFill();
    
    //Set the starting position
    this.shape.x = 100;
    this.shape.y = 100;


    //Moves the sprite by adding (vX,vY) to the current position
    this.update = function(){
        this.shape.x += this.vX;
        this.shape.y += this.vY;
        
        //Keep the sprite within the window
        if( this.shape.x - this.radius < 0){ 
            this.vX = -this.vX;
        }
        if( this.shape.y - this.radius < 0){
            this.vY = -this.vY;
        }
        if( this.shape.x  + this.radius > window.nativeWindow.stage.stageWidth){
            this.vX = -this.vX;
        }
        if( this.shape.y  + this.radius > window.nativeWindow.stage.stageHeight){
            this.vY = -this.vY;
        }
        
    };
}

function init(){
    //turn off the default HTML background
    window.htmlLoader.paintsDefaultBackground = false;
    var bottom = new Bouncer(60,0xff2233);
    var top = new Bouncer(30,0x2441ff);

    //listen for the enterFrame event
    window.htmlLoader.addEventListener("enterFrame",function(evt){
        bottom.update();
        top.update();
    });
    
    //add the bouncing shapes to the window stage
    window.nativeWindow.stage.addChildAt(bottom.shape,0);
    window.nativeWindow.stage.addChild(top.shape);
}
</script>
<body onload="init();">
<h1>de Finibus Bonorum et Malorum</h1>
<p>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium 
doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis 
et quasi architecto beatae vitae dicta sunt explicabo.</p>
<p style="background-color:#FFFF00; color:#660000;">This paragraph has a background color.</p>
<p>At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis 
praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias 
excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui 
officia deserunt mollitia animi, id est laborum et dolorum fuga.</p>
</body>
</html>

Example: Creating a native window

The following example illustrates how to create a native window.

public function createNativeWindow():void {
    //create the init options
    var options:NativeWindowInitOptions = new NativeWindowInitOptions();
    options.transparent = false;
    options.systemChrome = NativeWindowSystemChrome.STANDARD;
    options.type = NativeWindowType.NORMAL;
    
    //create the window
    var newWindow:NativeWindow = new NativeWindow(options);
    newWindow.title = "A title";
    newWindow.width = 600;
    newWindow.height = 400;
    
    newWindow.stage.align = StageAlign.TOP_LEFT;
    newWindow.stage.scaleMode = StageScaleMode.NO_SCALE;

    //activate and show the new window
    newWindow.activate();
}