You use the properties and methods of the NativeWindow class to manage the appearance, behavior, and lifecycle of desktop windows.

Contents

• Getting a NativeWindow instance
• Activating, showing and hiding windows
• Maximizing, minimizing, and restoring a window
• Changing the window display order
• Closing a window
• Allowing cancellation of window operations
• Example: Minimizing, maximizing, restoring and closing a window
• Example: Resizing and moving windows

Getting a NativeWindow instance

To manipulate a window, you must first get the window instance. You can get a window instance from one of the following places:

The window constructor  

That is, the window constructor for a new NativeWindow.

The window stage  

That is, stage.nativeWindow.

Any display object on the stage 

That is, myDisplayObject.stage.nativeWindow.

A window event 

The target property of the event object references the window that dispatched the event.

The global nativeWindow property of an HTMLLoader or HTML window 

That is, window.nativeWindow.

The nativeApplication object 

NativeApplication.nativeApplication.activeWindow references the active window of an application (but returns null if the active window is not a window of this AIR application). The NativeApplication.nativeApplication.openedWindows array contains all of the windows in an AIR application that have not been closed.

Because the Flex Application, WindowedApplication, and Window objects are display objects, you can easily reference the application window in an MXML file using the stage property, as follows:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" applicationComplete="init();">
    <mx:Script>
        <![CDATA[
            import flash.display.NativeWindow;

            public function init():void{
                var appWindow:NativeWindow = this.stage.nativeWindow;
                //set window properties
                appWindow.visible = true;
            }
        ]]>
    </mx:Script>
</WindowedApplication

Activating, showing and hiding windows

To activate a window, call the NativeWindow activate() method. Activating a window will bring the window to front, give it keyboard and mouse focus, and, if necessary, make it visible by restoring the window or setting the visible property to true. Activating a window will not change the ordering of other windows in the application. Calling the activate() method will cause the window to dispatch an activate event.

To show a hidden window without activating it, set the visible property to true. This will bring the window to the front, but will not assign the focus to the window.

To hide a window from view, set its visible property to false. Hiding a window will suppress the display of both the window, any related task bar icons, and, on MacOS X, the entry in the Windows menu.

Changing the window display order

AIR provides several methods for directly changing the display order of windows. You can move a window to the front of the display order or to the back; you can move a window above another window or behind it. At the same time, the user can reorder windows by activating them.

You can keep a window in front of other windows by setting its alwaysInFront property to true. If more than one window has this setting, then the display order of these windows will be sorted amongst each other, but they will always be sorted above windows with alwaysInFront set to false. Windows in the top-most group are also displayed above windows in other applications, even when the AIR application is not active. Because this behavior can be disruptive to a user, setting alwaysInFront to true should only be done when necessary and appropriate. Examples of justified uses include:

