Building an AIR application with Flash Professional CS5 and the BlackBerry Tablet OS SDK

The BlackBerry PlayBook runs the BlackBerry Tablet OS, and includes support for Adobe AIR and Adobe Flash Player. The BlackBerry Tablet OS SDK provides tools to package and deploy AIR applications (which use the .bar file extension) to the PlayBook simulator. Using this setup, you can create Flash content with either Adobe Flash Professional or Adobe Flash Builder.

In this article you'll learn how to build, package, and deploy a Battery Monitor application using Flash Professional CS5 and the BlackBerry Tablet OS SDK. This article is divided into the following sections:

• Using the BlackBerry Tablet OS SDK and Flash Professional CS5 Extension for AIR 2.5
• Creating a battery monitor application
• Packaging and deploying your application for the PlayBook simulator

The BlackBerry Tablet OS SDK for Adobe AIR provides APIs for developing AIR applications for the PlayBook. The current version of the SDK provides APIs for UI controls, which have an appearance similar to the native UI controls of the PlayBook. It also provides APIs to access system information, such as battery status. Along with the necessary libraries, it provides tools to package and deploy PlayBook applications (.bar files) to the PlayBook simulator.

Currently, a plug-in exists for Flash Builder 4 to deploy the PlayBook applications you create. At the time of this writing, a similar plug-in doesn’t exist for Flash Professional CS5. This article describes how to develop PlayBook applications using Flash Professional CS5 with the BlackBerry Tablet OS SDK.

Before following along with the steps in this article, install Adobe Flash Professional CS5 Extension for AIR 2.5 (beta) from Adobe Labs. Then download the BlackBerry Tablet OS SDK and install it as described in the Getting Started Guide.

In this section, you'll use Flash Professional to build a sample application for the PlayBook. To demonstrate how the app works, a battery monitor application is provided for you to download in the Requirements section at the top of this page. The sample files folder contains two subfolders. The items in the "For desktop" folder enable you to preview the functions of the application in Flash. The items in the "For simulator" folder use the APIs provided in the BlackBerry Tablet OS SDK. The files in this folder can be packaged and deployed to the PlayBook simulator. 

Introduction to the Battery Monitor

The Battery Monitor is an application that displays an accurate battery level and status. After downloading and uncompressing the sample files folder, open the file named BatteryMonitor.fla located in the "For desktop" folder. Test the movie to preview the application locally (see Figure 1).

In the "For desktop" subfolder of the sample files folder, locate the file named main.as. Open it and find the following lines of code: 

You can change the values of these variables and then test the movie again to see the results as the movie plays in Flash Player. You can use these variables to debug the movie without using a real device or a simulator.

Configuring the library path of the BlackBerry Tablet OS SDK

To get the battery information of the PlayBook device, you'll leverage the APIs provided by the BlackBerry Tablet OS SDK. The API reference document is located in the SDK folder, if you’d like to read more about how it works. When using APIs in your projects, you must add the library paths to the FLA file. In Flash Professional CS5, follow the steps:

1. Select File > ActionScript Settings.
2. In the Advanced ActionScript 3.0 Settings dialog box, select the Library Path tab.
3. Click the Add New Path button (the plus sign icon) and then click the Browse button (the Flash icon). In the Browse to SWC file window that appears, navigate to the SWC file named qnx-screen.swc, which is located in the installed BlackBerry Tablet OS SDK folder. Click Open.
4. Click the Add New Path button again. Click the Browse button to open the Browse to SWC file window. Navigate to the qnx-air.swc file that exists in the installed BlackBerry Tablet OS SDK folder. Click Open.
5. Click the arrow to the left of the qnx-air.swc path to expand it. Double-click the Link Type. In the Library Path Item Options dialog box that appears, use the Link Type menu to select External. Click OK as shown in Figure 2.

Note: It’s important to set the qnx-air library as external because it contains classes that only exist in the AIR runtime in the simulator, and do not exist in the AIR runtime on the desktop.

After making these changes, the library paths are updated (see Figure 3).

The battery information APIs are not native APIs of the Adobe AIR SDK. The BlackBerry Tablet OS SDK provides APIs that enable you to get the battery level values and trigger events when the battery status changes.

In the For simulator folder, locate and open the BatteryMonitor.fla file. Examine the following code in the main.as file:

These lines of code are used to import the classes necessary for monitoring the device’s battery status. Continue reading through the lines of code:

In the first line of the code example above, setting Device.device.batteryMonitoringEnabled to true allows you to turn on the battery monitoring functionality. When the batteryMonitoringEnabled method is set to true, DeviceBatteryEvent.LEVEL_CHANGE and DeviceBatteryEvent.STATE_CHANGE events are dispatched whenever changes to the battery level and state occur. You can use the onLevelChange and onStateChange event listener functions to monitor the battery levels and correspondingly update the battery icon in the application.

Open the file named battery.as and review the first two lines of code:

These import statements import the UI controls classes provided by the BlackBerry Tablet OS SDK. You can choose to use the UI controls classes provided by BlackBerry or create your own UI controls in ActionScript. For the purposes of this sample project you'll use the UI controls classes provided by BlackBerry because they make your application look like a native PlayBook application. The function named showWarning() is designed to display an alert message whenever the battery status is UNKNOWN.

Generating the application’s descriptor file

In this section, you'll add information that is required for the BlackBerry Tablet OS. Follow these steps:

1. Choose File > Adobe AIR 2.5 settings.
2. In the Version field, enter the value 1.0.0. The value of this field is used by the Tablet OS and must match this format.
3. In the Copyright field, enter 2010 Adobe Systems Inc. The value of this field is also required by the Tablet OS.
4. After making these changes, review the updated settings (see Figure 4).

Note: After making these changes, don't click Publish. Click OK and then test the movie. Flash Professional creates the application descriptor file automatically when the SWF movie is generated.

Now that the SWF file and the application descriptor file are ready, you'll follow the instructions provided in the next section to use the BlackBerry Tablet OS SDK tools for packaging and deploying the application. 

The steps outlined in the BlackBerry Tablet OS documentation describe how to package and deploy .bar files. Follow those steps to package and deploy the battery monitor application to the PlayBook simulator.

Note: The BlackBerry Tablet OS SDK does not currently support Flash Professional CS5 but the command line steps used to package and deploy the application are the same.

PlayBook simulator limitations

When you launch the battery monitor application on the PlayBook simulator, the warning message is displayed (see Figure 5).

This occurs because the simulator’s battery status always returns the value: UNKNOWN. The warning message is displayed to handle this kind of exception situation. When using the simulator, you cannot debug the battery monitoring functionality. Additionally, there are other features that are not supported by the simulator at the time of this writing, including the camera, GPS APIs and the microphone.

To work around the limitations of the simulator, you can debug your applications on a different mobile device. For example, you could publish your BlackBerry Tablet applications to AIR for Android. That way, you can use the APIs provided by the Adobe AIR SDK if your project does not require using the BlackBerry Tablet OS SDK. After testing and confirming that the features work as expected, you just need to modify the FLA file a bit to make it run on the PlayBook device.  

Both the BlackBerry Tablet OS SDK and Flash Professional will continue to improve the AIR application development workflow. It is an exciting time, because you can easily deliver applications using Flash Professional to the new BlackBerry Tablet platform. Stay tuned and be sure to visit the Adobe Developer Connection and BlackBerry Tablet OS developer page to learn about upcoming features and get updates.