Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Tutorial: Migrate your app to version 7

This tutorial shows you how to migrate your app to BlackBerry 7. We'll discuss some of the new features available on BlackBerry 7 smartphones and in the BlackBerry Java SDK.

By the end of this tutorial, you'll be able to:
  • Decide whether you want to migrate your app to version 7
  • Work with new BlackBerry 7 form factors and capabilities
  • Familiarize yourself with new APIs, such as NFC and 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 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:

  • Getting Started: A brief introduction to working with the BlackBerry Java SDK, including API overviews and sample code.
  • UI Sample Apps: Short, fully working applications included with the SDK that showcase a range of functionality.

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

Getting started

This tutorial is not a step-by-step guide; it's more 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 New Features 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, that only gives you one device screen resolution to work with. As we'll see later in this tutorial, 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.

To download the BlackBerry Smartphone Simulator, follow the instructions in the BlackBerry Smartphone Simulator guide.

Follow the installation process, and you should have yourself a nice new simulator. If you want to download more simulators, 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:

  1. In the Package Explorer select your application.
  2. 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:

  1. Open up the BlackBerry Smartphone Simulator
  2. Navigate to your Eclipse workspace to find your application's .cod file. For example, it could be located in the folder: <your application's name>/deliverables/Standard/7.1.0/.
  3. 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

Icon guidelines


Comparison of an old icon with BlackBerry 7 icons.

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 BlackBerry Java SDK 7, 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 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:


Image outlining ideal dimensions for BlackBerry 7 icons.

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 BlackBerry Java SDK.

  1. In Eclipse, open your application's BlackBerry_App_Descriptor.xml file.
  2. Under application icons, select Add and navigate to your icon's .png file.
  3. 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:


Screen shot of updated app with icon resized for BlackBerry 7.

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 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 discusses 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. The more compatible you make your app across screen sizes, the more ease you'll have in submitting your app for all BlackBerry 7 devices in future.


Comparison of the different screen resolutions of BlackBerry 7 devices.

 

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

You'll notice in the diagram above 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 World to maximize usability and user experience across all devices.

Touch interaction

BlackBerry 7 devices offer a wide range of touch interactions:


illustration of the supported 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 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:

Code sample: Listen for a touch event

protected boolean touchEvent (TouchEvent message) {
   switch(message.getEvent()) {
      case TouchEvent.CLICK:

         //Do something

         return true;
   }
   return false; 
}

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.

Code sample: Check a device's display color quality

public void checkColorQuality() {

     if (DeviceCapability.getDisplayColorQuality() == 
                 DeviceCapability.TRUE_COLOR)
					{
        //Do something
     }
}

Near field communication

You can check to see if NFC 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.

Code sample: check to see if a device supports NFC

public void checkNFC() {
     if (DeviceCapability.isNFCSupported()) //first, check if the device supports NFC. 
     {
         if (DeviceCapability.isNFCAvailable()) //next, check if it's available
         {
              //Do something
         }
     }
}

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 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 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.

For more information about working with high definition video, see Multimedia.

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.


Screen shot of the magnetometer.

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.

Code Sample: Retrieve Magnetometer data

 public void run()
 {
     // Open channel.
     Channel magChannel = MagnetometerSensor.openChannel( Application.getApplication() );
     
     while( running ) {
         // Read raw magnetometer data.
         double direction = 0;
         MagnetometerData data = magChannel.getData();
         synchronized( data ) {
             direction = data.getDirection();
         }    
         // Process the direction.
         process( direction );
         // sleep for maintaining query rate
         Thread.sleep( 500 );
     }
     // Close the channel to stop the sensor query routine.
     magChannel.close();
 }
 

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.


Screen shot of the simulator's Device Manipulator.

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

  • UI Guidelines - BlackBerry Smartphones: A detailed explanation of UI standards, guidelines, and recommendations for working with BlackBerry devices.
  • UI components: 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.

For more information about using 3D graphics, see Graphics. The net.rim.device.api.opengles API Reference also contains useful information about implementing 3D graphics.

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 isto take 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 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, as most of the APIs mentioned in this section 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 Features.

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.


Example of layered UI controls.

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.

Code Sample: Use ComponentCanvas

public void createComponentCanvas() {

    	ComponentCanvas canvas = new ComponentCanvas(480, 480);
    	ButtonField canvasButton = new ButtonField("A Button");

    	canvas.add(canvasButton, 30, 24);
    	
    }

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.


Example of the Send menu.

For more information about the Send Menu API, as well as code samples, see Menu items.

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.

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.

For more information about the RIM Cryptographic API, see the Security.

SQLite

Two major changes have been made to SQLite:
  • SQLite has been upgraded to version 3.7.2. This brings new functionality, such as the support of language collation.
  • The underlying implementation of SQLite has been customized, and now runs as a service. This can greatly improve performance, but means that database operations now use a runtime bridge to transfer data between Java and native code.

The changes to SQLite may require you to make significant changes to the design of your application's code.

For a more in-depth look at the functionality now available, see the Data Storage.

Camera focus mode changes

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 app to BlackBerry World

Finally, it's time to submit your app to BlackBerry World. This section assumes that you've submitted an app to BlackBerry 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:

  1. Click Manage Products
  2. Click the eye icon (view) icon under the Releases column for your app.
  3. Click the pen (edit) icon next to the Release containing the bundle of your app to be edited.
  4. Click on the Add Release Version tab.
  5. 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 World, keep the following in mind.

  • Include all 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 features, and have hopefully decided whether you want 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: