Skip to main content

Creating windows

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 an HTML window, either use the HTMLLoader createRootWindow() method or, from an HTML document, call the JavaScript window.open() method. The window created is a NativeWindow object whose display list contains an HTMLLoader object. The HTMLLoader object interprets and displays the HTML and JavaScript content for the window. You can access the properties of the underlying NativeWindow object from JavaScript using the window.nativeWindow property. (This property is only accessible to code running in the AIR application sandbox.)

When you initialize a window—including the initial application window—you should consider creating the window in the invisible state, loading content or executing any graphical updates, and then making the window visible. This sequence prevents any jarring visual changes from being visible to your users. You can specify that the initial window of your application should be created in the invisible state by specifying the <visible>false</visible> tag in the application descriptor (or by leaving the tag out altogether since false is the default value). New NativeWindows are invisible by default. When you create an HTML window with the HTMLLoader createRootWindow() method, you can set the visible argument to false. Call the NativeWindow activate() method or set the visible property to true to make a window visible.

Specifying window initialization properties​

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

PropertyDefault value
systemChromestandard
typenormal
transparentfalse
ownernull
maximizabletrue
minimizabletrue
resizabletrue

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

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.

Note: You cannot set the initialization properties for a window created with the JavaScript window.open() function. You can, however, override how these windows are created by implementing your own HTMLHost class. See Handling JavaScript calls to window.open() for more information.

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 underlying NativeWindow object is not created until you call the open() method. Once a window is opened, these initialization properties cannot be changed.

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 element must reference a SWF file 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 ActionScript​

When you create an AIR application using ActionScript, the main class of your application must extend the Sprite class (or a subclass of Sprite). 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 MainClass extends Sprite
    {
        private var mainWindow:NativeWindow;
        public function MainClass(){
            this.addEventListener(Event.ADDED_TO_STAGE, initialize);
        }

        private function initialize(event:Event):void{
            mainWindow = this.stage.nativeWindow;
            //perform initialization...
            mainWindow.activate(); //show the window
        }
    }
}

Note: Technically, you CAN access the nativeWindow property in the constructor function of the main class. However, this is a special case applying only to the initial application window.

When creating an application in Flash Professional, the main document class is created automatically if you do not create your own in a separate ActionScript file. You can access the NativeWindow object for the initial window using the stage nativeWindow property. For example, the following code activates the main window in the maximized state (from the timeline):

import flash.display.NativeWindow;

var mainWindow:NativeWindow = this.stage.nativeWindow;
mainWindow.maximize();
mainWindow.activate();

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 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="https://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 a NativeWindow​

To create a 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.

Note: To determine the maximum and minimum window sizes allowed on the current operating system, use the following static NativeWindow properties:

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

Creating an HTML window​

To create an HTML window, you can either call the JavaScript Window.open() method, or you can call the AIR HTMLLoader class createRootWindow() method.

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 is 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");

Note: You can extend the HTMLHost class in ActionScript to customize the window created with the JavaScript window.open() function. See About extending the HTMLHost class.

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 JavaScript 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"));

Note: If the content loaded by a new window is outside the application security sandbox, the window object does not have the AIR properties: runtime, nativeWindow, or htmlLoader.

If you create a transparent window, then SWF content embedded in the HTML loaded into that window is not always displayed. You must set the wmode parameter of the object or embed tag used to reference the SWF file to either opaque or transparent. The default value of wmode is window, so, by default, SWF content is not displayed in transparent windows. PDF content cannot be displayed in transparent windows, no matter which wmode value is set. (Prior to AIR 1.5.2, SWF content could not be displayed in transparent windows, either.)

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.

Note: The createRootWindow() function can be called from both JavaScript and ActionScript.

Creating a mx:Window​

To create a 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 a 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);

Adding content to a window​

How you add content to an AIR window depends on the type of window. For example, MXML and HTML let you declaratively define the basic content of the window. You can embed resources in the application SWF files 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, has 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 is not 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 file or image​

You can load Flash SWF files 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);
        }
    }
}

Note: Older SWF files created using ActionScript 1 or 2 share global states such as class definitions, singletons, and global variables if they are loaded into the same window. If such a SWF file relies on untouched global states to work correctly, it cannot be loaded more than once into the same window, or loaded into the same window as another SWF file using overlapping class definitions and variables. This content can be loaded into separate windows.

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 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();
htmlView.width = 300;
htmlView.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.

SWF content in an HTML file is not displayed if the window uses transparency (that is the transparent property of the window is true) unless the wmode parameter of the object or embed tag used to reference the SWF file is set to either opaque or transparent. Since the default wmode value is window, by default, SWF content is not displayed in a transparent window. PDF content is not displayed in a transparent window no matter what wmode value is used.

Also, neither SWF nor PDF content is displayed if the HTMLLoader control is scaled, rotated, or if the HTMLLoader alpha property is set to a value other than 1.0.

Adding SWF 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 adds 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 moves 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>
</head>
<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>

This example provides a rudimentary introduction to some advanced techniques that cross over the boundaries between JavaScript and ActionScript in AIR. If your are unfamiliar with using ActionScript display objects, refer to Display programming.

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();
}

More Help topics

Using the Flex AIR components