20100220 (Air Study)

However, unlike other MXML components, a Window-based component cannot be used in another MXML document. Instead, you create an instance of the MXML component in ActionScript.

Once the window's initial properties are set, you call the Window component's open() method to cause the operating system window to appear on the user's display.

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.

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.

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

Window Types

Normal
 A typical window. Normal windows use the full-size style of chrome and appear on the Windows task bar and the Mac OS X window menu.
 
 
Utility
 A tool palette. Utility windows use a slimmer version of the system chrome and do not appear on the Windows task bar and the Mac OS-X window menu.
 
 
Lightweight
 Lightweight windows have no chrome and do not appear on the Windows task bar or the Mac OS X window menu. In addition, lightweight windows do not have the System (Alt+Space) menu on Windows. Lightweight windows are suitable for notification bubbles and controls such as combo-boxes that open a short-lived display area. When the lightweight type is used, systemChrome must be set to none.

 
The desktop window is not created until you call the window open() method. Once a window is opened, these initialization properties cannot be changed.

Native window: 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.

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.

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.

Setting the displayState property of the Stage to StageDisplayState.FULL_SCREEN_INTERACTIVE puts the window in full-screen mode, and keyboard input is permitted in this mode. (In SWF content running in a browser, keyboard input is not permitted). To exit full-screen mode, the user presses the Escape key.

Window menus
A window menu is associated with a single window and is displayed below the title bar.

Context menus
Context menus open in response to a right-click or command-click on an interactive object in SWF content or a document element in HTML content.

Dock and system tray icon menus
These icon menus are similar to context menus and are assigned to an application icon in the Mac OS X dock or Windows notification area.

Pop-up menus
An AIR pop-up menu is like a context menu, but is not necessarily associated with a particular application object or component.

Flex menus
The Flex framework provides a set of Flex menu components. The Flex menus are drawn by the AIR runtime rather than the operating system and are not native menus. A Flex menu component can be used for Flex windows that do not have system chrome.

