Porting apps from the BlackBerry PlayBook

There are some things to consider when porting your application from the BlackBerry Tablet OS to the BlackBerry 10 OS. The good news is that the BlackBerry 10 Native SDK supports every API that came with the BlackBerry Native SDK for Tablet OS. Your application will continue to work as before. The better news is that the BlackBerry 10 Native SDK offers additional features, APIs, and development tools that you can use to bring the full power of BlackBerry 10 to your application. This means you can focus on taking advantage of all that BlackBerry 10 has to offer without worrying about whether your application will be supported.

To begin the porting process, you must first download the BlackBerry 10 Native SDK. After it's installed, you can import your existing code and start testing the application. Depending on the features of your application, you can refer to the following sections to learn more about the differences between the BlackBerry Tablet OS and the BlackBerry 10 OS:

  • Support for open source libraries
  • Graphics
  • Multimedia
  • Input and sensors
  • Connectivity
  • Social
  • Application control
  • User interface

Support for open source libraries

In addition to continuing support for all the open standards and libraries you know and love, like OpenGL, OpenAL, Ogg Vorbis, and Cocos2D-X, BlackBerry 10 supports additional libraries to help you port your application. For a complete list of supported libraries, see Library support at a glance.

The BlackBerry 10 Native SDK also supports the gameplay framework, an open source, cross-platform 3-D engine that helps you learn and develop mobile and desktop games.

Graphics: GLView library

The GLview library makes it easier to develop applications that use OpenGL ES 1.1 or 2.0. It helps you manage all the things you need to do to get OpenGL ES running. The GLview library provides an efficient and simplified execution loop that you can use to eliminate low-level EGL and Navigator set up code by registering callbacks for initialization, orientation change handling, display rendering, and buffer swap events.

Graphics: Retrieving screen height and width

To retrieve the height and width of the screen on devices that run BlackBerry 10, your application should query the HEIGHT and WIDTH environment variables. You should no longer use the screen APIs to get this information.

You can use the following code sample to retrieve the height and width of the screen:

int screen_resolution[2];
screen_resolution[0] = atoi(getenv("WIDTH")); //get width
screen_resolution[1] = atoi(getenv("HEIGHT")); //get height
Note that these environment variables will not work for BlackBerry PlayBook applications.

If you are using the GLview library, you can call glview_get_size() to retrieve the screen size.

Graphics: Texture compression

The BlackBerry 10 device uses the same hardware as the BlackBerry PlayBook tablet: a Texas Instruments OMAP 4430 processor combined with the PowerVR SGX540 GPU from Imagination to deliver stunning graphics performance. This GPU supports the PVRTC format natively.

Multimedia: Changes to supported formats

There is additional support for multimedia formats, codecs, and streaming protocols that was not present on the BlackBerry PlayBook tablet. The new formats are:

  • AVC-HD
  • FLAC
  • Motion JPEG
  • OGG (supported by multimedia renderer and the media player application only)
  • TIFF
The new codecs are:
  • AC-3 (Dolby Digital Plus)
  • FLAC
  • Ogg Vorbis (supported by multimedia renderer and the media player application only)
The new streaming protocols are:
  • HTTP Live Streaming (version 3.0)
  • RTP/RTSP
Digital Rights Management also gets additional support for:

Multimedia: Changes to APIs

The BlackBerry 10 Native SDK adds two APIs that gives you more control over the playback of media files. Mediacontroller.h provides functions for playlist control (next track, previous track), volume control, and accessing the metadata of media being played. Mediaplayer.h provides functions for changing playback state, accessing the duration and position values of the playback, and setting the metadata for media.

The multimedia renderer has an additional event API that exposes data types for event information and functions to monitor and process events. If your application requires low-level, multimedia event handling outside of BlackBerry Platform Services, this API is the one to choose.

Input and sensors: Supporting device orientation changes

