Taskbar icons in AIR

You can add commands to the standard dock menu by creating a NativeMenu object containing the commands and assigning it to the NativeApplication.nativeApplication.icon.menu property. The items in the menu are displayed above the standard dock icon menu items.

You can bounce the dock icon by calling the NativeApplication.nativeApplication.icon.bounce() method. If you set the bounce() priority parameter to informational, then the icon bounces once. If you set it to critical, then the icon bounces until the user activates the application. Constants for the priority parameter are defined in the NotificationType class.

When the dock icon is clicked, the NativeApplication object dispatches an invoke event. If the application is not running, the system launches it. Otherwise, the invoke event is delivered to the running application instance.

You can add a menu to the system tray icon by creating a NativeMenu object and assigning it to the NativeApplication.nativeApplication.icon.menu property (no default menu is provided by the operating system). Access the system tray icon menu by right-clicking the icon.

Add a tooltip to an icon by setting the tooltip property:

NativeApplication.nativeApplication.icon.tooltip = "Application name"; 

The SystemTrayIcon object referenced by the NativeApplication.nativeApplication.icon property dispatches a ScreenMouseEvent for click , mouseDown , mouseUp , rightClick , rightMouseDown , and rightMouseUp events. You can use these events, along with an icon menu, to allow users to interact with your application when it has no visible windows.

The following example creates an AIR application which has a system tray icon, but no visible windows. (The visible property of the application must not be set to true in the application descriptor, or the window will be visible when the application starts up.)

package 
{ 
    import flash.display.Loader; 
    import flash.display.NativeMenu; 
    import flash.display.NativeMenuItem; 
    import flash.display.NativeWindow; 
    import flash.display.Sprite; 
    import flash.desktop.DockIcon; 
    import flash.desktop.SystemTrayIcon; 
    import flash.events.Event; 
    import flash.net.URLRequest; 
    import flash.desktop.NativeApplication; 
 
    public class SysTrayApp extends Sprite 
    { 
        public function SysTrayApp():void{ 
            NativeApplication.nativeApplication.autoExit = false; 
            var icon:Loader = new Loader(); 
            var iconMenu:NativeMenu = new NativeMenu(); 
            var exitCommand:NativeMenuItem = iconMenu.addItem(new NativeMenuItem("Exit")); 
                exitCommand.addEventListener(Event.SELECT, function(event:Event):void { 
                    NativeApplication.nativeApplication.icon.bitmaps = []; 
                    NativeApplication.nativeApplication.exit(); 
                }); 
 
            if (NativeApplication.supportsSystemTrayIcon) { 
                NativeApplication.nativeApplication.autoExit = false; 
                icon.contentLoaderInfo.addEventListener(Event.COMPLETE, iconLoadComplete); 
                icon.load(new URLRequest("icons/AIRApp_16.png")); 
                 
                var systray:SystemTrayIcon =  
                    NativeApplication.nativeApplication.icon as SystemTrayIcon; 
                systray.tooltip = "AIR application"; 
                systray.menu = iconMenu; 
            } 
 
            if (NativeApplication.supportsDockIcon){ 
                icon.contentLoaderInfo.addEventListener(Event.COMPLETE,iconLoadComplete); 
                icon.load(new URLRequest("icons/AIRApp_128.png")); 
                var dock:DockIcon = NativeApplication.nativeApplication.icon as DockIcon;  
                dock.menu = iconMenu; 
            } 
        } 
         
        private function iconLoadComplete(event:Event):void 
        { 
            NativeApplication.nativeApplication.icon.bitmaps = 
                [event.target.content.bitmapData]; 
        } 
    } 
} 

When a window is in the background, you can notify the user that an event of interest related to the window has occurred. On Mac OS X, you can notify the user by bouncing the application dock icon (as described in Bouncing the dock ). On Windows and Linux, you can highlight the window taskbar button by calling the notifyUser() method of the NativeWindow instance. The type parameter passed to the method determines the urgency of the notification:

• NotificationType.CRITICAL : the window icon flashes until the user brings the window to the foreground.

• NotificationType.INFORMATIONAL : the window icon highlights by changing color.

  Note: On Linux, only the informational type of notification is supported. Passing either type value to the notifyUser() function will create the same effect.

  The following statement highlights the taskbar button of a window:

  stage.nativeWindow.notifyUser(NotificationType.CRITICAL); 

  Calling the NativeWindow.notifyUser() method on an operating system that does not support window-level notification has no effect. Use the NativeWindow.supportsNotification property to determine if window notification is supported.

On the Windows operating system, windows created with the types utility or lightweight do not appear on the taskbar. Invisible windows do not appear on the taskbar, either.

Because the initial window is necessarily of type, normal , in order to create an application without any windows appearing in the taskbar, you must either close the initial window or leave it invisible. To close all windows in your application without terminating the application, set the autoExit property of the NativeApplication object to false before closing the last window. To simply prevent the initial window from ever becoming visible, add <visible>false</visible> to the <initalWindow> element of the application descriptor file (and do not set the visible property to true or call the activate() method of the window).

In new windows opened by the application, set the type property of the NativeWindowInitOption object passed to the window constructor to NativeWindowType.UTILITY or NativeWindowType.LIGHTWEIGHT .

On Mac OS X, windows that are minimized are displayed on the dock taskbar. You can prevent the minimized icon from being displayed by hiding the window instead of minimizing it. The following example listens for a nativeWindowDisplayState change event and cancels it if the window is being minimized. Instead the handler sets the window visible property to false :

private function preventMinimize(event:NativeWindowDisplayStateEvent):void{ 
    if(event.afterDisplayState == NativeWindowDisplayState.MINIMIZED){ 
        event.preventDefault(); 
        event.target.visible = false; 
    } 
} 

If a window is minimized on the Mac OS X dock when you set the visible property to false , the dock icon is not removed. A user can still click the icon to make the window reappear.