Android mobile application in Flex

Adobe Flash Builder 4.5 makes it easy for you to build mobile apps for a variety of devices using the same workflow you use to build web or desktop applications today. You can now build apps to run on the Google Android platform. In June 2011, shortly after the release of Flex and Flash Builder 4.5, Adobe will release an update that makes it possible to develop mobile apps for BlackBerry Tablet OS and iOS.

This article walks you through the basic steps required in Flash Builder 4.5 to create and run a simple mobile Flex project both on the desktop and on a device. This app will display the text "Hello, World!" on your device, with a button below it that you can tap to advance to another screen.

First things first. Make sure you have a copy of Flash Builder 4.5. You can download a trial version and check it out for 30 days.

Creating a new mobile project

Creating a Flex mobile project in Flash Builder 4.5 is easy:

1. Select File > New > Flex Mobile Project to open the project wizard.
2. On the Project Location screen of the wizard, specify the Project name: HelloWorld (see Figure 1).
3. Keep the other settings at their default values, so just click Next.

Figure 1. Specifying the Flex project location

4. On the Mobile Settings screen of the wizard, ensure that Google Android is checked as the target platform. (In a future update, Flash Builder will also offer BlackBerry Tablet OS and Apple iOS as available target platforms.) There are three possible app design styles; choose View-Based Application. Leave the other settings at their defaults for this exercise (see Figure 2).

Figure 2. Specifying the mobile settings of the Flex project

5. Now this next step is optional. In case you're interested, you can click the Permissions tab to see which permissions are allowed by the app on the device at runtime. You can leave INTERNET checked for now, since you generally want the app to connect to the Internet on the device (see Figure 3). You can see a list ofpermissions for Android devices in the online documentation.

Figure 3. Determining the mobile app's permissions

6. Click Next to advance to the Server Settings screen of the wizard. Leave the settings as-is (see Figure 4) and then click Next again.

Figure 4. Selecting the application server technology used by the mobile app

7. Flash Builder now creates the project and updates the path settings, and shows you the Build Paths screen of the wizard. Here you can add libraries or source paths that you know you'll need in your application. You can also change some filenames and parameters. For your purposes here, you only need to change the Application ID, which is a unique string needed to help identify your application.
   
   If you're creating a test project, any name is sufficient (e.g. "test") but a real-world application should use something similar to a fully qualified domain name. For example, com.mydomain.MyApp is a good choice, whereMyApp is the actual name of your application. For this tutorial, enter com.mydomain.HelloWorld as the Application ID (see Figure 5) and then click Finish.

Figure 5. Adding libraries or source paths used by the mobile app

At this point Flash Builder should load the project, open the code editor, and display your new Flex mobile application in the authoring environment (see Figure 6).

Figure 6. Flex mobile project ready to code in Flash Builder (click to enlarge)

When you create a Flex mobile project, Flash Builder generates the following files for the project (where ProjectNameis the name you give your project in the first step of the wizard):

• ProjectName.mxml: This is the application file for the project. Typically, you do not add content to the default application file directly.
• ProjectNameHomeView.mxml: This file represents the initial screen (or view) of the project. Flash Builder places the file in a package called "views."

(These are MXML files, written in the user interface markup language that Flash Builder uses to design application interfaces. You can read more about views in the online documentation.)

Adding the "Hello, World!" code to the mobile project

Right now the app is just an empty container, except for some information about the default layout. Time to add some text to the screen and a button below it that does something when pressed.

