Migrating your application to BlackBerry 7

In this tutorial, you will learn how to migrate your application to BlackBerry® 7. We'll discuss some of the new features available of BlackBerry 7 devices, and the BlackBerry® Java® SDK.

By the end of this tutorial, you'll be able to:

Decide whether you need to migrate your app

Work with new BlackBerry 7 form factors and capabilities

Familiarize yourself with new APIs, such as NFC or the Send Menu API

Before you begin

This tutorial is for developers looking to migrate existing applications to BlackBerry 7. You should have a working understanding of Java programming, and developing for the BlackBerry platform. This tutorial won't cover how to develop a BlackBerry application. If you need to learn how to develop an application, see the following resources:

Java Sample Apps: Short, fully working applications included with the SDK which showcase a range of functionality.

Finally, you can't develop for the BlackBerry 7 without the BlackBerry Java SDK 7.0 installed. You can download the SDK at BlackBerry Developer Zone.

Getting started

This tutorial is less of a step-by-step guide as it is a series of recommendations for migrating your apps. As such, there's only one real requirement: make sure your app runs using the latest version of the BlackBerry Java SDK. It may be helpful to review the Release Notes to see if there are any major changes to classes or methods that your application uses, or if there are any known issues which might affect development.

Test your app in a BlackBerry Smartphone Simulator

Download a BlackBerry Smartphone Simulator

While you could use the BlackBerry® Smartphone Simulator included with the BlackBerry® Java® SDK 7.0, that only gives you one device screen resolution to work with. As we'll later see in this guide, BlackBerry® 7 devices come in a wide range of screen resolutions, most of which are rotatable. We'll have less work (and reworking) to do later on if we see how your app looks on as many simulators as possible up front.

Under Choose your OS, select 7.0. You should see the following appear below the drop-down menus:

Select 7.0.0.101. Don't worry if the last three numbers you see don't match the numbers here, as these vary between the simulators.

If prompted, log in to BlackBerry Developer Zone.

Click the Download button, and select a location to download the installer to.

Locate the file you've just downloaded and run it.

Follow the installation process, and you should have yourself a nice new simulator. If you want to download more simulators, simply select another BlackBerry 7 simulator from the drop-down menu and install it as well.

Load and run your application on a simulator

Now that we have a simulator, be sure to recompile your application using the BlackBerry 7 tools. To compile and package your application in Eclipse®
IDE:

In the Package Explorer select your application.

Navigate to BlackBerry > Package > Project(s)

This will produce a .cod file in your workspace. To load and run it on one of the simulators you downloaded:

Open up the BlackBerry Smartphone Simulator

Navigate to your Eclipse workspace to find your application's .cod file. It should be located in the folder: <your application's name>/deliverables/Standard/7.0.0/.

Navigate to your application's icon on the BlackBerry Smartphone Simulator home screen.

In all likelihood, your application is going to run just fine in BlackBerry 7. However, as you might have noticed, your application icon isn't how it normally looks. Among other things, the icon size has increased in BlackBerry 7. We'll learn about icon resolutions and more in the next section, Update your application for BlackBerry 7.

Update your application for BlackBerry 7

Icon guidelines

We have a problem: your application's icon is blurry, and too small. Before we make any changes or additions to your app, let's make sure your it compiles properly in the BlackBerry® Java® SDK 7.0, and uses the new UI guidelines for BlackBerry® 7 devices. Once you've done this, if there aren't any changes you want to make, you'll be able to submit to BlackBerry App World™.

All apps need an application icon. If your app sends notifications to the Home screen, it needs a Banner indicator. If your app displays notifications in the Title bar, then it needs a Title bar indicator. Be sure to include 2 pixels padding on the top and the right; meaning the total area of your title bar indicator is actually 23x23 pixels. Creating a 92x92 application icon is best, as you can then resize it down to small resolutions.

Dimensions and guidelines for BlackBerry 7 devices are as follows:

Create your icons as 24-bit .png files for maximum clarity and color accuracy on a BlackBerry device. For more information on icon creation, see the UI Guidelines for BlackBerry Smartphones. The UI guidelines also list best practices for designing application icons, such as leaving an appropriate amount of padding on all sides of the icon.

