The AIR application descriptor file is an XML file that sets the basic properties of an AIR application. When developing with FLEX, it lives at “project folder/src/main file name-app.xml”; when developing with Flash CS3 it is also generated automatically when you create an AIR project, and you can edit it visually through the menu Commands > AIR - Application and Installer Settings, or edit the XML document by hand.
The application descriptor file contains the properties of the AIR application and affects the whole application — its name, version, copyright, and so on. In theory, the application descriptor file can use any file name. When we create an empty file with Flash CS3 and use the default settings, the descriptor file is automatically renamed application.xml and placed in a special directory of the AIR project.
The structure of this descriptor file looks like this:
AIR Application Properties
minimumPatchLevel: Together with the AIR namespace, indicates the required runtime version. The AIR application installer will prompt the user to download the required patch version.
Basic Application Information
This section declares the app’s ID, version, filename, program name, description, and copyright.
id:[required] The unique identifier string for this AIR application. This element is required, must be 1–212 characters long, and is limited to the following characters:
- 0-9
- a-z
- A-Z
- . (dot)
- - (hyphen)
To make the identifier “unique”, we usually use the reverse of a domain name the author owns as the prefix; for example, the prefix org.mousebomb in org.mousebomb.TestApp is mousebomb.org written backwards.
version:[required] Sets the version number of the AIR application. This version number has nothing to do with the AIR runtime, and the AIR runtime does not parse it. For example, you can write: “1.0”, “.4”, “0.5”, “4.9”, “1.3.4a”.
filename:[required] This is the file name of the AIR application’s main program (no extension needed). For example, if you set it to “main”, then when AIR installs the application it generates an executable file whose name is “main”. The value can be set to any UTF-8 character other than the following:
Character
Hex code
various
0x00 - x1F
*
x2A
“
x22
:
x3A
>
x3C
<
x3E
?
x3F
x5C
x7C
name:[optional, but recommended] The title shown while the AIR installer runs; if the install folder is not set in the installFolder element, the value of name is also used as the install folder’s name.
description:[optional] The description shown when the AIR application is installed.
copyright:[optional] Copyright information. On Mac systems, this copyright text is displayed in the About dialog of the installed AIR application, and also appears in the Info.plist file as the value of the NSHumanReadableCopyright key.
Install Folder and Start Menu Path
**installFolder[optional]: ** Determines the subdirectory under the default installation directory.
On Windows, the default installation subdirectory is under the Program Files directory. On Mac OS, it is the /Applications directory. For example, if the installFolder property is set to “Mousebomb AIR” and the AIR application is named “ExampleApp”, then the AIR application is installed at “C:Program FilesMousebomb AIRExampleApp” (Windows), or “/Applications/Mousebomb AIR/Example.app” (Mac OS). You can also use “/“ in installFolder to create additional subdirectories.
This element is optional; if it is not set, the AIR application will use the value of name as the installation subdirectory name when it installs.
programMenuFolder:[optional] Windows only; sets the directory of the AIR application in the Start menu. The character restrictions are the same as for installFolder.
Properties of the Initial Application Window
When the AIR program loads, the runtime creates an initial window based on the relevant settings in initialWindow, and loads the specified SWF or HTML file into that window.
The values of initialWindow’s child elements are used to set the initial window’s properties until the top-level file has finished loading.
content: Sets the URL of the main content file, which can be a SWF or an HTML file. This value is a relative path based on the AIR application’s installation directory.
Note: because the value of the content element is treated as a URL, the content’s file name must be encoded according to RFC 1738. For example, a space must be written as %20.
**title[optional]: ** The title of the window.
**systemChrome[optional]: ** If this property is set to standard, the window is displayed with the system chrome; if set to none, no system chrome is displayed. This property cannot be changed at runtime.
**transparent[optional]: ** Whether the window is transparent. true is transparent, false is opaque. Transparency slows down drawing and uses more memory. This property cannot be changed at runtime.
Note: when systemChrome is none, transparent can only be set to true.
**visible[optional]: ** Whether the window is visible; true means visible, false means not. The official docs say the default is false, so why is it true by default when I create a project… This parameter can be set at runtime via stage.nativeWindow.visible.
**x, y, width, height[optional]: ** These four properties are self-explanatory. If you don’t set these values, they depend on the SWF’s settings (SWF), or the operating system decides automatically based on the content (HTML).
**minSize, maxSize[optional]: ** Minimum size, maximum size. If not set, the operating system decides.
**minimizable, maximizable, resizable[optional]: ** Set whether the window can be minimized, maximized, and resized. All default to true.
Setting Icon Files (Commonly Used!)
You can set icon files in 4 sizes. If you don’t, the system uses the default icon.
The icon file size corresponding to each element must match it; if it doesn’t, the operating system automatically scales the image from the closest size.
Note: you need to package the icon files when publishing the AIR package.
For the best results, design icons that display properly in both 32-bit and 16-bit color.
Providing a Custom User Interface for AIR Application Updates
Although AIR uses a default dialog to install and update AIR applications, you can customize your own application update UI. To display your custom app, you have to handle the updater itself.
Suppose you have already installed an AIR application with customUpdateUI set to true, and then you double-click an .air installer package containing an update, or install an updater that uses the seamless install feature — the runtime will open the version you already installed and let it perform the update, and your AIR application logic must decide how to carry out the update correctly (the new version’s application ID and publisher ID must match the old version’s). I’ve never done this one; for details see the official docs http://livedocs.adobe.com/air/1/devappsflash/updating_apps_1.html#1032597
Allowing the Browser to Invoke the AIR Application
Have you ever used QQ, EMULE, or Taobao’s Wangwang? From a web page you can click a link to open the program directly and perform the relevant actions. If set to true, our AIR app can also be invoked from a web page. Security issues must definitely be taken into account when implementing this feature; see http://livedocs.adobe.com/air/1/devappsflash/app_launch_1.html#1039401 (browser invocation).
Declaring File Associations
[optional] This setting lets the AIR application associate file formats in the system after installation. If a format you want to associate is already associated with another program, you can override that association: use the NativeApplication.setAsDefaultApplication() method at runtime. But it’s best to get the user’s consent first.
Note: the NativeApplication.setAsDefaultApplication() method can only associate formats declared in fileTypes. See http://livedocs.adobe.com/air/1/devappsflash/runtime_os_info_1.html#1036812 (managing file associations) http://livedocs.adobe.com/air/1/devappsflash/app_launch_1.html#1038002 (capturing command-line arguments)