Menus are hierarchical in nature. NativeMenu objects contain child NativeMenuItem objects. NativeMenuItem objects that represent submenus, in turn, can contain NativeMenu objects. The top- or root-level menu object in the structure represents the menu bar for application and window menus. (Context, icon, and pop-up menus don't have a menu bar).

NativeMenu and NativeMenuItem objects both dispatch displaying and select events:

Displaying:
Immediately before a menu is displayed, the menu and its menu items will dispatch a displaying event to any registered listeners. The displaying event gives you an opportunity to update the menu contents or item appearance before it is shown to the user.

Select: 
When a command item is chosen by the user, the item will dispatch a select event to any registered listeners. Submenu and separator items cannot be selected and so never dispatch a select event.

You can assign a key equivalent (sometimes called an accelerator) to a menu command. The menu item will dispatch a select event to any registered listeners when the key, or key combination is pressed. The menu containing the item must be part of the menu of the application or the active window for the command to be invoked.

Key equivalents have two parts, a string representing the primary key and an array of modifier keys that must also be pressed. To assign the primary key, set the menu item keyEquivalent property to the single character string for that key. If you use an uppercase letter, the shift key is added to the modifier array automatically.

To assign different modifier keys, assign a new array containing the desired key codes to the keyEquivalentModifiers property. The default array is overwritten. Whether or not you use the default modifiers or assign your own modifier array, the shift key is added if the string you assign to the keyEquivalent property is an uppercase letter.

Menu items have the two state properties, checked and enabled:
checked
Set to true to display a check mark next to the item label.
enabled
Toggle the value between true and false to control whether the command is enabled. Disabled items are visually "grayed-out" and do not dispatch select events.
The data property of the NativeMenuItem class allows you to reference an arbitrary object in each item.

Setting a window menu
nativeWindowObject.menu = root;

Setting a context menu on an interactive object
interactiveObject.contextMenu = root;

Setting a dock icon menu
DockIcon(NativeApplication.nativeApplication.icon).menu = root;

Setting a system tray icon menu
SystemTrayIcon(NativeApplication.nativeApplication.icon).menu = root;

Displaying a menu as a pop-up
root.display(stage, x, y);

To create a separator line, create a NativeMenuItem, setting the isSeparator parameter to true in the constructor. Then add the separator item to the menu in the correct location:
var separatorA:NativeMenuItem = new NativeMenuItem("A", true);
editMenu.addItem(separatorA);

If you provide more than one image, AIR selects the size closest to the current display size of the taskbar icon, scaling it only if necessary.
To change the icon image, assign an array containing the new image or images to the bitmaps property. You can animate the icon by changing the image in response to an enterFrame or timer event.
To remove the icon from the notification area on Windows, or restore the default icon appearance on Mac OS X, set bitmaps to an empty array.

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.

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.

On Windows, you can highlight the window taskbar button by calling the notifyUser() method of the NativeWindow instance.
NotificationType.CRITICAL: the window icon flashes until the user brings the window to the foreground.
NotificationType.INFORMATIONAL: the window icon highlights by changing color.

File
 File object represents a path to a file or directory. You use a file object to create a pointer to a file or folder, initiating interaction with the file or folder.
 
 
FileMode
 The FileMode class defines string constants used in the fileMode parameter of the open() and openAsync() methods of the FileStream class. The fileMode parameter of these methods determines the capabilities available to the FileStream object once the file is opened, which include writing, reading, appending, and updating.
 
 
FileStream
 FileStream object is used to open files for reading and writing. Once you've created a File object that points to a new or existing file, you pass that pointer to the FileStream object so that you can open and then manipulate data within the file.
 
 
1.Locate the following files, provided in the samples/badge directory of the Flex SDK, and add them to your web server.
badge.swf
default_badge.html
AC_RunActiveContent.js
2.Open the default_badge.html page in a text editor.
3.In the default_badge.html page, in the AC_FL_RunContent() JavaScript function, adjust the FlashVars parameter definitions for the following:Parameter
 Description
appname  The name of the application, displayed by the SWF file when the runtime is not installed.
appurl  (Required). The URL of the AIR file to be downloaded. You must use an absolute, not relative, URL.
airversion  (Required). For the 1.0 version of the AIR runtime, set this to 1.0.
imageurl  The URL of the image (optional) to display in the badge.
buttoncolor  The color of the download button (specified as a hex value, such as FFCC00).
messagecolor  The color of the text message displayed below the button when the runtime is not installed (specified as a hex value, such as FFCC00).
4.The minimum size of the badge.swf file is 217 pixels wide by 180 pixels high. Adjust the values of the width and height parameters of the AC_FL_RunContent() function to suit your needs.
5.Rename the default_badge.html file and adjust its code (or include it in another HTML page) to suit your needs.

badge.fla
 The source Flash CS3 file used to compile the badge.swf file. The badge.fla file compiles into a SWF 9 file (which can be loaded in Flash Player ).
AIRBadge.as
 An ActionScript 3.0 class that defines the base class used in the basdge.fla file.
You can use Flash CS3 to redesign the visual interface of the badge.fla file.

Loading the air.swf file
var airSWF:Object; // This will be the reference to the main class of air.swf
var airSWFLoader:Loader = new Loader(); // Used to load the SWF
var loaderContext:LoaderContext = new LoaderContext();
// Used to set the application domain domain
loaderContext.applicationDomain = ApplicationDomain.currentDomain;
airSWFLoader.contentLoaderInfo.addEventListener(Event.INIT, onInit);
airSWFLoader.load(new URLRequest("http://airdownload.adobe.com/browserapi/air.swf"), loaderContext);
function onInit(e:Event):void
{
    airSWF = e.target.content;
}

With air.swf, you can:
Checking if the AIR runtime is installed - airSWF.getStatus();
Checking from a web page if an AIR application is installed - airSWF.getApplicationVersion(appID, pubID, versionDetectCallback);
Installing an AIR application from the browser - airSWF.installApplication(url, runtimeVersion, arguments);
Launching an installed AIR application from the browser - airSWF.launchApplication(appID, pubID, arguments);

To receive invoke events call the addEventListener() method of the NativeApplication object (NativeApplication.nativeApplication). When an event listener registers for an invoke event, it will also receive all invoke events that occurred before the registration. Queued invoke events are dispatched one at a time on a short interval after the call to addEventListener() returns.

Only one instance of an AIR application is started. When an already running application is invoked again, AIR dispatches a new invoke event to the running instance.

An AIR application can be set to launch automatically when the current user logs in by setting NativeApplication.nativeApplication.startAtLogin=true.

When the application is invoked via the browser, the application's NativeApplication object dispatches a BrowserInvokeEvent object.
Keep in mind that if you add an event listener later in execution (after application initialization) it will still receive all BrowserInvokeEvent events that have occurred since the application started.
If you expect only a specific web site to invoke the application, the application should check the securityDomain property of the BrowserInvokeEvent object.

The quickest way to terminate an application is to call NativeApplication.nativeApplication.exit() and this works fine when your application has no data to save or resources to clean up.

To provide consistent behavior on all platforms, whether the exit sequence is initiated via operating system chrome, menu commands, or application logic, observe the following good practices for exiting the application:
1.Always dispatch an exiting event through the NativeApplication object before calling exit() in application code and check that another component of your application doesn't cancel the event.public function applicationExit():void {
    var exitingEvent:Event = new Event(Event.EXITING, false, true);
    NativeApplication.nativeApplication.dispatchEvent(exitingEvent);
    if (!exitingEvent.isDefaultPrevented()) {
        NativeApplication.nativeApplication.exit();
    }
}
2.Listen for the application exiting event from the NativeApplication.nativeApplication object and, in the handler, close any windows (dispatching a closing event first).
private function onExiting(exitingEvent:Event):void {
    var winClosingEvent:Event;
    for each (var win:NativeWindow in NativeApplication.nativeApplication.openedWindows) {
        winClosingEvent = new Event(Event.CLOSING,false,true);
        win.dispatchEvent(winClosingEvent);
        if (!winClosingEvent.isDefaultPrevented()) {
            win.close();
        } else {
            exitingEvent.preventDefault();
        }
    }
    if (!exitingEvent.isDefaultPrevented()) {
        //perform cleanup
    }
}
3.Windows should always handle their own clean up by listening for their own closing event.
4.Only one exiting listener should be used in your application since handlers called earlier cannot know whether subsequent handlers will cancel the exiting event (and it would be unwise to rely on the order of execution).

Reading the application descriptor file
var appXml:XML = NativeApplication.nativeApplication.applicationDescriptor;
Getting the application and publisher identifiers
trace(NativeApplication.nativeApplication.applicationID);
trace(NativeApplication.nativeApplication.publisherID);
As part of the process of building an AIR file, the AIR Developer Tool (ADT) generates a publisher ID. This is an identifier that is unique to the certificate used to build the AIR file. If you reuse the same certificate for multiple AIR applications, they will have the same publisher ID.

Managing file associations
AIR can only manage associations for the file types originally declared in the application descriptor. You cannot get information about the associations of a non-declared file type.
isSetAsDefaultApplication()
 Returns true if the AIR application is currently associated with the specified file type.
setAsDefaultApplication()
 Creates the association between the AIR application and the open action of the file type.
removeAsDefaultApplication()
 Removes the association between the AIR application and the file type.
getDefaultApplication()
 Reports the path of the application that is currently associated with the file type.
 
 
Getting the runtime version and patch level
trace(NativeApplication.nativeApplication.runtimeVersion);
trace(NativeApplication.nativeApplication.runtimePatchLevel);

The NativeApplication object dispatches two events that help you detect when a user is actively using a computer. If no mouse or keyboard activity is detected in the interval determined by the NativeApplication.idleThreshold property, the NativeApplication dispatches a userIdle event. When the next keyboard or mouse input occurs, the NativeApplication object dispatches a userPresent event. The idleThreshold interval is measured in seconds and has a default value of 300 (5 minutes). You can also get the number of seconds since the last user input from the NativeApplication.nativeApplication.lastUserInput property.

The LocalConnection class enables communications between AIR applications, as well as among AIR applications and SWF content running in the browser.

By default, the connectionName argument is resolved into a value of "superdomain:connectionName", where superdomain is the superdomain of the file that contains the connect() command. For example, if the file that contains the receiving LocalConnection object is located at www.someDomain.com, connectionName resolves to "someDomain.com:connectionName".

In content running in the application security sandbox in Adobe AIR (content installed with the AIR application), the runtime uses the string app# followed by the application ID for the AIR application (defined in the application descriptor file) in place of the superdomain. For example a connectionName for an application with the application ID com.example.air.MyApp connectionName resolves to "app#com.example.air.MyApp:connectionName".

If the string for connectionNamedoes not begin with an underscore (_), a prefix is added with the superdomain and a colon (for example, "myDomain:connectionName").

If the string for connectionNamebegins with an underscore (for example, "_connectionName"), a prefix is not added to the string. This means that the receiving and sending LocalConnection objects use identical strings for connectionName.

You cannot specify a superdomain in connectionName in the receiving LocalConnection object — you can do this in only the sending LocalConnection object.