Developing, running and packaging AIR mobile applications for Android
From IntelliJ-Wiki
This tutorial walks you through the main tasks related to developing AIR mobile applications for Android devices in IntelliJ IDEA:
- We start by preparing for AIR mobile application development. This includes enabling the Flash/Flex Support plugin, registering a Flex SDK in IntelliJ IDEA and creating a project with a Flash module. The resulting project infrastructure is briefly discussed along with the features available "out-of-the-box" (sections Exploring the project structure and Running the sample application).
- Then, we develop a simple AIR mobile application showing you some of the coding techniques and coding assistance features.
- Discussed separately is a way of creating a template for an AIR application descriptor.
- We proceed by preparing run configurations and then running the application, first using an emulator and then a real Android mobile device.
- We complete the tutorial by creating a distribution-ready Android application package and exploring the project output.
Before you start
- Download and install a Flex Software Development Kit (SDK). (You need a Flex SDK for producing Adobe Flash Player, Adobe AIR and AIR mobile-oriented applications.)
- Download and install the latest version of an Adobe AIR SDK.
- Copy all the contents of the AIR SDK installation folder into the Flex SDK installation folder. (Generally, a Flex SDK includes an AIR SDK as its part. Depending on a version, however, a Flex SDK may be incomplete in its AIR part. That is, not all of the files present in the latest AIR SDK version may be included. To avoid related problems, it’s worth "updating" your Flex SDK using the AIR SDK as a source.)
For Mac OS X users: Don’t use the Finder for copying. Instead, open the Terminal window and run the following command:ditto <path_to_air_sdk_installation_folder> <path_to_flex_sdk_installation_folder>
(There are also other commands for performing the same operation, see Merging directories on Mac OS X.)
- Get an Android 2.2+ mobile device (e.g. phone) to be able to run a sample application on it.
Making sure that the Flash/Flex Support plugin is enabled
IntelliJ IDEA’s support of Flash and related technologies (AIR, AIR mobile) is based on the Flash/Flex Support plugin. So, the first thing to do is to make sure that this plugin is enabled:
1. Open the Settings dialog (CTRL+ALT+S, or File | Settings on Windows or Linux, or IntelliJ IDEA | Preferences on Mac OS X).
2. In the left-hand pane of the dialog, under IDE Settings, select Plugins (1).
3. On the Plugins page that opens in the right-hand part of the dialog, make sure that the check box next to Flash/Flex Support is selected (3). (To quickly find this plugin, use the search box. If you type, fl, only the plugins whose names and descriptions contain fl will be shown (2).)
4. If suggested, restart IntelliJ IDEA.
(For more information on working with plugins, see Managing Plugins in IntelliJ IDEA Help.)
Specifying a Flex SDK and adding documentation URL
IntelliJ IDEA should be aware of a Flex SDK to be able to use it. To specify the Flex SDK in the IDE:
1. Open the Project Structure dialog (CTRL+ALT+SHIFT+S or File | Project Structure).
2. In the leftmost pane, under Platform Settings, select SDKs (1). Above the pane to the right, click 
(2) and select Flex SDK from the list (3).
3. In the Select Home Directory for Flex SDK dialog that opens, select the directory in which you have the desired Flex SDK installed.
Click OK or press ENTER.
The specified Flex SDK is added to IntelliJ IDEA.
4. Though this is optional, add the URL of online Flex SDK documentation to the SDK configuration. (Later, we’ll show how to use this documentation when working with your code.)
To specify the documentation URL, select the Documentation Paths tab and click 
(alternatively, press ALT+S).
The Specify Documentation URL dialog that opens already contains the URL that you want.
So, just press ENTER to accept the specified URL and close the dialog.
The URL is shown on the Documentation Paths tab.
5. At this step, configuring the Flex SDK is complete. Click OK in the Project Structure dialog.
(For more information on working with SDKs, see SDK and SDKs in IntelliJ IDEA Help.)
Creating a project
Any new development in IntelliJ IDEA starts with creating a project. (To find out why a project is needed, see Project in IntelliJ IDEA Help.)
For the purposes of this tutorial, we will create our new project from scratch and give it a name HelloWorld. We will also create a Flash module with the same name (HelloWorld) and a sample AIR mobile application.
1. To start creating a project, select New Project from the File menu. (Alternatively, you can use the Create New Project link on the Welcome screen.)
As a result, the New Project wizard opens.
2. Select Create project from scratch.
Click Next.
3. In the Project name field, type HelloWorld (1).
Make sure that the Create module option is selected (2), and, under Select type, click Flash Module (3).
The rest of the settings are OK and don’t need to be changed.
Click Next.
4. Specify the initial setting for your new Flash module.
Select Mobile as the Target platform (1) (the application that we are going to develop is intended for the AIR mobile platform).
Make sure that the Create sample app option is selected (2) (we’ll use the sample application for showing certain IntelliJ IDEA features and also as the basis for our own application development).
Click Finish to complete the wizard.
Wait while IntelliJ IDEA is creating the necessary project structures. When this process is complete, you can see the structure of your new project in the Project tool window (in the left-hand part of the workspace). At the same time, the file HelloWorld.mxml which represents the sample application is opened in the editor (in the right-hand part of the workspace).
Exploring the project structure
Let’s take a quick look at the project structure.
There are two top-level nodes in this structure:
- HelloWorld. This node represents your Flash module. The .idea folder and the file HelloWorld.iml inside are used to store configuration data for your project and module respectively. The folder src is for your source code. At the moment, this folder contains only one file, the main sample application file HelloWorld.mxml.
- External Libraries. This is a category that represents all the "external" resources necessary for your development work. Currently in this category are the .swc files that make up your Flex SDK.
(For more information on tool windows in general and the Project tool window in particular, see IntelliJ IDEA Tool Windows and Project Tool Window in IntelliJ IDEA Help.)
Running the sample application
Applications in IntelliJ IDEA are run according to what is called run/debug configurations. Such configurations, generally, should be created prior to running an application. (For more information, see Running, Debugging and Testing and Running and Debugging ActionScript and Flex Applications in IntelliJ IDEA Help.)
In our case, however, we already have one run configuration. When creating a Flash module, we specified that we’d like the sample application to be created. So, IntelliJ IDEA has created HelloWorld.mxml containing the application source code and also a run configuration for running this application.
Let’s take a quick look at this run configuration.
Accessing run configuration settings
One of the possible ways to access run configuration settings is by using the main toolbar. There is an area there containing controls related to running applications. These include the run/debug configuration selector and icons for running applications in various modes.
The configuration selector, obviously, lets you select a run/debug configuration that you want to be used. It also lets you access the run/debug configuration settings. To open these settings, select Edit Configurations.
The Run/Debug Configurations dialog opens showing the settings for the run configuration HelloWorld.
Exploring the run configuration settings
The Run/Debug Configurations dialog, at the moment, looks similar to this:
As you can see:
- The run configuration has a build configuration associated with it (shown in the Build configuration field). (See the discussion of build configurations in IntelliJ IDEA Help.)
- The application is going to be run using an emulator of an Android device (the Emulator option is selected).
- An auto-generated application descriptor will be used (the App descriptor field).
- Prior to running, IntelliJ IDEA will automatically build the application (the Make option is selected in the Before Launch section).
(To find out more about the settings in this dialog, use the Help button (alternatively, F1). This will open the dialog description in IntelliJ IDEA Help.)
We are going to use the HelloWorld run configuration as is and won’t make any changes to it yet. Click OK to close the dialog.
Studying the source code. Using online documentation
To find out what to expect when running the sample application, let’s take a look at its source code (HelloWorld.mxml).
The source code is very simple, and you, possibly, can guess at a glance what it does. Even so, we suggest that you make use of the context-sensitive online documentation to study the code. Though this might be unnecessary in this particular case, you may find this ability very useful in other circumstances.
(When configuring the Flex SDK we specified the documentation URL. So, the online documentation is only a couple of clicks away from you now.)
Place the cursor within ViewNavigatorApplication and press SHIFT+F1. The description of the ViewNavigatorApplication class opens in your default Web browser. Read the description and then switch back to IntelliJ IDEA.
Repeat this procedure for navigationContent, Button, label, click and popToFirstView(). Finally, you’ll know that there is one screen (view) in the application that contains the Home button which doesn’t really do anything useful.
Let’s now see that this is so.
(As an alternative to SHIFT+F1, you can also use CTRL+Q. In this case, the documentation extracted from the Flex SDK sources will be shown. For more information on working with documentation, see Viewing Reference Information in IntelliJ IDEA Help.)
Running the application
To run the application, click Run 
(SHIFT+F10).
As a result, the Run tool window opens at the bottom of the screen. This tool window is responsible for displaying all the output from executed run configurations. (For more information, see Run Tool Window in IntelliJ IDEA Help.)
At the moment, the tool window contains only the command line IntelliJ IDEA used to run the application, including all options and arguments.
After a while, the emulator window opens with the sample application running in it.
You can give the Home button a couple of clicks to see that it reacts somehow. There’s nothing more you can do with the application at the moment, so close the emulator window.
The Run tool window responds by outputting Process finished with exit code 0 (meaning that the application has been successfully stopped.)
Close the Run tool window by clicking 
. (If you don’t see this icon, point to the leftmost 
first.)
To complete this discussion, there are more options for running and debugging applications in the Run menu.
The options for running applications and for working with run/debug configurations, if appropriate, are also present as context menu commands in the Project tool window and the editor. (Check.)
Expanding the application
Now we are going to expand the sample application to show some of the coding assistance features.
The application we are aiming at will contain two screens (views). The first of the screens, the Home screen, will contain the Say Hello button. Tapping this button will display the second of the screens, the Hello screen. This screen will show the text Hello, World! and contain the Back button. Tapping Back will bring you back onto the first of the screens.
The application file structure and code
The application in its final state will include three .mxml files.
HelloWorld.mxml (which already exists) will just define the initial application view. Here is what it will look like:
<?xml version="1.0" encoding="utf-8"?> <s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" firstView="views.HomeView"> </s:ViewNavigatorApplication>
The remaining two files (HomeView.mxml and HelloView.mxml) which we’ll create in the views package will implement the application views. (The views package doesn’t yet exist and we’ll create it as well.) Here is the source code for these files:
views.HomeView.mxml
<?xml version="1.0" encoding="utf-8"?> <s:View xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" title="Home"> <s:VGroup width="100%" height="100%" verticalAlign="middle" horizontalAlign="center"> <s:Button label="Say Hello" click="navigator.pushView(HelloView)"/> </s:VGroup> </s:View>
views.HelloView
<?xml version="1.0" encoding="utf-8"?> <s:View xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" title="Hello"> <s:VGroup width="100%" height="100%" verticalAlign="middle" horizontalAlign="center"> <s:Label text="Hello, World!"/> <s:Button label="Back" click="navigator.popView()"/> </s:VGroup> </s:View>
Modifying HelloWorld.mxml. Creating views.HomeView.mxml from its usage
First of all, let’s get rid of unnecessary code in HelloWorld.mxml, namely:
<s:navigationContent> <s:Button label="Home" click="navigator.popToFirstView()"/> </s:navigationContent>
To do that, highlight the corresponding code lines and press DELETE.
Now place the cursor between spark" and > and press ENTER to start a new line.
Type f and select firstView from the suggestion list. (You can select the highlighted element in the list by pressing ENTER).
Between the quotation marks (that are added automatically), type views.HomeView.
Note that views.HomeView is red. This is because IntelliJ IDEA doesn’t know what it is and marks it as an error. (In fact, the referenced view HomeView and the package views don’t exist.)
Also note a light bulb 
at the beginning of the line. This indicates that there is a quick fix available for the current context. To access the quick fix list, click the light bulb or press ALT+ENTER.
Select Create View 'HomeView' (ENTER).
In the dialog that opens, confirm that you want to create the package views by clicking Yes. (Alternatively, press ENTER).
As a result, the package views and the file HomeView.mxml are created.
At the same time the new file (HomeView.mxml) opens in the editor.
Before we start editing HomeView.mxml, let’s summarize what we’ve just seen.
You don’t need to create entities such as packages, classes, etc. prior to referencing them in your code. Instead, you can reference the entities that don’t yet exist and then use a corresponding quick fix to create the referenced entities.
(For more information on quick fixes and related features, see Intention Actions in IntelliJ IDEA Help.)
Writing code for HomeView.mxml
Let’s start modifying the file by adding the title attribute to <s:View>.
Place the cursor between spark" and > and press ENTER to start a new line.
Type ti and select title.
Between the quotation marks, type Home.
Go to the end of the current line (press END) and press ENTER to start a new line.
What’s left to be added is this:
<s:VGroup width="100%" height="100%" verticalAlign="middle" horizontalAlign="center"> <s:Button label="Say Hello" click="navigator.pushView(HelloView)"/> </s:VGroup>
The quickest way to add this fragment is by moving from the "inside outward", that is, by adding <s:Button> first and then "wrapping" it in <s:Group>.
Type <s:B and select s:Button (you can use the arrow keys to move within the suggestion list).
Type / to close the tag.
Place the cursor between Button and /. Type space, then l and select label.
Between the quotation marks, type Say Hello.
In a similar way, add the remaining attribute and its value (click="navigator.pushView(HelloView)").
Note that HelloView is red because a non-existing view is referenced. Unfortunately, IntelliJ IDEA 11 doesn’t provide an appropriate quick fix (IntelliJ IDEA 12 EAP does). So let’s fix this problem by creating the corresponding view file (HelloView.mxml).
Creating HelloView.mxml
In the Project tool window, select views, press ALT+INSERT and select File form the New menu.
(Note: 1. To switch to the Project tool window using the keyboard, press ALT+1. 2. The alternative way of accessing the New menu is by selecting New from the File menu, or New from the context menu.)
In the New File dialog that opens, specify the name of the file to be created (HelloWorld.mxml) and click OK (alternatively, press ENTER).
The file HelloWorld.mxml is created and opened in the editor.
Completing the code for HomeView.mxml. Using the Surround With operation
Go back to editing HomeView.mxml. (To switch between the editor tabs using the keyboard, press ALT+LEFT ARROW or ALT+RIGHT ARROW.)
Highlight <s:Button label="Say Hello" click="navigator.pushView(HelloView)"/> and select Surround With from the Code menu (alternatively, press CTRL+ALT+T).
In the Surround With menu, select Surround with <tag></tag>.
A pair of tags (<>...</>) is added that surrounds the <s:Button> element.
Within the opening tag, type s:V and select s:VGroup.
Type space, then w and select width. Between the quotation marks, type 100%.
In a similar way, add the remaining attributes and their values (height="100%" verticalAlign="middle" horizontalAlign="center").
When the opening <s:VGroup> is completed, press ESCAPE or ENTER.
Delete the empty lines. (You can use CTRL+Y to delete a current line.)
Developing the code for HelloView.mxml
Let’s start developing code for HelloView.mxml by copying all the contents of HomeView.mxml into HelloView.mxml:
1. To select all the contents of HomeView.mxml, press CTRL+A.
2. To copy the selected contents to the clipboard, press CTRL+C.
3. To switch to HelloView.mxml, press ALT+RIGHT ARROW.
4. To paste the contents of the clipboard into the file, press CTRL+V.
Change the value of the title attribute from Home to Hello.
Start a new line after the <s:VGroup> opening tag.
Using code completion, type <s:Label text="Hello, World!"/>.
Within <s:Button .../>, change the label from Say Hello to Back, and replace pushView(HelloView) with popView().
The source code of the overall application is now ready.
We could run the application right away the way we did before but let’s first have a look at a bit different thing, an AIR application descriptor template that you are most likely to deal with in your development work.
Creating an AIR application descriptor template
An auto-generated application descriptor (see a definition of the application descriptor in Adobe AIR documentation) was created when we ran Hello World for the first time. Though that let us run the application, this is, basically, the only good thing about an auto-generated descriptor.
In fact, you have very limited control over that kind of descriptor. In practice, you are more likely to be using a descriptor template which can be flexibly adjusted to your needs. In this section, we’ll show how to create such a template and briefly discuss its contents.
Functions for creating the descriptor templates can be found in the UI for working with Flash build configurations. (See the discussion of build configurations in IntelliJ IDEA Help.) So now we are going to take a look at this UI and create the template.
Opening build configuration settings
Build configurations for Flash modules are managed in the Project Structure dialog. To open this dialog, generally, you can use File | Project Structure, the toolbar icon 
, or CTRL+ALT+SHIFT+S. However, for accessing build configurations, there is a shortcut on the Status bar. Let’s use this shortcut:
In the right-hand part of the Status bar, click HelloWorld (app) (1) and select Project Structure (2).
The build configuration settings are shown in the Project Structure dialog.
Note where in the Project Structure dialog the build configurations are located. (They appear as elements of a Flash module.)
At the moment, there is one (Flash) module HelloWorld and one build configuration with the same name. (This build configuration was created automatically when creating our Flash module.)
The settings for a selected build configuration are shown in the right-hand part of the dialog, on the Build Configuration page.
Exploring general build configuration settings
The settings on the General tab all seem to be clear. (To see their explanations, click the Help button or press F1.)
Basically, there is only one thing that we’d like you to note. This is where the module output is generated and stored (the Output folder field). By default, this is <project_folder>\out\production\<module_name>.
Creating the descriptor template
The settings and functions related to Android (including those for creating the application descriptor template) are on the Android tab. So, click this tab.
Now, to create the template:
1. Under Application descriptor, select Custom Template and click Create.
The Create AIR Descriptor Template dialog opens. Note the template file name and location. If interested, also take a look at other settings. These will affect the initial template contents and may be edited manually when the template has been created. (As in most of the cases, you can use the Help button or F1 for opening the dialog description.)
2. Click Create.
3. Click OK in the Project Structure dialog.
As a result the template file is created which you can see in the Project tool window.
Let’s take a quick look at the template contents.
Exploring the descriptor template
Open the template file in the editor. To do that, select the template file in the Project tool window and press F4.
Almost all that the template contains goes to the descriptor file as is. (The descriptor is generated in the output folder each time the module is built.)
The only variable part in the template is the <content> element (within <initialWindow>).
When generating the descriptor, the text SWF file name is set automatically at compile time is replaced with the name and extension (.swf) of the application file.
So, to control the descriptor contents, you will, generally, comment and uncomment elements, change their content, add new elements and so on.
(To uncomment a commented element, place the cursor within the element and select Code | Comment with Block Comments or press CTRL+SHIFT+SLASH. In the same way you can comment an element. However, in this case you should highlight the element first.)
Preparing run configurations
Now we are going to:
- Enable the use of the template-based descriptor in the run configuration for the emulator (HelloWorld).
- Create a configuration for running the application on a real Android device.
Enabling the use of the template in the existing configuration
Open the HelloWorld run configuration as we did before.
From the App descriptor (emulator) list, select as set for Android: HelloWorld-app.xml. (This means that the descriptor template specified for Android in the associated build configuration (HelloWorld (app)) will be used to generate the descriptor.)
No other changes in this run configuration are necessary.
Creating a run configuration for an Android device
To create a run configuration for an Android device, we will create a copy of the existing configuration (HelloWorld) and then adjust the settings. (The alternative way is to create a run configuration from scratch by using ).
1. Click Copy Configuration 
(CTRL+D). As a result, a copy of the run configuration with the name HelloWorld (1) is created.
2. Let’s change the name to HelloWorldDevice to distinguish this configuration from the one intended for the emulator (1).
3. Under Run on, select Android device (2).
No other changes in this run configuration are needed.
4. Click OK in the Run/Debug Configurations dialog to save the changes made.
Running the application on the emulator
To run the application using the emulator-oriented run configuration:
1. Select the HelloWorld run configuration.
2. Click Run (SHIFT+F10).
The result is similar to that we had when running the sample application for the first time. What is different is the application behavior.
Play with the application in the emulator for a little while, and then close the emulator window. If necessary, also close the Run tool window.
Running the application on an Android device
Before running the application we have to prepare the device and, on Windows, possibly, also to install a USB device driver.
Preparing the device
To prepare the device, you should set the default USB connection type to Charge only and also turn USB debugging on.
To set the USB connection type:
1. Press the menu button and tap Settings.
2. On the Settings screen, tap Connect to PC.
3. On the USB connection type screen, tap Default connection type and then tap Charge only.
Now to turn USB debugging on:
1. Go back to the Settings screen and tap Applications.
2. On the Applications screen, tap Development.
3. On the Development screen, select the USB debugging check box. Optionally, just for convenience, select Stay awake (Screen will never sleep while charging).
Connect the device to your PC using the USB cable.
Installing the device driver on Windows
For a Windows PC to communicate with an Android device, the corresponding device driver is needed. Sometimes, the driver is installed automatically as soon as you connect the device to your PC. If this doesn’t happen, you can install the driver included in your Flex SDK (the corresponding drivers are located in <flex_sdk_installation_folder>\install\android\usb_drivers):
Just in case, here are the instructions (if you know how to install the driver, skip the instructions and proceed to running the application).
1. Click Start 
(1), right-click Computer (2) and select Manage (3).
2. In the Computer Management dialog, under Computer Management (Local), select Device Manager (1).
3. In the second-from-the-left pane find Android Phone (it may be within the Other devices category). Right-click it (2) and select Update Driver Software (3).
The Update Driver Software wizard opens.
4. Click Browse my computer for driver software.
5. In the Browse For Folder dialog, select the folder that contains the necessary drivers (<flex_sdk_installation_folder>\install\android\usb_drivers) and click OK.
6. In the Update Driver Software wizard, under Search for driver software in this location, select Include subfolders and click Next.
7. If a Windows security warning is displayed that looks similar to this:
click Install this driver software anyway.
The driver is being installed. When this process is complete, the following page of the wizard is displayed:
8. Click Close.
In the Computer Management dialog, Android Composite ADB Interface (ADB stands for Android Debug Bridge) is shown under Android Phone which means that the driver has been successfully installed, and your PC can now properly communicate with your Android device.
9. Close the Computer Management dialog.
Running the application
Now, to run the application:
1. Select the run configuration HelloWorldDevice and click Run (SHIFT+F10).
If the AIR runtime is not currently installed on your device, the following dialog is shown:
2. Select Yes to confirm that you’d like to install the runtime.
A set of messages is displayed describing the application installation process (creating an Android package, checking for the previous installed version of the application and uninstalling it, if found, and so on). When the installation process is complete, the following is shown in the lower-left corner of the workspace:
At the same time, the starting screen of the application is shown on your device.
3. To check if everything is fine with the application, tap Say Hello and then Back when the second of the screens is shown.
Uninstalling the application and the AIR runtime (optional)
Optionally, uninstall the application and also the AIR runtime:
1. Go to Settings | Applications | Manage applications.
2. Tap HelloWorld, and then tap Uninstall. Confirm your intention to uninstall the application by tapping OK.
3. Repeat this procedure for the Adobe AIR runtime, if necessary.
Packaging the application
Once your AIR mobile Android application is tested and ready, you can package it for distribution. This is how you do that in IntelliJ IDEA:
1. Select Package AIR Application from the Build menu.
2. In the Package AIR Application dialog that opens, select the necessary options for your Android package and click Package. (Click Help (F1) to see a detailed description of this dialog.)
Wait while IntelliJ IDEA is packaging your application. (You can monitor the task status by watching the Status bar). When the process is complete, you can find the resulting package (as well as other output generated so far) in the module output folder.
Exploring the output folder
This is how the output folder (<project_folder>\out\production\<module_name>) may look in your file manager (e.g. Windows Explorer):
By now, this folder contains the following files:
- HelloWorld.apk is your Android application package.
- HelloWorld.swf is your application file.
- HelloWorld-android-descriptor.xml is an auto-generated application descriptor. This file was created when we ran the HelloWorld application for the first time (before we made changes to the HelloWorld run configuration).
- HelloWorld-app.xml is your template-based AIR application descriptor.
At this step our exercises are complete, and we hope that you now have a general idea of how to develop AIR mobile applications in IntelliJ IDEA.
