Creating your first AIR application with the Flex SDK

For a quick, hands-on illustration of how AIR works, use these instructions to create a simple SWF-based AIR "Hello World" application using the Flex SDK. You will learn how to compile, test, and package an AIR application with the command-line tools provided with the SDK.

To begin, you must have installed the runtime and set up the Flex 3. You will use the AMXMLC compiler, the AIR Debug Launcher (ADL), and the AIR Developer Tool (ADT) in this tutorial. These programs can be found in the bin directory of the Flex 3 SDK (see Setting up the Flex 3 SDK).

Contents

Create the AIR application descriptor file

This section describes how to create the application descriptor, which is an XML file with the following structure:

<application>
    <id>...</id>
    <version>...</version>
    <filename>�?�</filename>
    <initialWindow>
        <content>�?�</content>
        <visible>�?�</visible>
        <systemChrome>�?�</systemChrome>
        <transparent>�?�</transparent>
        <width>�?�</width>
        <height>�?�</height>
    </initialWindow>
</application>

Create an XML file named HelloWorld-app.xml and save it in the project directory.
Add the <application> element, including the AIR namespace attribute:
<application xmlns="http://ns.adobe.com/air/application/1.0"> The last segment of the namespace, "1.0," specifies the version of the runtime required by the application.
Add the <id> element:
<id>samples.flex.HelloWorld</id> The application ID uniquely identifies your application along with the publisher ID (which AIR derives from the certificate used to sign the application package). The recommended form is a dot-delimited, reverse-DNS-style string, such as "com.company.AppName". The application ID is used for installation, access to the private application file-system storage directory, access to private encrypted storage, and interapplication communication.
Add the <version> element:
<version>0.1</version> Helps users to determine which version of your application they are installing.
Add the <filename> element:
<filename>HelloWorld</filename> The name used for the application executable, install directory, and similar for references in the operating system.
Add the <initialWindow> element containing the following child elements to specify the properties for your initial application window:
<content>HelloWorld.swf</content> Identifies the root HTML file for AIR to load.

<visible>true</visible> Makes the window visible immediately.

<width>400</width> Sets the window width (in pixels).

<height>200</height> Sets the window height.

Save the file. Your complete application descriptor file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://ns.adobe.com/air/application/1.0">
    <id>samples.flex.HelloWorld</id>
    <version>0.1</version>
    <filename>HelloWorld</filename>
    <initialWindow>
        <content>HelloWorld.swf</content>
        <visible>true</visible>
        <systemChrome>none</systemChrome>
        <transparent>true</transparent>
        <width>400</width>
        <height>200</height>
    </initialWindow>
</application>

This example only sets a few of the possible application properties. For the full set of application properties, which allow you to specify such things as window chrome, window size, transparency, default installation directory, associated file types, and application icons, see Setting AIR application properties

Write the application code

Note: SWF-based AIR applications can use a main class defined either with MXML or with ActionScript. This example uses an MXML file to define its main class. The process for creating an AIR application with a main ActionScript class is similar. Instead of compiling an MXML file into the SWF, you compile the ActionScript class file. When using ActionScript, the main class must extend flash.display.Sprite.

Like all Flex applications, AIR applications built with the Flex framework contain a main MXML file. AIR applications, however, use the WindowedApplication component as the root element instead of the Application component. The WindowedApplication component provides properties, methods, and events for controlling your application and its initial window.

The following procedure creates the Hello World application.

Using a text editor, create a file named HelloWorld.mxml and add the following MXML code:

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

Next, add a Label component to the application (place it inside the WindowedApplication tag).
Set the text property of the Label component to "Hello AIR".

Set the layout constraints to always keep it centered.

The following example shows the code so far:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"
    title="Hello World">
        <mx:Label text="Hello World" horizontalCenter="0" verticalCenter="0"/>
</mx:WindowedApplication>

Add the following style block:
```
<mx:Style>
    WindowedApplication
    {
        background-color:"0x999999";
        background-alpha:"0.5";
    }
</mx:Style>
```
These styles apply to the entire application and set the window background to be a slightly transparent gray.

The entire application code now looks like the following:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" title="Hello World">
    <mx:Style>
        WindowedApplication
        {
            background-color:"0x999999";
            background-alpha:"0.5";
        }
    </mx:Style>
    <mx:Label text="Hello World" horizontalCenter="0" verticalCenter="0"/>
</mx:WindowedApplication>

Compile the application

Before you can run and debug the application, you must compile the MXML code into a SWF file using the amxmlc compiler. The amxmlc compiler can be found in the bin directory of the Flex 3 SDK. If desired, you can set the path environment of your computer to include the Flex 3 SDK bin directory to make it easier to run the utilities on the command line.

Open a command shell or a terminal and navigate to the project folder of your AIR application.
Enter the following command:
```
amxmlc HelloWorld.mxml 
```

Running amxmlc produces HelloWorld.swf, which contains the compiled code of the application.

Note: If the application does not compile, fix syntax or spelling errors. Errors and warnings are displayed in the console window used to run the amxmlc compiler.

For more information, see Compiling an AIR application with the amxmlc compiler.

Test the application

To run and test the application from the command line, use the AIR Debug Launcher (ADL) to launch the application using its application descriptor file. (ADL can be found in the bin directory of the Flex 3 SDK.)

From the command prompt, enter the following command:

adl HelloWorld-app.xml

The resulting AIR application looks something like this (the green background is the user's desktop):

Using the horizontalCenter and verticalCenter properties of the Label control, the text is placed in the center of the window. Move or resize the window as you would any other desktop application.

For more information, see Using the AIR Debug Launcher (ADL).

Create the AIR installation file

When your application runs successfully, you can use the ADT utility to package the application into an AIR installation file. An AIR installation file is an archive file that contains all the application files, which you can distribute to your users. You must install the Adobe AIR runtime before installing a packaged AIR file.

To ensure application security, all AIR installation files must be digitally signed. For development purposes, you can generate a basic, self-signed certificate with ADT or another certificate generation tool. You can also buy a commercial code-signing certificate from a commercial certificate authority such as VeriSign or Thawte. When users install a self-signed AIR file, the publisher is displayed as "unknown" during the installation process. This is because a self-signed certificate only guarantees that the AIR file has not been changed since it was created. There is nothing to prevent someone from self-signing a masquerade AIR file and presenting it as your application. For publicly released AIR files, a verifiable, commercial certificate is strongly recommended. For an overview of AIR security issues, see AIR security.

Generating a self-signed certificate and key pair

From the command prompt, enter the following command (the ADT executable can be found in the bin directory of the Flex 3 SDK):

adt -certificate -cn SelfSigned 1024-RSA sampleCert.pfx samplePassword

This example uses the minimum number of attributes that can be set for a certificate. You can use any values for the parameters in italics. The key type must be either 1024-RSA or 2048-RSA (see Digitally signing an AIR file).

Creating the AIR installation file

From the command prompt, enter the following command (on a single line):

adt -package -storetype pkcs12 -keystore sampleCert.pfx HelloWorld.air 
HelloWorld-app.xml HelloWorld.swf

You will be prompted for the keystore file password.

The HelloWorld.air argument is the AIR file that ADT produces. HelloWorld-app.xml is the application descriptor file. The subsequent arguments are the files used by your application. This example only uses three files, but you can include any number of files and directories.

After the AIR package is created, you can install and run the application by double-clicking the package file. You can also type the AIR filename as a command in a shell or command window.

See also