Creating windows

Contents [Hide]

Specifying window initialization properties
Creating the initial application window
Creating a NativeWindow
Creating an HTML window
Adding content to a window
Example: Creating a native window

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.

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:

Property	Default value
systemChrome	standard
type	normal
transparent	false
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 into 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>

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.

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.

Adding content to a window

How you add content to an AIR window depends on the type of window. HTML lets you declaratively define the basic content of the window in a text file. You can load a variety of resources from separate application files. HTML and Flash content can 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 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);  
        } 
    } 
}

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

Note: SWF or PDF content in an HTML file is not displayed if the window uses transparency (that is the transparent property of the window is true) or if the HTMLLoader control is scaled.

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, please refer to the Display Programming section of the Programming ActionScript 3.0 guide for more information.

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