Adding a new icon

Once you've created your icon, you'll need to add it to your application. Adding an icon is the same process as it was in previous versions of the BlackBerry Java SDK.

Save your project, and package it from the BlackBerry > Package > Project(s).

When you load your application onto a BlackBerry® Smartphone Simulator, it should now look something like this:

If you don't want to make any further updates to your application, you can skip ahead to the last section, Submit your application to BlackBerry App World. Otherwise, continue onto the next section to learn about new device features and BlackBerry 7 device screen resolutions.

New device features

Once you're sure your app compiles as-is, it's time to begin updating it for BlackBerry® 7 devices. This section will go over new hardware capabilities, and how to work with them using the BlackBerry® Java® SDK.

Screen resolution

BlackBerry 7 devices come in a range of different screen resolutions. Though there are a number of simulator models available, the BlackBerry® Bold™
9900 and BlackBerry® Bold™
9930 are the devices to work towards. Currently, these are the only devices BlackBerry App World™ is accepting submissions for. Of course, the more compatible you make your app across all screen sizes, the more ease you'll have in submitting your app for all BlackBerry 7 devices in future.

Display resolution

Display physical size

Dot pitch (mm)

BlackBerry Bold
9900

BlackBerry Bold
9930

640 x 480 pixels (4:3 aspect ratio)

Rotated: 480 x 640 pixels (3:4 aspect ratio)

2.8 inches

0.0885

BlackBerry® Curve™
9360

480 x 360 pixels (4:3 aspect ratio)

2.44 inches

0.1035

BlackBerry® Torch™
9810

480 x 640 pixels (3:4 aspect ratio)

Rotated: 640 x 480 pixels (4:3 aspect ratio)

3.2 inches

0.1005

BlackBerry® Torch™
9850

480 x 800 pixels (9:15 aspect ratio)

Rotated: 800 x 480 pixels (15:9 aspect ratio)

3.7 inches

0.1005

First, you need to adapt your application for new screen resolutions. When reworking graphics for the new larger screens, ask yourself the following questions:

You'll notice in the above diagram that all the devices at all rotations share one thing in common: a minimum screen width of 480 pixels. Designing for a screen no wider than 480 pixels is your best option to maximize compatability accross devices. You may want to submit different versions (releases) of your application to BlackBerry App World™ to maximize usability and user experience across all devices.

Touch interaction

BlackBerry 7 devices offer a wide range of touch interactions:

Touch screen interfaces are a more natural way of interacting with objects and information. When designing for a touch screen, always keep in mind that your user's hands aren't transparent. If you place a button in the middle of the screen, their hands will block a large portion of the screen as they reach for it, possibly making your UI difficult to use. Put buttons and other interactive fields at the edges of the screen, and keep them as far apart as possible to prevent accidental clicking.

Using touch screen events hasn't changed in the BlackBerry Java SDK 7.0. Touch events are handled using the TouchEvent class, located in the net.rim.device.api.ui package. It's best to use a switch statement to respond to touch events, as you can locate all responses to all touch events in one method. You can also add more responses to more touch events without having to write an entirely new method. Let's listen and respond to a TouchEvent.CLICK (when a user taps the screen) as an example:

32-bit color

BlackBerry 7 devices support 32-bit color depth (24 bits for color, 8 bits for transparency). Though all BlackBerry 7 devices support 32-bit color, it's best to explicitly check that a device does, rather than assume. You can check whether a device supports 32-bit color using the DeviceCapability.getDisplayColorQuality() method. This method returns two constants, DeviceCapability.TRUE_COLOR, if the device supports 32-bit color, or DeviceCapability.HIGH_QUALITY otherwise.

We'll use an if statement, so that our application only takes action when the TRUE_COLOR constant is returned, indicating that the device supports 32-bit colors. Once we know whether it does or not, we can take an action; such as using the new Bitmap.createAlpha() method to create 32-bit color bitmaps for use in our apps on devices that support it.

Near field communication

You can check to see if NFC (near field communication) is available on a device, as well. The process is similar to checking whether a device supports 32-bit color or not. We'll use a pair of nested if statements to check for support, and then take action based on the results.

