Developing BlackBerry Tablet Applications with Flex 4.5

Chapter 1. Hello World

This section will walk you through building your first BlackBerry PlayBook application using Adobe Flash Builder 4.5. If you don’t have Flash Builder 4.5, you can get a trial from Adobe at http://www.adobe.com/products/flashbuilder/.

Now that you have Flash Builder 4.5 installed, open it and lets get started.

Create a Flex Mobile Project

Create a new Flex Mobile Project by choosing File→New→Flex Mobile Project as shown in Figure 1-1.

Figure 1-1. Create a Flex Mobile Project

This will open the New Flex Mobile Project wizard, which will walk you through the rest of the project-creation process. The first screen you’re presented allows you to set the project name, location, and Flex SDK. Enter the name HelloWorld as the Project name and leave the other settings to their defaults. Click Next, as shown in Figure 1-2.

Figure 1-2. Project Name and Location

The second screen in the new project wizard is where you can select settings specific to the target platform. Since you have installed the Blackberry Tablet OS plug-in, you will see the options for both Google Android and BlackBerry Tablet OS. Select BlackBerry Tablet OS. You also have the option of three different application types: Blank, View-Based Application, and Tabbed Application. For this first project, select View-Based Application as shown in Figure 1-3 and leave the other settings to their defaults.

Figure 1-3. Select Application Template

Next, click on the Permissions tab. Within this tab, you can select the permissions your application will need in order to interact with the BlackBerry Tablet OS–native APIs. For the purposes of this exercise, leave only the access_internet permission selected, as shown in Figure 1-4. Click next.

Figure 1-4. Set BlackBerry Tablet OS Permissions

The next screen allows for the configuration of an application server and output folder. For this project, we will not be using an application server, so leave it set to None/Other and click next, as shown in Figure 1-5.

Figure 1-5. Server Settings

The last screen that you will see is the Build Paths screen; this is where you set your Application ID. This setting is very important, as the Application ID will be used to identify your application in BlackBerry App World. To ensure that your application has a unique identifier, the reverse domain naming convention works best. Figure 1-6 shows the value of com.domain.mobile.HelloWorld as the application ID. By replacing the word domain with a domain that you own, you can ensure that your application ID is unique. Complete this step and click Finish.

Figure 1-6. Application ID

Flash Builder will now create your new project and, by default, the HelloWorldHomeView.mxml will be created and opened in the workspace, along with the HelloWorld.mxml main application file (see Figure 1-7).

Figure 1-7. New Project has been created

Let’s update the contents of the HelloWorldHomeView.mxml by adding a Label.

<?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="HomeView">
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>

    <s:Label text="Hello World" fontSize="24"
             horizontalCenter="0" verticalCenter="0"/>

</s:View>

Before running an application for the first time, you will need to set up either a simulator environment or a device for your testing.

Set Up a Test Environment

If you do not have a device to test with, RIM has made a VMware image available—it’s located at http://us.blackberry.com/developers/tablet/adobe.jsp. After downloading this disk image, open it within VMware and complete the following steps to test your application.

Within Flash Builder, click on the Flash Builder and then on the Preferences menu. Then expand the Flash Builder→Target Platforms→BlackBerry Tablet OS→Signing item within the tree on the left side. See Figure 1-8.

Figure 1-8. Signing Screen

Click on the Create certificate to create a new certificate for your workspace. Fill in the form values, then click OK. See Figure 1-9.

Figure 1-9. Create a Developer Certificate

Next, you will need to register as a developer with RIM by completing the form at https://www.blackberry.com/SignedKeys/. Once you have completed this form, you will be sent some code-signing files. To register these with Flash Builder, click on the Register button (see Figure 1-10). Figure 1-11 shows the registration form. Figure 1-12 shows that you have now been registered with the RIM Signing Authority.

Figure 1-10. Developer Certificate Created

Figure 1-11. Register RIM Signing Authority

Figure 1-12. RIM Signing completed

Now that you have created a certificate and registered yourself with RIM, you need to add a test device. Select the Test Devices item from the left menu.

Click on the Add button. See the setup instructions in Setup Simulator or Setup Device to move forward with your testing. See Figure 1-13.

Figure 1-13. Add a Test Device

Setup Simulator

Open the virtual machine within VMware. Click on the gear in the upper-right corner and then click security. Turn on development mode (see Figure 1-14). Now go back to the home screen and click the little person icon to read your IP address (see Figure 1-15).

Once you have your IP address, complete the Add BlackBerry Tablet OS Test Device setup. Be sure to check the box that says Create a debug token and upload it to this device (see Figure 1-16). Once you say OK, you will be prompted to set the device to accept the debug token. Figure 1-17 shows the warning dialog. Figure 1-18 shows the simulator waiting for the debug token. Figure 1-19 shows that the debug token has been added.

