Aside from all the files and other assets that make up your Adobe AIR applications, an AIR application requires an application descriptor--an XML file which defines the basic properties of the application.

When you use Flex Builder 3, the application descriptor file is automatically generated when you create an AIR project. If you're developing AIR applications using the Flex 3 or AIR SDKs, you must create this file manually. A sample descriptor file, descriptor-sample.xml, can be found in the samples directory of your SDK installation.

Contents

• The application descriptor file structure
• Defining properties in the application descriptor file

The application descriptor file structure

The application descriptor file contains the properties that affect the entire application, such as its name, version, copyright, and so on. Any file name can be used for the application descriptor file. When you package the application with either Flex Builder or ADT, the application descriptor file is renamed application.xml and placed within a special directory inside the package.

Here's an example application descriptor file:

<?xml version="1.0" encoding="utf-8" ?>
<application xmlns="http://ns.adobe.com/air/application/1.0.M6"
    minimumPatchLevel="1047">
    <id>com.example.HelloWorld</id>
    <version>2.0</version>
    <filename>Hello World</filename>
    <name>Example Co. AIR Hello World</name>
    <description>
        The Hello World sample file from the Adobe AIR documentation.
    </description>
    <copyright>Copyright ｩ 2006 Example Co.</copyright>
    <initialWindow>
        <title>Hello World</title>
        <content>
            HelloWorld-debug.swf
        </content>
        <systemChrome>none</systemChrome>
        <transparent>true</transparent>
        <visible>true</visible>
        <minimizable>true</minimizable>
        <maximizable>false</maximizable>
        <resizable>false</resizable>
        <width>640</width>
        <height>480</height>
        <minSize>320 240</minSize>
        <maxSize>1280 960</maxSize>
    </initialWindow> 
    <installFolder>Example Co/Hello World</installFolder>
    <programMenuFolder>Example Co</programMenuFolder>
    <icon>
        <image16x16>icons/smallIcon.png</image16x16>
        <image32x32>icons/mediumIcon.png</image32x32>
        <image48x48>icons/bigIcon.png</image48x48>
        <image128x128>icons/biggestIcon.png</image128x128> 
    </icon>
    <customUpdateUI>true</customUpdateUI>
    <allowBrowserInvocation>false</allowBrowserInvocation>
    <fileTypes>
        <fileType>
            <name>adobe.VideoFile</name>
            <extension>avf</extension>
            <description>Adobe Video File</description>
            <contentType>application/vnd.adobe.video-file</contentType>
            <icon>
                <image16x16>icons/avfIcon_16.png</image16x16>
                <image32x32>icons/avfIcon_32.png</image32x32>
                <image48x48>icons/avfIcon_48.png</image48x48>
                <image128x128>icons/avfIcon_128.png</image128x128>
            </icon>
        </fileType>
    </fileTypes>
</application>

Defining properties in the application descriptor file

At its root, the application descriptor file contains an application property that has several attributes:

<application version="1.0"
    xmlns="http://ns.adobe.com/air/application/1.0.M6"
    minimumPatchLevel="5331">

xmlns The AIR namespace, which you must define as the default XML namespace. The namespace will change with each major release of AIR (but not with minor patches). The last segment of the namespace, such as "1.0" indicates the AIR runtime version required by the application.

minimumPatchLevel Together with the AIR namespace, this property determines the version of the AIR runtime required by the application. The application installer prompts the user to download and install the required version or patch, if necessary.

Defining the basic application information

The following elements define application ID, version, name, file name, description, and copyright information:

<id>com.example.samples.TestApp</id>
<version>2.0</version>
<filename>TestApp</filename>
<name>Example Co. Test Application</name>
<description>An MP3 player.</description>
<copyright>Copyright ｩ 2006 [YourCompany, Inc.]</copyright>

id An identifier string unique to the application, known as the application ID. The attribute value is restricted to the following characters:

• 0-9
• a-z
• A-Z
• . (dot)
• - (hyphen)

The value must contain between 1 to 212 characters. This element is required.

The id string typically uses a dot-separated hierarchy, in alignment with a reversed DNS domain address, a Java package or class name, or an OS X Universal Type Identifier. The DNS-like form is not enforced, and AIR does not create any association between the name and actual DNS domains.

version Specifies the version information for the application. (It has no relation to the version of the runtime). The version string is an application-defined designator. AIR does not interpret the version string in any way. Thus version "3.0" is not assumed to be more current than version "2.0." Examples: "1.0", ".4", "0.5", "4.9", "1.3.4a". This element is required.

filename The string to use as a filename of the application (without extension) when the application is installed. The application file launches the AIR application in the AIR runtime. If no name value if provided, the filename s also used as the name of the installation folder. This element is required.

The filename property can contain any Unicode (UTF-8) character except the following, which are prohibited from use as filenames on various file systems:

The filename value cannot end in a period.

name (Optional, but recommended) The title displayed by the AIR application installer. If provided, the name value is also used as the name of the installation folder (within the folder specified in the installFolder element).

description (Optional) Displayed in the AIR application installer.

copyright (Optional) The copyright information for the AIR application. On Mac OS, the copyright text appears in the About dialog box for the installed application, and it is used in the NSHumanReadableCopyright field in the Info.plist file for the application.

Defining the installation folder and program menu folder

The installation and program menu folders are defined with the following property settings:

<installFolder>Acme</installFolder>
<programMenuFolder>Acme/Applications</programMenuFolder>

installFolder (Optional) Identifies the subdirectory of the default installation directory.

On Windows, the default installation subdirectory is the Program Files directory. On Mac OS, it is the /Applications directory. For example, if the installFolder property is set to "Acme" and an application is named "ExampleApp", then the application will be installed in C:\Program Files\Acme\ExampleApp on Windows and in /Applications/Acme/Example.app on MacOS.

Use the forward-slash (/) character as the directory separator character if you want to specify a nested subdirectory, as in the following:

<installFolder>Acme/Power Tools</installFolder>

The installFolder property can contain any Unicode (UTF-8) character except the following, which are prohibited from use as folder names on various file systems (see the filename property above for the list of exceptions).

The installFolder property is optional. If you specify no installFolder property, the application is installed in a subdirectory of the default installation directory, based on the name property.

programMenuFolder (Optional) Identifies the location in which to place shortcuts to the application in the All Programs menu of the Windows operating system. (This setting is currently ignored on other operating systems.) The restrictions on the characters that are allowed in the value of the property are the same as those for the installFolder property.

Defining the properties of the initial application window

When an AIR application is loaded, the runtime uses the values in the initialWindow element to create the initial window for the application. The runtime then loads the SWF or HTML file specified in the content element into the window.

<initialWindow>
    <content>AIRTunes.swf</content>
    <title>AIR Tunes</title>
    <systemChrome>none</systemChrome>
    <transparent>true</transparent>
    <visible>true</visible>
    <minimizable>true</minimizable>
    <maximizable>true</maximizable>
    <resizable>true</resizable>
    <width>400</width>
    <height>600</height>
    <x>150</x>
    <y>150</y>
    <minSize>300 300</minSize>
    <maxSize>800 800</maxSize>
</initialWindow>

The child elements of the initialWindow element set the properties of the window into which the root content file is loaded.

content The value specified for the content element is the URL for the main content file of the application. This may be either a SWF file or an HTML file. The URL is specified relative to the root of the application installation folder. (When running an AIR application with ADL, the URL is relative to the folder containing the application descriptor file. You can use the root-dir parameter of ADL to specify a different root directory.)

title (Optional) The window title.

systemChrome (Optional) If you set this attribute to standard, the standard system chrome supplied by the operating system is displayed. If you set it to none, no system chrome is displayed. When using the Flex mx:WindowedApplication component, the component applies its custom chrome if standard system chrome is not set. The system chrome setting cannot be changed at run time.

transparent (Optional) Set this to "true" if you want the application window to support alpha blending. A window with transparency may draw more slowly and require more memory. The transparent setting cannot be changed at run time.

visible (Optional) Set this to true if you want the main window to be visible as soon as it is created. The default value is false. Note that the Flex mx:WindowedApplication component automatically sets the window to visible immediately before the applicationComplete event is dispatched, unless the showWindow attribute is set to false in the MXML definition.