The biggest change with input and sensor handling has to do with orientation changes: your application code for the BlackBerry 10 OS is much simpler than it was on the BlackBerry PlayBook tablet. The navigator on the BlackBerry 10 OS handles the entire application window lifecycle and matches the application's orientation with the device orientation. Orientation is now reported as PORTRAIT or LANDSCAPE, instead of angular measurements, and the default orientation on start up (assuming you haven't specified one) is portrait. Your application should use the navigator to receive and handle orientation change events as follows:

  1. Register for orientation change events
  2. Once the device starts rotating, the navigator sends a message to your application with either LANDSCAPE or PORTRAIT and the rotation edge as the data
  3. Once your application is ready to rotate, it informs the navigator, which then initiates the rotation sequence
  4. Your application is notified of the rotation, resizes its window buffers accordingly, and redraws its updated window
  5. Your application informs the navigator that it's finished handling the rotation
  6. The navigator completes the rotation of the device (such as rotating other applications) and sends a message to your application
You should no longer use the screen library to set the SCREEN_PROPERTY_ROTATION value, as the navigator will set this automatically when it posts its window.

Connectivity

BlackBerry 10 offers several options to connect your app to the outside world. Here are two new APIs available to you:

  • Bluetooth: provides Bluetooth communication, device management, profiles, and low-energy functionality to your app
  • Near Field Communication (NFC): provides functions to allow your app to communicate with payment systems, smart posters, physical access controls, and other BlackBerry 10 devices

Social: BBM Social Platform

The BlackBerry 10 Native SDK supports the BBM Social Platform. You can use the BBM Social Platform APIs to connect instances of your application running on different BlackBerry devices around the world. With these connections, users can invite each other to play games, chat, and send data between application instances. The BBM Social Platform APIs also provide application to application communication, so you can transport data between applications without building your own platform.

Application control: Changes to APIs

The new invocation framework service allows your application to launch another application and pass data, such as opening a media player to play video or opening an email client to send a message. Using this framework, your application can invoke other applications or allow itself to be invoked to transfer data, support additional functionality, etc.

You can use the notifications API to control the various notification methods of the BlackBerry 10 OS. This includes sound alerts, the LED light, application icon badges, toasts, and adding items to the universal inbox.

Application control: Changes to application permissions

The complete list of application permissions for the BlackBerry 10 OS is listed here. To update the permissions required for your app, consider the following changes:

  • the run_when_backgrounded permission allows you to perform background processing
  • the bbm_connect permission provides access to the BBM Social Platform
  • the access_pimdomain_calendars, access_pimdomain_contacts, access_pimdomain_messages, and access_pimdomain_notebooks permissions provide access to calendar, contacts, email and PIN messages, and notebooks on the device
  • the access_sms_mms permission allows you to access text messages stored on the device
  • the play_audio permission is not required
  • the read_geolocation permission is not available, instead use access_location_services
  • the set_audio_volume permission is not required
  • the post_notification permission allows you to post notifications to the notification area of the screen

User interface guidelines

The user experience for BlackBerry 10 has changed significantly from the experience on the BlackBerry PlayBook tablet. Creating a cinematic experience, having fluid workflows, and emphasizing high performance are just some of the key principles that BlackBerry 10 applications should follow. The BlackBerry 10 UI Guidelines cover these principles and specify design, interaction, and style guidelines for your app.

User interface: Application icon size

The application icon is your opportunity to showcase your application to users. The recommended application icon size for BlackBerry 10 devices is 114 x 114 pixels. This is different than the recommended application icon size for the BlackBerry PlayBook tablet (86 x 86 pixels). For more information on icons, visual style, and best practices, see the BlackBerry 10 UI Guidelines.

User interface: Support for multiple application icons and splash screens

The BlackBerry 10 Dev Alpha and the first BlackBerry 10 device support a 1280 x 768 screen resolution. Future BlackBerry 10 devices will support two screen sizes: 1280 x 720 (16:9) for full touch screen devices, and 720 x 720 (1:1) for devices with a physical keyboard. Applications should provide an icon and splash screen that supports both screen sizes so that they look consistent across devices. You specify icons and splash screens in the BAR application descriptor file and you can add them for each supported screen resolution. The BlackBerry 10 OS chooses the correct icon and splash screen to use based on the device that the application is running on.