Figure 1-14. Turn on Development Mode in Simulator

Figure 1-15. Read IP Address

Figure 1-16. Complete Form with IP Address of Simulator

Figure 1-17. Upload Debug Token warning

Figure 1-18. Waiting for Debug Token

Figure 1-19. Debug Token added

Setup Device

Connect your device via USB. Click on the gear in the upper-right corner and then click security. Turn on development mode (see Figure 1-20). Now go back to the home screen and click the little person icon to read your IP address (see Figure 1-21).

Once you have your IP address, complete the Add BlackBerry Tablet OS Test Device setup. Be sure to check the box that says Create a debug token and upload it to this device (see Figure 1-22). Once you say OK, you’re prompted to set the device to accept the debug token. Figure 1-23 shows the warning dialog; Figure 1-24 shows the device waiting for the debug token; Figure 1-25 shows that the debug token has been added; and Figure 1-26 shows the debug token installed on the device.

Once this completes, you’re ready to move on to Reading and setting author information for debug, where you will set the author and author ID.

Figure 1-20. Turn on Development Mode in Device

Figure 1-21. Read IP Address

Figure 1-22. Complete Form with IP Address of Device

Figure 1-23. Upload Debug Token warning

Figure 1-24. Waiting for Debug Token

Figure 1-25. Debug Token added

Figure 1-26. Debug Token installed on device

Reading and setting author information for debug

Before you can run your application, you need to add your author name and ID to the blackberry-tablet.xml file. To read these values, go to Preferences→BlackBerry Tablet OS→Signing. Highlight one of your Debug Tokens and click the Details button (see Figure 1-27). Figure 1-28 shows the author information. Copy the author name and author ID into the blackberry-tablet.xml file as shown in the following code.

<?xml version="1.0" encoding="UTF-8"?>
<qnx>
   <author>HappyToad LLC</author>
   <authorId>gYAAgBCK5G60OhJ_Alo1WGV0fks</authorId>
   <buildId>349</buildId>
   <platformVersion>1.0.0.0</platformVersion>
</qnx>

Figure 1-27. Select debug token then click details

Figure 1-28. Copy debug token details

Now we can run the application. To do this, right-click on the HelloWorld.mxml file within the Package Explorer and select Run As→Mobile Application, as shown in Figure 1-29. Since this is the first time running this application, the Run Configurations window will open.

To run this application on the simulator, select “On device” and choose Simulator from the drop-down menu (see Figure 1-30).

To run this application on the device, select “On device” and choose PlayBook from the drop-down menu (see Figure 1-31).

Now click Apply and then click Run as you see the Hello World application launch.

Figure 1-32 shows Hello World running on the simulator.

Figure 1-33 shows Hello World running on the device.

Figure 1-29. Run As Mobile Application

Figure 1-30. Run on Simulator

Figure 1-31. Run on Device

Figure 1-32. Hello World running on simulator

Figure 1-33. Hello World running on device

Congratulations, you have just created your first BlackBerry Tablet OS application with Adobe Flex 4.5.

Debug a Flex Mobile Project

Now that you have created your Hello World application and run it via the Run Configurations window, you may wish to debug your application. Fortunately for you, the workflow for debugging a Flex Mobile application is the same as debugging any other Adobe Flex or Adobe AIR application.

Update the HelloWorld.mxml file to include a creationComplete handler as shown in the following code.

<?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.HelloWorldHomeView"
    creationComplete="viewnavigatorapplication1_creationCompleteHandler(event)">
    <fx:Script>
        <![CDATA[
            import mx.events.FlexEvent;

            protected function viewnavigatorapplication1_creationCompleteHandler
            (event:FlexEvent):void
            {
                // TODO Auto-generated method stub
                trace("hello world");
            }

        ]]>
    </fx:Script>
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>
</s:ViewNavigatorApplication>

We now need to toggle a breakpoint within the application on line 14 to demonstrate a debugging session. To do this, right-click on line 14 within Flash Builder and select Toggle Breakpoint from the context menu. Figure 1-34 shows this process. A small blue dot will appear in the gutter, showing that the break point is enabled.

Figure 1-34. Toggle a Breakpoint

We’re now ready to debug this application. To do this, right-click on the HelloWorld.mxml file within the Package Explorer, then select Debug As→Mobile Application, as shown in Figure 1-35. Since this is the first time debugging this application, the Debug Configurations window will open. To debug this using the Flash builder emulator, select “On device” as the Launch method and select a device from the drop-down menu, as shown in Figure 1-36.

When asked if you would like to switch to the Flash Builder debug perspective, select Yes (see Figure 1-37). Figure 1-38 shows the application paused on line 14 within Flash Builder’s debug perspective. You can see the trace message within the console panel. To allow the application to complete, click the Resume button.

Congratulations, you have just completed your first Flash Builder debug session for a Flex Mobile application.