Managing windows



You use the properties and methods of the NativeWindow class to manage the appearance, behavior, and life cycle of desktop 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 native window constructor used to create the window:

    var nativeWin = new air.NativeWindow(initOptions);
  • The stage property of a display object in the window:

    var nativeWin = window.htmlLoader.stage.nativeWindow;
  • The target property of a native window event dispatched by the window:

    function onNativeWindowEvent(event) 
    { 
        var nativeWin = event.target; 
    }
  • The nativeWindow property of an HTML page displayed in the window:

    var nativeWin = window.nativeWindow;
  • The activeWindow and openedWindows properties of the NativeApplication object:

    var win = NativeApplication.nativeApplication.activeWindow; 
    var firstWindow = NativeApplication.nativeApplication.openedWindows[0];

    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.

Activating, showing, and hiding windows

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

To show a hidden window without activating it, set the visible property to true. This brings 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 suppresses the display of both the window, any related taskbar icons, and, on Mac OS X, the entry in the Windows menu.

Note: On Mac OS X, it is not possible to completely hide a minimized window that has an icon in the window portion of the dock. If the visible property is set to false on a minimized window, the dock icon for the window is still displayed. If the user clicks the icon, the window is restored to a visible state and displayed.

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 is sorted among each other, but they are always sorted above windows which have 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 tool tips, pop-up lists, custom menus, or combo boxes. 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.

  • Short-lived toast-style windows.

Note: AIR does not enforce proper use of the alwaysInFront property. However, if your application disrupts a user’s workflow, it is likely to be consigned to that same user’s trash can.

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

Member

Description

alwaysInFront property

Specifies whether the window is displayed in the top-most group of windows.

In almost all cases, false is the best setting. Changing the value from false to true brings the window to the front of all windows (but does not activate it). Changing the value from true to false orders the window behind windows remaining in the top-most group, but still in front of other windows. Setting the property to its current value for a window does not change the window display order.

orderToFront()

Brings the window to the front.

orderInFrontOf()

Brings the window directly in front of a particular window.

orderToBack()

Sends the window behind other windows.

orderBehind()

Sends the window directly behind a particular window.

activate()

Brings the window to the front (along with making the window visible and assigning focus).

Note: If a window is hidden (visible is false) or minimized, then calling the display order methods has no effect.

On the Linux operating system, different window managers enforce different rules regarding the window display order:

  • On some window managers, utility windows are always displayed in front of normal windows.

  • On some window managers, a full screen window with alwaysInFront set to true is always displayed in front of other windows that also have alwaysInFront set to true.

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 generates 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 does 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 made, your application logic can dispatch the relevant notification event using the dispatchEvent() method of the window.

function onCloseCommand(event){ 
    var closingEvent = new air.Event(air.Event.CLOSING,true,true); 
    dispatchEvent(closingEvent); 
    if(!closingEvent.isDefaultPrevented()){ 
        win.close(); 
    } 
}

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.

window.nativeWindow.maximize();

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

 
window.nativeWindow.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.

 
window.nativeWindow.restore();
Note: The behavior that results from maximizing an AIR window is different from the Mac OS X standard behavior. Rather than toggling between an application-defined “standard” size and the last size set by the user, AIR windows toggle between the size last set by the application or user and the full usable area of the screen.

On the Linux operating system, different window managers enforce different rules regarding setting the window display state:

  • On some window managers, utility windows cannot be maximized.

  • If a maximum size is set for the window, then some windows do not allow a window to be maximized. Some other window managers set the display state to maximized, but do not resize the window. In either of these cases, no display state change event is dispatched.

  • Some window managers do not honor the window maximizable or minimizable settings.

Note: On Linux, window properties are changed asynchronously. If you change the display state in one line of your program, and read the value in the next, the value read will still reflect the old setting. On all platforms, the NativeWindow object dispatches the displayStateChange event when the display state changes. If you need to take some action based on the new state of the window, always do so in a displayStateChange event handler. See Listening for window events.

Example: Minimizing, maximizing, restoring and closing a window

