Editor: Mary Treseler Production Editor: Holly Bauer Proofreader: Holly Bauer
Cover Designer: Karen Montgomery Interior Designer: David Futato Illustrator: Robert Romano
Printing History: July 2011:
Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. The image of a parrot and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc., was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.
Introduction to BlackBerry Tablet OS In 2011, Research in Motion (RIM) introduced an entirely new operating system known as the BlackBerry Tablet OS. The first device using this new operating system was released in May of 2011 and was known as the BlackBerry PlayBook. Through Adobe’s partnership with RIM, this new operating system was built fully integrated with the Adobe AIR runtime; as a result, the performance of Adobe AIR applications running on BlackBerry tablet devices is outstanding, and RIM has built specific libraries accessible to ActionScript for deep integration within the operating system. This book walks you through the creation of your first Adobe AIR application using the Flex 4.5 framework and provides examples of how to interact with the device’s components. These include the GPS unit, camera, gallery, accelerometer, multi-touch display, and the StageWebView, Operating System interactions, native components, and more.
Who This Book Is For Developing BlackBerry Tablet OS Applications with Adobe Flex 4.5 targets developers of every skill level. It starts with a basic Hello World application and then quickly moves to more complicated examples where the BlackBerry Tablet OS APIs are explored.
Who This Book Is Not For This book is not for developers who are interested in developing native BlackBerry applications. This book only provides examples of BlackBerry Tablet OS application development using Adobe Flex 4.5 and ActionScript 3.
Conventions Used in This Book The following typographical conventions are used in this book:
Menu options Menu options are shown using the → character, such as File→Open. Italic Italic indicates new terms, URLs, email addresses, filenames, and file extensions. Constant width
This is used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. Constant width bold
This indicates commands or other text that should be typed literally by you. Constant width italic
This indicates text that should be replaced with user-supplied values or values determined by context.
This Book’s Example Files You can download the example files for this book from this location: http://examples.oreilly.com/9781449305567-files/ Where necessary, multiple code samples are provided for each recipe to correspond with the different development environments. Each sample will be separated into a folder for the specific environment. Each application should include the needed code for your environment as well as an application descriptor file.
Using the Code Examples This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. In addition, answering a question by citing this book and quoting example code does not require permission. However, selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission. We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Developing BlackBerry Tablet Applications with Flex 4.5 by rich Tretola (O’Reilly). Copyright 2011 Rich Tretola, 978-1-449-30556-7.” If you think your use of code examples falls outside fair use or the permission given here, feel free to contact us at firstname.lastname@example.org. viii | Preface
How to Use This Book Development rarely happens in a vacuum. In today’s world, email, Twitter, blogs, coworkers, friends, and colleagues all play a vital role in helping you solve development problems. Consider this book yet another resource at your disposal to help you solve the development problems you will encounter (however, this book does have a big advantage: it’s available anytime of the day or night). The content is arranged in such a way that solutions should be easy to find and understand.
Safari® Books Online Safari Books Online is an on-demand digital library that lets you easily search over 7,500 technology and creative reference books and videos to find the answers you need quickly. With a subscription, you can read any page and watch any video from our library online. Read books on your cell phone and mobile devices. Access new titles before they are available for print, and get exclusive access to manuscripts in development and post feedback for the authors. Copy and paste code samples, organize your favorites, download chapters, bookmark key sections, create notes, print out pages, and benefit from tons of other time-saving features. O’Reilly Media has uploaded this book to the Safari Books Online service. To get full digital access to this book and others on similar topics from O’Reilly and other publishers, sign up for free at http://my.safaribooksonline.com.
How to Contact Us Please address comments and questions concerning this book to the publisher: O’Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472 (800) 998-9938 (in the United States or Canada) (707) 829-0515 (international or local) (707) 829-0104 (fax) We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at: http://www.oreilly.com/catalog/9781449305567 To comment or ask technical questions about this book, send email to: email@example.com
Preface | ix
For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com. Find us on Facebook: http://facebook.com/oreilly Follow us on Twitter: http://twitter.com/oreillymedia Watch us on YouTube: http://www.youtube.com/oreillymedia
Acknowledgments First and foremost, I would like to thanks my wife and best friend, Kim, and my daughters, Skye, Coral, and Trinity, for their love and support. I love you all! I would like to say thanks to the Adobe Flex team and the members of the Flex CAB who provided early access and support to the AIR 2.6 and Flash Builder 4.5 tools and documentation. Thank you as well to Mary Treseler from O’Reilly for providing this opportunity.
x | Preface
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. 1
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 ViewBased Application as shown in Figure 1-3 and leave the other settings to their defaults. 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. 2 | Chapter 1: Hello World
Figure 1-3. Select Application Template
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. 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. Create a Flex Mobile Project | 3
Figure 1-4. Set BlackBerry Tablet OS Permissions
4 | Chapter 1: Hello World
Figure 1-5. Server Settings
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. Flash Builder will now create your new project and, by default, the HelloWorldHome View.mxml will be created and opened in the workspace, along with the Hello World.mxml main application file (see Figure 1-7).
Create a Flex Mobile Project | 5
Figure 1-6. Application ID 6 | Chapter 1: Hello World
Figure 1-7. New Project has been created
Let’s update the contents of the HelloWorldHomeView.mxml by adding a Label.
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.
Create a Flex Mobile Project | 7
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
8 | Chapter 1: Hello World
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
Create a Flex Mobile Project | 9
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” on page 11 or “Setup Device” on page 14 to move forward with your testing. See Figure 1-13.
Figure 1-13. Add a Test Device
10 | Chapter 1: Hello World
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
Create a Flex Mobile Project | 11
Figure 1-15. Read IP Address
Figure 1-16. Complete Form with IP Address of Simulator