Note that we need to check both if NFC is supported, and if it's currently available. Think of an available feature like the virtual keyboard on a BlackBerry
Torch: the virtual keyboard is only available when it's being displayed to the user. It's always supported, however - that functionality is built into the software. Likewise, the NFC feature is only available when it comes into contact with another NFC tag, inducing a current. But, like the virtual keyboard, if a device has an NFC chip in it, NFC is always supported by the device. Because the state of the NFC feature fluctuates, we can use the new DeviceCapability.addNFCListener(DeviceCapabilityListener listener) method to listen for changes in NFC support for a device.

Whether a feature is available or unavailable can fluctuate quite often, and it's recommended that you only use the NFC feature when isNFCAvailable() returns a value of true.

The above code only checks if NFC is supported on a device. Once you've detected support for NFC, it's time to either read from the tag, or write to it. In addition, you can also emulate an NFC tag using a Near Field Communication device. Implementing NFC is a tutorial within itself, but the Near Field Communication section of the Networking and connectivity Development Guide walks through the process step-by-step.

High definition video support

BlackBerry 7 can record 720p high definition video. Their default camera setting is for 720p HD recording, but you can also record in at 640x480 pixels and 174x144 pixels. Videos are encoded using the H.264 Video codec at roughly 30 frames per section, and audio is encoded using the AAC-LC audio codec.

Magnetometer

Most BlackBerry 7 devices come with a Magnetometer sensor installed, which measures the strength and polarity of a magnetic field. This enables the Compass application, as well as directional context within mapping applications.

In addition to the obvious uses as a compass, incorporating Magnetometer functionality into your application has other benefits. For example, a photo sharing app could not only include the geographical location of where a photograph was taken, but the direction the photographer was taking it from. You can also use the Magnetometer to find the orientation and rotation of a device.

The Magnetometer API is located in the net.rim.device.api.system package. It's implemented in a similar way to the accelerometer API: you open a channel, receive data, and close it when you're ready. The entry point to using the Magnetometer sensor is the MagenetometerSensor class. Typically, you'll only want to retrieve data from a Magnetometer sensor periodically, as retrieving data constantly consumes battery life quickly, and takes too much space to store and buffer. It's best to use a while loop to handle this periodic checking. In addition, it's also recommended to use a dedicated thread for retrieving data, to prevent congestion of the main event thread.

But how can you tell if your application is detecting data correctly? In the BlackBerry® Smartphone Simulator, you can simulate this functionality using the Device Manipulator. Simulate > Manipulate Device... brings up the Device Manipulator. You can rotate the device by inputting numbers into the Rotation, Tilt and Dir. (direction) text fields, or you can simply drag the three colored rings to manipulate the device's orientation. In addition, you can record a series of motions and play it back, so you can monitor data and test on a more granular level, without worrying about generating manipulation data.

BlackBerry devices offer a vast range of functionality in all versions, of which this section is very much a high-level overview.

UI Component Development Guide: Displays the different kinds of fields, buttons and UI elements you can add to your application, as well as sample code for implementing.

Use 3D graphics

You can now create 3D graphics using the OpenGL®
ES 2.0 library. The library allows you to create and manage 3D shapes, shaders and textures, and renders them onto the screen. OpenGL
ES 2.0 functionality is located in the net.rim.device.api.opengles package.

In the next section, we'll look at the new APIs in the BlackBerry Java SDK 7.0.

Leverage new API features

Now that we've covered the new hardware features, let's look at the new features provided in the BlackBerry® Java® SDK.

One of the prime reasons for migrating your application is taking advantage of all the new functionality on BlackBerry® 7 devices. You don't need to implement any of these to have your app accepted into BlackBerry App World™. That said, they can introduce interesting and exciting new features exclusive to BlackBerry 7 devices.

It may be helpful to import the sample applications into your development environment of choice, as most of the below APIs and classes have an associated sample application.

These are just a small portion of the new features in the BlackBerry Java SDK 7.0. To see all the new features, see New in this release.

Layer UI controls

ComponentCanvas is a manager which extends the AbsoluteFieldManager class. Unlike AbsoluteFieldManager, however, it can be placed directly on top of other manager elements and fields.