Make sure the HelloWorldHomeView.mxml tab is visible in Flash Builder. (If it's not, double-click the HelloWorldHomeView.mxml view in the Package Explorer on the left side of the project window.) Insert some blank lines above the closing </s:View> tag. Then enter the following code, or else copy and paste it:

<s:VGroup width="100%" height="100%" verticalAlign="middle" horizontalAlign="center"> <s:Label text="Hello, World!"/> <s:Button label="Continue" click="button1_clickHandler(event)" styleName="next"/> </s:VGroup> <fx:Script> <![CDATA[ protected function button1_clickHandler(event:MouseEvent):void { navigator.pushView(MyNewView); } ]]> </fx:Script>

Select File > Save to save your file. Your code should resemble Figure 7. (Pasting the copied code from the article page into Flash Builder may strip out the line breaks and indentations; however, the code still works.) Here's what this code does: Inside the VGroup (a layout container that arranges elements vertically) appears the code that will create a label that says "Hello, World!" and a button that says "Continue". Below that is a script that "pushes" the HelloWorldHomeView screen (or view) aside when the button is tapped, revealing a second screen called MyNewView.

If you choose to type out the code yourself rather than copy and paste it, you'll notice that the code hinting in Flash Builder helps you enter the proper code correctly.

Figure 7. Code to display the "Hello, World!" text and "Continue" button on the screen

You're just a few steps away from testing your application. Right now the new MyNewView screen that this pushing script is supposed to act on does not yet exist, so let's create it now:

1. In the main menu, select File > New > MXML Component. You'll see the New MXML Component dialog box.
2. Make sure "HelloWorld/src" appears as the source folder. If it isn't, click the Browse button to select the HelloWorld project.
3. For the Package, type views if it's not already there.
4. For the Name, type in the name of the screen (view) that's referenced in the script that does the pushing:MyNewView.
5. Keep the Layout set to None. Make sure that the component is "Based on" spark.components.View. Your dialog box should look similar to Figure 8.
6. Click Finish.

Figure 8. Creating the MyNewView view

Back in the authoring environment, click the MyNewView tab to make it visible, if it's not already. Let's add some text and a button to this view. Insert some blank lines above the closing </s:View> tag. Then enter, or copy and paste, the following code:

<s:VGroup width="100%" height="100%" verticalAlign="middle" horizontalAlign="center"> <s:Label text="Success!"/> <s:Button label="Back" click="button1_clickHandler(event)" styleName="back"/> </s:VGroup> <fx:Script> <![CDATA[ protected function button1_clickHandler(event:MouseEvent):void { navigator.popToFirstView(); } ]]> </fx:Script>

Select File > Save to save your file. Your code should resemble Figure 9. (Pasting the copied code from the article page into Flash Builder may strip out the line breaks and indentations; however, the code still works.) Here's what this code does for MyNewView: Inside the VGroup is the code that will create a label that says "Success!" and a button that says "Back". Below that is a script that "pops" you back to HelloWorldHomeView when the button is tapped, so you'll return to where you started.

Figure 9. Code to display the "Success!" text and "Back" button on the second screen

Now you're ready to test the app.

Testing the app on the desktop

You don't need a mobile device to test your app. Flash Builder makes it easy to run and debug mobile apps on the desktop:

1. Ensure that the main MXML file for the project is open and active within the code editor (its name should be HelloWorld.mxml).
2. Click the Run button on the main toolbar (see the red highlight in Figure 10).

Figure 10. Clicking the Run button on the main toolbar

3. Ensure that the target platform is set to Google Android.
4. For the Launch Method, select On Desktop and then choose a device to simulate—for example, Motorola Droid Pro. Your settings should resemble those shown in Figure 11.
5. Click Run in the dialog box to accept your settings and launch the application on the desktop.
6. A program launcher called ADL now runs, showing a window (called HelloWorld-debug) that displays "Hello, World!" on the HomeView screen and a Continue button below it (see Figure 12).
7. Click the Continue button to advance to the next screen, MyNewView, which displays "Success!" on the screen and a Back button below it. Clicking the Continue button is the equivalent of tapping the button with your finger on the actual device.

Figure 11. Selecting the emulated device with which to test the app

Figure 12. Running the mobile application in a window that mimics the device's look. The first screen appears on the left; the second screen on the right.

9. Either click the Back button or press Control-B (Command-B) to go back to the previous screen. This is the equivalent of tapping the Back button on the actual device. You can click back and forth between these two views.
10. Close the HelloWorld-debug window and then select File > Save to save your Flash Builder project file.

Congratulations! You have successfully run your first Flex mobile app on the desktop.

Testing the app on the device

Testing your app on a simulated device is one a good way to see how it looks but running and debugging the app on an actual device is even better. The following steps show you to run your application on a real Android device connected over USB:

1. Make sure that USB debugging mode is enabled on your device. On Android 2.2, you do this by launching the system settings application, tapping Applications > Development, and then ensuring that USB Debugging is checked. (Tap OK on your device to allow USB debugging.) For more information, see Connect Google Android devices in the online documentation.
2. Plug your device into your computer via a USB cable. Your device may prompt you to choose a connection type. Choose to mount it as a disk drive.
3. Click the Run button on the main toolbar (see the red highlight in Figure 13).

Figure 13. Clicking the Run button on the main toolbar

4. In the Run Configurations dialog box, ensure that the Project field displays "HelloWorld" (if not, click Browse to select it), the application file is set to "src/HelloWorld.mxml", Google Android is the target platform, and On Device is the selected launch method (see Figure 14).
5. Click Run in the dialog box to make Flash Builder send the app to your device. Your device should respond and your app should automatically launch.

Figure 14. Configuring the app to run on a mobile device

Note: If your computer prompts you to upgrade your device to run the latest version of Adobe AIR, click OK (see Figure 15).

Figure 15. Prompt to upgrade your device to the latest version of Adobe AIR

Congratulations! You have successfully run your first Flex mobile app to a mobile device. Note that your app is called HelloWorld-debug on the device. Now it's time to deploy the release build of your HelloWorld app. (A release build is generally the final version of the application.)

Bonus: Packaging the app for release

Once you're ready to release the final build of your application, for example to the Android Market, you can export it from Flash Builder:

1. With your project open in Flash Builder, select Project > Export Release Build.
2. In the Export Release Build dialog box, make sure that your HelloWorld project appears in the Project selector. HelloWorld.mxml should appear in the Application selector.
3. Connect your device to your computer if it is not already.
4. Specify the base filename of the Android Package (APK) file or leave the default, which is the project name.
5. Make sure that "Signed packages for each target platform" is selected. Click Next to start the build export process.
6. You now have to select a digital signature that is used to sign the application. Trusted signatures are obtained from certificate authorities, but you can create a self-signed certificate for now. Either locate your existing certificate and enter your password, or click the Create button and fill out the information in the Create Self-Signed Digital Certificate dialog box. (Use your name as the publisher name and enter your password where indicated.)
7. Click Browse to save your certificate to your computer. The path and filename you entered will now appear in the Save As field (see Figure 16). Click OK to return to the Export Release Build dialog box.
8. This next step is optional. Click the Package Contents tab to see which assets are being included in the release build. These are the necessary files for your app to run, and they vary from app to app. (Including more assets may increase the final package size, so you'll want to carefully determine which assets to include when you publish your mobile apps to devices.)
9. Click Finish.

Figure 16. Creating a self-signed digital certificate

Congratulations! Flash Builder created the release build (APK) file and deployed and installed it on your device. Note that the release build is called HelloWorld, while the HelloWorld-debug app is your test app.

Note: If no device is connected or recognized, you'll see a warning that it wasn't successfully deployed.

You will find your APK file in the default folder where Flash Builder stores your project asset files:

• Windows: C:\Users\<username>\My Documents\Adobe Flash Builder 4.5\<project folder>
• Mac OS: HD/Users/<username>/Documents/Adobe Flash Builder 4.5/<project folder>

You could now submit this as an app to the online store.

Bonus: Redesigning the buttons with skins

Flash Builder makes it a snap to change the appearance ("skin") of visual elements in your project. The following steps show you how to import a style sheet and some skinning MXML files so you can swap out the buttons' look with a simple code change.

1. Download the sample project file (HelloWorldSkins.zip) from the top of the article and extract its contents to a folder of your choosing (for example, on the desktop).
2. Select File > Import Flash Builder Project from the main menu. In the Import Flash Builder Project dialog box, browse to the FXP file you just extracted from the sample file for this article (HelloWorldSkins.fxp) and click Open. Click Finish in the confirmation dialog box to complete the process.
3. Note the addition of the HelloWorldSkins project to the Package Explorer. Expand the HelloWorldSkins folder to reveal the main.css file in HelloWorldSkins/src/(default package) folder.
4. Drag the main.css file from the HelloWorldSkins folder to the HelloWorld/src/(default package) folder (see Figure 17).

Figure 17. Dragging the main.css file from the HelloWorldSkins sample project (left) to your HelloWorld project (right)

5. In the Move dialog box, confirm that you want HelloWorld/src/(default package) as the destination folder for the move (see Figure 18). If a different destination is highlighted, just click "(default package)" to select it.

Figure 18. Confirming the destination of the moved file

6. Select File > New > Package from the main menu. In the New Package dialog box, make sure that "HelloWorld/src" appears as the source path and enter skins as the package name. Click Finish to complete the process.
7. Back in the Package Explorer, expand the HelloWorldSkins/src/skins folder to reveal four MXML files: 
   
   • BackButtonSkin1.mxml
   • BackButtonSkin2.mxml
   • NextButtonSkin1.mxml
   • NextButtonSkin2.mxml
   Select the first MXML file in the list (BackButtonSkin1.mxml) and then press Shift on your keyboard and select the last MXML file in the list (NextButtonSkin2.mxml). You should have selected all four files in the group.
8. Drag all four files to the empty HelloWorld/src/skins folder you just created. This time the Move dialog box asks you to confirm the destination of the four resources you're moving. Make sure that "skins" is highlighted and click OK to complete the move. Your HelloWorld asset structure should now look like Figure 19.

Figure 19. Revised HelloWorld asset structure showing newly added main.css file and skin MXML files

9. To make your HelloWorld project aware of the main.css file you just inserted, double-click the HelloWorld.mxml file in the "(default package)" folder to open it in the workspace. Insert the following line just above the closing</s:ViewNavigatorApplication> tag:
   
   <fx:Style source="main.css"/>
   Your code should resemble Figure 20.

Figure 20. HelloWorld.mxml file showing new code referencing the main.css file

10. Select File > Save to save the HelloWorld.mxml file.
11. With the HelloWorld project selected in the Package Explorer, click the Run button. You should now see a very different set of buttons on the screens (see Figure 21).

Figure 21. Buttons with the NextButtonSkin1 and BackButtonSkin1 skin applied

12. Earlier you moved four skin files from the article's sample file to your own. Figure 21 shows one set of skins; changing the buttons to show the other set is as easy as making a simple code change.
13. First close the ADL window showing the app demo. Then double-click the main.css file in HelloWorld/src/(default package) to open it in the workspace. Change the skin names being referred to from "1" to "2":
    
    • NextButtonSkin1 becomes NextButtonSkin2
    • BackButtonSkin1 becomes BackButtonSkin2
14. Save the main.css file (File > Save) and re-run the HelloWorld app. You should now see yet another different set of buttons on the screens (see Figure 22).

Figure 22. Buttons with the NextButtonSkin2 and BackButtonSkin2 skin applied

Congratulations! You've seen how easy it is to change the appearance of a button in your HelloWorld app buy making a simple change to the main.css file, which references the skin definition file that you inserted into your project.