AIR provides an easy-to-use, cross-platform window API for creating native operating system windows using Flash, Flex, and HTML programming techniques.

With AIR, you have a wide latitude in developing the look-and-feel of your application. The windows you create can look like a standard desktop application, matching Apple style when run on the Mac, and conforming to Microsoft conventions when run on Windows. Or you can use the skinnable, extendible chrome provided by the Flex framework to establish your own style no matter where your application is run. You can even draw your own windows with vector and bitmap artwork with full support for transparency and alpha blending against the desktop. Tired of rectangular windows? Draw a round one.

Contents

Windows in AIR

Native Window classes

Native window event flow

Properties controlling native window style and behavior

A visual window catalog

Windows in AIR

AIR supports three distinct APIs for working with windows: the ActionScript-oriented NativeWindow class, the Flex framework mx:WindowedApplication and mx:Window classes, which "wrap" the NativeWindow class, and, in the HTML environment, the JavaScript Window class.

ActionScript windows

When you create windows with the NativeWindow class, you use the Flash stage and display list directly. To add a visual object to a NativeWindow, you add the object to the display list of the window stage or to another display object on the stage.

Flex Framework windows

When you create windows with the Flex framework, you typically use MXML components to populate the window. To add a Flex component to a window, you add the component element to the window MXML definition. You can also use ActionScript to add content dynamically. The mx:WindowedApplication and mx:Window components are designed as Flex containers and so can accept Flex components directly whereas NativeWindow objects cannot. When necessary, NativeWindow properties and methods can be accessed through the WindowedApplication and Window objects using the stage.nativeWindow property. See About window containers for more information about these Flex components.

HTML windows

When you create HTML windows, you use HTML, CSS, and JavaScript to display content. To add a visual object to an HTML window, you add that content to the HTML DOM. HTML windows are a special category of NativeWindow. The AIR host defines a nativeWindow property in HTML windows that provides access to the underlying NativeWindow instance. You can use this property to access the NativeWindow properties, methods, and events described in this section.

The initial application window

The first window of your application is automatically created for you by AIR. AIR sets the properties and content of the window using the parameters specified in the initialWindow element of the application descriptor file.

If the root content is a SWF file, AIR creates a NativeWindow instance, loads the SWF file, and adds it to the window stage. If the root content is an HTML file, AIR creates an HTML window and loads the HTML.

For more information about the window properties specified in the application descriptor, see The application descriptor file structure.

Native Window classes

The native window API contains the following classes:

Native window event flow

Native windows dispatch events to notify interested components that an important change is about to occur or has already occurred. Many window-related events are dispatched in pairs. The first event warns that a change is about to happen. The second event announces that the change has been made. You can cancel a warning event, but not a notification event. The following sequence illustrates the flow of events that occurs when a user clicks the maximize button of a window:

1. The NativeWindow object dispatches a displayStateChanging event.
2. If no registered listeners cancel the event, the window maximizes.
3. The NativeWindow object dispatches a displayStateChange event.

   In addition, the NativeWindow object also dispatches events for related changes to the window size and position. The window does not dispatch warning events for these related changes. The related events are:

   1. A move event is dispatched if the top, left corner of the window moved because of the maximize operation.
   2. A resize event is dispatched if the window size changed because of the maximize operation.

A NativeWindow object dispatches a similar sequence of events when minimizing, restoring, closing, moving, and resizing a window.

The warning events are only dispatched when a change is initiated through window chrome or other operating-system controlled mechanism. When you call a window method to change the window size, position, or display state, the window only dispatches an event to announce the change. You can dispatch a warning event, if desired, using the window dispatchEvent() method, then check to see if your warning event has been cancelled before proceeding with the change.

For detailed information about the window API classes, methods, properties, and events, see the Flex 3 Language Reference (http://www.adobe.com/go/learn_flex3_aslr).

For general information about using the Flash display list, see the "Display Programming" section of the Programming ActionScript 3.0 (http://www.adobe.com/go/programmingAS3) reference.

Properties controlling native window style and behavior

The following properties control the basic appearance and behavior of a window:

• type
• systemChrome
• transparent

When you create a window, you set these properties on the NativeWindowInitOptions object passed to the window constructor. AIR reads the properties for the initial application window from the application descriptor. (Except the type property, which cannot be set in the application descriptor and is always set to normal.) The properties cannot be changed after window creation.

Some settings of these properties are mutually incompatible: systemChrome cannot be set to standard when either transparent is true or type is lightweight.

Window Types

The AIR window types combine chrome and visibility attributes of the native operating system to create three functional types of window. Use the constants defined in the NativeWindowType class to reference the type names in code. AIR provides the following window types:

Window chrome

Window chrome is the set of controls that allow users to manipulate a window in the desktop environment. Chrome elements include the title bar, title bar buttons, border, and resize grippers.

System chrome

You can set the systemChrome property to standard or none. Choose standard system chrome to give your window the set of standard controls created and styled by the user's operating system. Choose none to provide your own chrome for the window (or to use Flex chrome). Use the constants defined in the NativeWindowSystemChrome class to reference the system chrome settings in code.

System chrome is managed by the system. Your application has no direct access to the controls themselves, but can react to the events dispatched when the controls are used. When you use standard chrome for a window, the transparent property must be set to false and the type property must be normal or utility.

Flex chrome

When you use the Flex mx:WindowedApplication or mx:Window components, the window can be use either system chrome or chrome provided by the Flex framework. To use the Flex chrome, set the systemChrome property used to create the window to none.

Custom chrome

When you create a window with no system chrome and you do not use the Flex mx:WindowedApplication of mx:Window components, then you must add your own chrome controls to handle the interactions between a user and the window. You are also free to make transparent, non-rectangular windows.

Window transparency

To allow alpha blending of a window with the desktop or other windows, set the window transparent property to true. The transparent property must be set before the window is created and cannot be changed.

A transparent window has no default background. Any window area not occupied by a display object will be invisible. If a display object has an alpha setting of less than one, then anything below the object will show through, including other display objects in the same window, other windows, and the desktop. Rendering large alpha-blended areas can be slow, so the effect should be used conservatively.

Transparent windows are useful when you want to create applications with borders that are irregular in shape or that "fade out" or appear to be invisible.

Transparency cannot be used with windows that have system chrome.

Transparency in an MXML application window

By default, the background of an MXML window is opaque, even if you create the window as transparent. (Notice the transparency effect at the corners of the window.) To present a transparent background for the window, set a background color and alpha value in the style sheet or <mx:Style> element contained in your application MXML file. For example, the following style declaration gives the background a slightly transparent green shade:

WindowedApplication
{
    background-alpha:".8";
    background-color:"0x448234";
}

Transparency in an HTML application window

By default the background of HTML content displayed in HTML windows and HTMLLoader objects is opaque, even if the containing window is transparent. To turn off the default background displayed for HTML content, set the paintsDefaultBackground property to false. The following example creates an HTMLLoader and turns off the default background:

var html:HTMLLoader = new HTMLLoader();
html.paintsDefaultBackground = false;

This example uses JavaScript to turn off the default background of an HTML window:

window.htmlLoader.paintsDefaultBackground = false;

If an element in the HTML document sets a background color, the background of that element is not transparent. Setting a partial transparency (or opacity) value is not supported. However, you can use a transparent png-format graphic as the background for a page or a page element to achieve a similar visual effect.

A visual window catalog

The following table illustrates the visual effects of different combinations of window property settings on the Mac OS X and Windows operating systems.