• Temporary pop-up windows for controls such as tooltips, pop-up lists, custom menus, or comboboxes. Because these windows should close when they lose focus, the annoyance of blocking a user from viewing another window can be avoided.
• Extremely urgent error messages and alerts. When an irrevocable change may occur if the user does not respond in a timely manner, it may be justified to push an alert window to the forefront. However, most errors and alerts can be handled in the normal window display order. (Please refer to the AIR end-user license agreement (EULA) for information on AIR's suitability for time-critical applications such as aircraft and nuclear power plant control.)
• Short-lived toast-style windows.

The NativeWindow class provides the following properties and methods for setting the display order of a window relative to other windows:

Closing a window

To close a window, use the NativeWindow.close method.

Closing a window unloads the contents of the window, but if other objects have references to this content, the content objects will not be destroyed. The NativeWindow.close() method executes asynchronously, the application that is contained in the window continues to run during the closing process. The close method dispatches a close event when the close operation is complete. The NativeWindow object is still technically valid, but accessing most properties and methods on a closed window will generate an IllegalOperationError. You cannot reopen a closed window. Check the closed property of a window to test whether a window has been closed. To simply hide a window from view, set the NativeWindow.visible property to false.

If the Nativeapplication.autoExit property is true, which is the default, then the application exits when its last window closes.

Allowing cancellation of window operations

When a window uses system chrome, user interaction with the window can be canceled by listening for, and canceling the default behavior of the appropriate events. For example, when a user clicks the system chrome close button, the closing event is dispatched. If any registered listener calls the preventDefault() method of the event, then the window will not close.

When a window does not use system chrome, notification events for intended changes are not automatically dispatched before the change is made. Hence, if you call the methods for closing a window, changing the window state, or set any of the window bounds properties, the change cannot be canceled. To notify components in your application before a window change is actually made, your application logic can dispatch the relevant notification event using the dispatchEvent() method of the window.

For example, the following logic implements a cancelable event handler for a window close button:

public function onCloseCommand(event:MouseEvent):void{
    var closingEvent:Event = new Event(Event.CLOSING,true,true);
    dispatchEvent(closing);
    if(!closingEvent.isDefaultPrevented()){
        win.close();
    }
}

Note that the dispatchEvent() method returns false if the event preventDefault() method is called by a listener. However, it can also return false for other reasons, so it is better to explicitly use the isDefaultPrevented() method to test whether the change should be canceled.

Maximizing, minimizing, and restoring a window

To maximize the window, use the NativeWindow maximize() method.

myWindow.maximize();

To minimize the window, use the NativeWindow minimize() method.

myWindow.minimize();

To restore the window (that is, return it to the size that it was before it was either minimized or maximized), use the NativeWindow restore() method.

myWindow.restore();

Example: Minimizing, maximizing, restoring and closing a window

The following short MXML application demonstrates the Window maximize(), minimize(), restore(), and close() methods.

<?xml version="1.0" encoding="utf-8"?>

<mx:WindowedApplication 
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="vertical">
    
   
    <mx:Script>
    <![CDATA[
    public function minimizeWindow():void
    {
        this.stage.nativeWindow.minimize();
    }

    public function maximizeWindow():void
    {
        this.stage.nativeWindow.maximize();
    }          
    
    public function restoreWindow():void
    {
        this.stage.nativeWindow.restore();
    }          

    public function closeWindow():void
    {
        this.stage.nativeWindow.close();
    }
    ]]>
    </mx:Script>

    <mx:VBox>
        <mx:Button label="Minimize" click="minimizeWindow()"/>
        <mx:Button label="Restore" click="restoreWindow()"/>
        <mx:Button label="Maximize" click="maximizeWindow()"/>
        <mx:Button label="Close" click="closeWindow()"/>
    </mx:VBox>

</mx:WindowedApplication>

Resizing and moving a window

When a window uses system chrome, the chrome provides drag controls for resizing the window and moving around the desktop. If a window does not use system chrome you must add your own controls to allow the user to resize and move the window.

Resizing a window

To resize a window, use the NativeWindow startResize() method. When this method is called from a mouseDown event, the resizing operation is driven by the mouse and completes when the operating system receives a mouseUp event. When calling startResize(), you pass in an argument that specifies the edge or corner from which to resize the window.

The scale mode of the stage determines how the window stage and its contents will behave when a window is resized. Keep in mind that the stage scale modes are designed for situations, such as a web browser, where the application is not in control of the size or aspect ratio of its display space. In general, you will get the best results by setting the stage scaleMode property to StageScaleMode.NO_SCALE. If you want the contents of the window to scale, you can still set the scaleX and scaleY parameters in response to the window bounds changes.

Moving a window

To move a window without resizing it, use the NativeWindow startMove() method. Like the startResize() method, when the startMove() method is called from a mouseDown event, the move process is mouse-driven and completes when the operating system receives a mouseUp event.

For more information about the startResize and startMove methods, see the Flex 3 Language Reference (http://www.adobe.com/go/learn_flex3_aslr).

Example: Resizing and moving windows

The following example shows how to initiate resizing and moving operations on a window:

package
{
    import flash.display.Sprite;
    import flash.events.MouseEvent;
    import flash.display.NativeWindowResize;

    public class NativeWindowResizeExample extends Sprite
    {
        public function NativeWindowResizeExample():void
        {
            // Fills a background area.
            this.graphics.beginFill(0xFFFFFF);
            this.graphics.drawRect(0, 0, 400, 300);
            this.graphics.endFill();
            
            // Creates a square area where a mouse down will start the resize.
            var resizeHandle:Sprite = 
                createSprite(0xCCCCCC, 20, this.width - 20, this.height - 20);
            resizeHandle.addEventListener(MouseEvent.MOUSE_DOWN, onStartResize);
            
            // Creates a square area where a mouse down will start the move.
            var moveHandle:Sprite = createSprite(0xCCCCCC, 20, this.width - 20, 0);
            moveHandle.addEventListener(MouseEvent.MOUSE_DOWN, onStartMove);
        }
        
        public function createSprite(color:int, size:int, x:int, y:int):Sprite
        {
            var s:Sprite = new Sprite();
            s.graphics.beginFill(color);
            s.graphics.drawRect(0, 0, size, size);
            s.graphics.endFill();
            s.x = x;
            s.y = y;
            this.addChild(s);    
            return s;        
        }
    
        public function onStartResize(event:MouseEvent):void
        {
            this.stage.nativeWindow.startResize(NativeWindowResize.BOTTOM_RIGHT);
        }

        public function onStartMove(event:MouseEvent):void
        {
            this.stage.nativeWindow.startMove();
        }
    }
}