Creating windows

Adobe AIR 1.0 and later

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:

Property

Default value

systemChrome

standard

type

normal

transparent

false

owner

null

maximizable

true

minimizable

true

resizable

true

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 = new air.NativeWindowInitOptions(); 
options.systemChrome = air.NativeWindowSystemChrome.STANDARD; 
options.type = air.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.

Creating the initial application window

Use a standard HTML page for the initial window of your application. This page is loaded from the application install directory and placed in the application sandbox. The page serves as the initial entry point for your application.

When your application launches, AIR creates a window, sets up the HTML environment, and loads your HTML page. Before parsing any scripts or adding any elements to the HTML DOM, AIR adds the runtime , htmlLoader , and nativeWindow properties to the JavaScript Window object. You can use these properties to access the runtime classes from JavaScript. The nativeWindow property gives you direct access to the properties and methods of the desktop window.

The following example illustrates the basic skeleton for the main page of an AIR application built with HTML. The page waits for the JavaScript window load event and then shows the native window. 

<html> 
    <head> 
        <script language="javascript" type="text/javascript" src="AIRAliases.js"></script> 
        <script language="javascript"> 
            window.onload=init; 
 
            function init(){ 
                window.nativeWindow.activate(); 
            } 
        </script> 
    </head> 
    <body></body> 
</html>
Note: The AIRAliases.js file referenced in this example is a script file that defines convenient alias variables for the commonly used built-in AIR classes. The file is available inside the frameworks directory of the AIR SDK.

Creating a NativeWindow

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

var options = new air.NativeWindowInitOptions(); 
options.systemChrome = air.NativeWindowSystemChrome.STANDARD; 
options.transparent = false; 
var newWindow = new air.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 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 = air.NativeWindow.systemMaxSize; 
var minOSSize = air.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 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> 
<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 in the ActionScript 3.0 Developer’s Guide .

Note: To access the runtime, nativeWindow and htmlLoader properties of the JavaScript Window object, the HTML page must be loaded from the application directory. This will always be the case for the root page in an HTML-based application, but may not be true for other content. In addition, documents loaded into frames even within the application sandbox do not receive these properties, but can access those of the parent document.

Example: Creating a native window

The following example illustrates how to create a native window: 

function createNativeWindow() { 
    //create the init options 
    var options = new air.NativeWindowInitOptions(); 
    options.transparent = false; 
    options.systemChrome = air.NativeWindowSystemChrome.STANDARD; 
    options.type = air.NativeWindowType.NORMAL; 
     
    //create the window 
    var newWindow = new air.NativeWindow(options); 
    newWindow.title = "A title"; 
    newWindow.width = 600; 
    newWindow.height = 400; 
     
    //activate and show the new window 
    newWindow.activate(); 
}

// Ethnio survey code removed