You may want to leave the main window hidden initially, so that changes to the window's position, the window's size, and the layout of its contents are not shown. You can then display the window by setting the stage.nativeWindow.visible property (for the main window) to true. For details, see Working with native windows.

x, y, width, height (Optional) The initial bounds of the main window of the application. If you do not set these values, the window size is determined by the settings in the root SWF file or, in the case of HTML, by the operating system.

minSize, maxSize (Optional) The minimum and maximum sizes of the window. If you do not set these values, they will be determined by the operating system.

minimizable, maximizable, resizable (Optional) Specifies whether the window can be minimized, maximized, and resized. By default, these settings default to true.

Specifying icon files

The icon property specifies one or more icon files to be used for the application. Including an icon is optional. If you do not specify an icon property, the operating system will display a default icon.

The path specified is relative to the application root directory. Icon files must be in the PNG format. You can specify all of the following icon sizes:

<icon>
    <image16x16>icons/smallIcon.png</image16x16>
    <image32x32>icons/mediumIcon.png</image32x32>
    <image48x48>icons/bigIcon.png</image48x48>
    <image128x128>icons/biggestIcon.png</image128x128> 
</icon>

If an element for a given size is present, the image in the file must be exactly the size specified. If all sizes are not provided, the closest size is scaled to fit for a given use of the icon by the operating system.

For best results, provide an image for each of the available sizes. In addition, make sure that the icons look presentable in both 16- and 32-bit color modes.

Providing a custom user interface for application updates

AIR installs and updates applications using the default installation dialogs. However, you can provide your own user interface for updating an application. To indicate that your application should handle the update process itself, set the customUpdateUI element to true:

<customUpdateUI>true</customUpdateUI>

When the installed version of your application has the customUpdateUI element set to true and the user then double-clicks the AIR file for a new version or installs an update of the application using the seamless install feature, the runtime opens the installed version of the application, rather than the default AIR application installer. Your application logic can then determine how to proceed with the update operation. (The application ID and publisher ID in the AIR file must match those in the installed application for an upgrade to proceed.)

For more information, see Updating AIR applications.

Allowing browser invocation of the application

If you specify the following setting, the installed AIR application can be launched via the browser invocation feature (by the user clicking a link in a page in a web browser):

<allowBrowserInvocation>true</allowBrowserInvocation>

The default value is false.

If you set this value to true, be sure to consider security implications, described in Browser invocation.

For more information, see Installing and running an AIR applications from a web page.

Declaring file type associations

The fileTypes element allows you to declare the file types with which an AIR application can be associated. When an AIR application is installed, any declared file type will be registered with the operating system and, if these file types are not already associated with another application, they will be associated with the AIR application. To override an existing association between a file type and another application, use the NativeApplication.setAsDefaultApplication() method at run time (preferably with the user's permission).

<fileTypes>
    <fileType>
        <name>adobe.VideoFile</name>
        <extension>avf</extension>
        <description>Adobe Video File</description>
        <contentType>application/vnd.adobe.video-file</contentType>
        <icon>
            <image16x16>icons/AIRApp_16.png</image16x16>      
            <image32x32>icons/AIRApp_32.png</image32x32>      
            <image48x48>icons/AIRApp_48.png</image48x48>     
            <image128x128>icons/AIRApp_128.png</image128x128>
        </icon>
    </fileType>
</fileTypes>

The fileTypes element is optional. If present, it may contain any number of fileType elements.

The name and extension elements are required for each fileType declaration that you include. The same name can be used for multiple extensions. The extension uniquely identifies the file type. (Note that the extension is specified without the preceding period.) The description element is optional and is displayed to the user by the operating system user interface. The contentType property is also optional, but helps the operating system to locate the best application to open a file under some circumstances. The value should be the MIME type of the file content.

Icons can be specified for the file extension, using the same format as the application icon element. The icon files must also be included in the AIR installation file (they are not packaged automatically).

When a file type is associated with an AIR application, the application will be invoked whenever a user opens a file of that type. If the application is already running, AIR will dispatch the InvokeEvent object to the running instance. Otherwise, AIR will launch the application first. In both cases, the path to the file can be retrieved from the InvokeEvent object dispatched by the NativeApplication object. You can use this path to open the file.

See also

• Managing file associations
• Capturing command line arguments