You can use the new ComponentCanvas class to layer UI elements, such as buttons, on top of other fields, such as a video field. ComponentCanvas allows you to place elements at specific x-y coordinates on the screen, and allows you to overlap different fields. You can use ComponentCanvas in conjunction with the new 3D graphics libraries available to create augmented reality applications, or to overlay controls on a video player.

This will add a UI button to the ComponentCanvas 30 pixels from the left and 24 pixels from the top of the screen. Like all other managers, the only thing you can add to a ComponentCanvas is another field. The ComponentCanvas we've created is 480 pixels by 480 pixels. Regardless of where in your application you create ComponentCanvas, it is always drawn on top of all other fields and managers.

ComponentCanvas is located in the net.rim.device.api.ui.container package.

Create Send Menu items

You can use the Send Menu API to send files from your application with a contact. You can send media files, BlackBerry®
Messenger contacts text messages, and more without leaving your application. Only applications developed by Research In Motion will appear on a send menu.

For more information about the Send Menu API, as well as code samples, see Send Menu API in the Integration Development Guide.

Scan Barcodes

The BlackBerry Java SDK 7.0 now implements ZXing 1.6 for additional barcode scanning functionality and accuracy. You can use the library and the associated utilities to not only scan barcodes, but to generate barcodes as well. You can use these to store information (a website's URL, for example). Users can scan a barcode using the camera on their BlackBerry device. The ZXing library supports a number of 1D (lines) and 2D (matrixes, or QR codes) barcodes.

For more information about scanning barcodes, see Barcode scanning in the UI and Navigation Development Guide.

Updates to existing BlackBerry APIs

In addition to the above new features, some updates have been made to existing APIs and classes in the BlackBerry Java SDK for version 7.0. If your application uses these classes, it's a good idea to review this information and make sure your application will still function as expected on BlackBerry 7 devices.

The RIM Cryptographic API

If your application requires a FIPS-compliant AES implementation, you will now need to specify that explicitly.

BlackBerry 7 devices, by default, do not use FIPS-compliant AES implementations. All devices using BlackBerry® 6 or previous versions of the BlackBerry®
Device Software used a FIPS-compliant AES implementation by default.

Because of this, the AES implementation in the RIM® Cryptographic API has changed. Previously, a FIPS-validated version of the AES encryption algorithm was the default. In the BlackBerry Java SDK 7.0, the BlackBerry® device automatically chooses the AES encryption algorithm for best performance.

As of BlackBerry 7, the camera's default focus mode is no longer single-shot. The BlackBerry device's camera now automatically selects the best focus mode - usually continuous.

If your application relies on single-shot focus mode, use the following method: EnhancedFocusControl.setFoucsMode(String mode). There are three modes available, FOCUS_MODE_CONTINUOUS, FOCUS_MODE_FIXED, and FOCUS_MODE_SINGLESHOT.

You can check if a focus mode is supported on a BlackBerry device using the EnhancedFocusControl.isFocusModeSupported(String mode) method.

Submit your application to BlackBerry App World

Finally, it's time to submit your app to BlackBerry App World. BlackBerry App World is now accepting app submissions for the BlackBerry® Bold™
9900 and BlackBerry® Bold™
9930 devices. This section assumes that you've submitted an app to BlackBerry App World previously. If you need a refresher, see the Vendor Portal Administration Guide for BlackBerry App World.

To mark your apps as supporting new devices in the BlackBerry App World Vendor Portal:

Click Manage Products

Click the eye icon (view) icon under the Releases column for your app.

Click the pen (edit) icon next to the Release containing the bundle of your app to be edited.

Click on the Add Release Version tab.

Click on the pen (edit) icon under the Device Support column for the bundle you wish to edit.

There, you can select which BlackBerry 7 devices you want to support.

When submitting your app to BlackBerry App World, keep the following in mind.

Include all of the required fields when submitting. You can find the minimum requirements in this Knowledge Base Article.

If you're making your app available for over the air (wireless network) download, include the User Agent of the device.

Next steps

Congratulations! In this tutorial, you've learned how to work with new BlackBerry 7 form factors and device capabilities, the new BlackBerry® Java® SDK 7.0 API features, and have hopefully decided whether you need to update your application or not.

From here, the next step is to look more in-depth at new features to implement. The following resources may help: