As we already mentioned, you create and organize a Flex AIR project the same way you would a Flex web application if you are using the Flex SDK. If you are using Flex Builder, the only difference is that you must specify that the new application is a desktop application. You can do that by selecting the “Desktop application” option in the “Application type” section of the New Flex Project dialog.

Once you’ve created a new Flex AIR project, you need to do one more thing to differentiate it from a Flex web application. Instead of defining the main application document’s root tag as Application, you must define it as WindowedApplication. That means an empty main application file for an AIR application looks like this:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
</mx:WindowedApplication>

WindowedApplication is a subclass of Application, which means everything that applies to Application also applies to WindowedApplication. However, in addition to the properties, methods, and events in the Application class, the WindowedApplication class also defines an API that is specific to AIR. For example, WindowedApplication objects have a title property, which allows you to set the text that appears in the title bar of the application window. If you look at the documentation for WindowedApplication (http://livedocs.adobe.com/flex/3/langref/mx/core/WindowedApplication.html), you’ll see that many of the properties (e.g., systemChrome, maximizable, minimizable, transparent, etc.) are read-only. Many of these properties can be set only from the application descriptor file, which you can read about in the next section.

Descriptor files are XML files that AIR applications require to determine what to run and how to run it, as well as how the .air file gets packaged and installed. For example, a descriptor file tells the AIR runtime what .swf file to run in the main window, and it can specify various settings for the main window, such as title and transparency.

The descriptor file allows you to configure a lot of settings. However, at a minimum, AIR requires that you define the following settings: application ID, name of the AIR file, version number, and content for the main (initial) window. Here is an example of a basic descriptor file:

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://ns.adobe.com/air/application/1.0">
    <id>Example</id>
    <filename>Example</filename>
    <version>1.0</version>
    <initialWindow>
        <content>Main.swf</content>
    </initialWindow>
</application>

Many of the additional settings apply to the initialWindow tag, within which you can nest additional elements for those settings. For example, you can add x and y elements to set the initial x and y coordinates of the main window.

You can read about all the descriptor file settings at http://livedocs.adobe.com/flex/3/html/help.html?content=File_formats_1.html#1043413.

If you are using Flex Builder, when you create a new desktop application project, Flex Builder will automatically create a descriptor file for you. The descriptor file will be placed alongside the main MXML file, and it will be named <ProjectName>-app.xml where <ProjectName> is the name of the Flex project.

If you’re using the Flex SDK, you must create the descriptor file yourself. The file should be a UTF-8-encoded XML file. You do not have to use a specific name for the file.

Compiling and testing AIR applications is extraordinarily simple if you are using Flex Builder. In fact, all you need to do is run the application as you would for any Flex application, and Flex Builder will take care of compiling for AIR and running the application in the debug launcher. Therefore, if you are using Flex Builder, you can skip the remainder of this section and jump to Working with AIR Features.”

If you are using the Flex SDK, compiling and testing AIR applications is not difficult, but it is a little more involved than compiling and testing using Flex Builder. To compile an AIR application using the SDK you must run the standard Flex compiler (mxmlc) using the additional +configname=air parameter. Optionally, you can use the amxmlc compiler instead, which is a shortcut that automatically adds the +configname=air parameter. For the examples in this section, we’ll use amxmlc.

At a minimum, the compiler requires a main MXML file. In the simplest format, the following command will compile Main.mxml into an AIR .swf:

amxmlc Main.mxml

When you compile an AIR application, the compiler options are identical to those you use when compiling a web application. You can refer back to Chapter 2 for more information about these options.