The following short HTML page demonstrates the NativeWindow maximize(), minimize(), restore(), and close() methods:

<html> 
<head> 
<title>Change Window Display State</title> 
<script src="AIRAliases.js"/> 
<script type="text/javascript"> 
     function onMaximize(){ 
         window.nativeWindow.maximize(); 
     } 
     
     function onMinimize(){ 
         window.nativeWindow.minimize(); 
     } 
     
     function onRestore(){ 
         window.nativeWindow.restore(); 
     } 
     
     function onClose(){ 
         window.nativeWindow.close(); 
     } 
</script> 
</head> 
 
<body> 
     <h1>AIR window display state commands</h1> 
         <button onClick="onMaximize()">Maximize</button> 
         <button onClick="onMinimize()">Minimize</button> 
         <button onClick="onRestore()">Restore</button> 
    <button onClick="onClose()">Close</button> 
</body> 
</html>

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.

Note: To resize or move a window, you must first obtain a reference to the NativeWindow instance. For information about how to obtain a window reference, see Getting a NativeWindow instance.

Resizing a window

To allow a user to resize a window interactively, 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.

To set the window size programmatically, set the width, height, or bounds properties of the window to the desired dimensions. When you set the bounds, the window size and position can all be changed at the same time. However, the order that the changes occur is not guaranteed. Some Linux window managers do not allow windows to extend outside the bounds of the desktop screen. In these cases, the final window size may be limited because of the order in which the properties are set, even though the net affect of the changes would otherwise have resulted in a legal window. For example, if you change both the height and y position of a window near the bottom of the screen, then the full height change might not occur when the height change is applied before the y position change.

Note: On Linux, window properties are changed asynchronously. If you resize a window in one line of your program, and read the dimensions in the next, they will still reflect the old settings. On all platforms, the NativeWindow object dispatches the resize event when the window resizes. If you need to take some action, such as laying out controls in the window, based on the new size or state of the window, always do so in a resize event handler. See Listening for window events.

Moving a window

To move a window without resizing it, use theNativeWindow 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 Adobe AIR Language Reference for HTML Developers (http://www.adobe.com/go/learn_air_html_jslr).

To move a window programmatically, set the x, y, or bounds properties of the window to the desired position. When you set the bounds, the window size and position can both be changed at the same time.

Note: On Linux, window properties are changed asynchronously. If you move a window in one line of your program, and read the position in the next, the value read will still reflect the old setting. On all platforms, the NativeWindow object dispatches the move event when the position changes. If you need to take some action based on the new position of the window, always do so in a move event handler. See Listening for window events.

Example: Resizing and moving windows

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

<html xmlns="http://www.w3.org/1999/xhtml"> 
<head> 
<script src="AIRAliases.js"/> 
<script type="text/javascript"> 
     function onResize(type){ 
         nativeWindow.startResize(type); 
     } 
     
     function onNativeMove(){ 
         nativeWindow.startMove(); 
     } 
</script> 
<style type="text/css" media="screen"> 
 
.drag { 
    width:200px; 
    height:200px; 
    margin:0px auto; 
    padding:15px; 
    border:1px dashed #333; 
    background-color:#eee; 
    } 
 
.resize { 
    background-color:#FF0000; 
    padding:10px; 
    } 
.left { 
        float:left; 
        }     
.right { 
    float:right; 
}     
 
</style> 
<title>Move and Resize the Window</title> 
</head> 
 
<body> 
<div class="resize left" onmousedown="onResize(air.NativeWindowResize.TOP_LEFT)">Drag to resize</div> 
<div class="resize right" onmousedown="onResize(air.NativeWindowResize.TOP_RIGHT)">Drag to resize</div> 
<div class="drag" onmousedown="onNativeMove()">Drag to move</div> 
<div class="resize left" onmousedown="onResize(air.NativeWindowResize.BOTTOM_LEFT)">Drag to resize</div> 
<div class="resize right" onmousedown="onResize(air.NativeWindowResize.BOTTOM_RIGHT)">Drag to resize</div> 
</body> 
</html>