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:
- Download and install the BlackBerry 10 Native SDK.
- 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
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.
BlackBerry 10 offers several options to connect your app to the outside world. Here are two new APIs available to you:
Supporting 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:
- Register for orientation change events
- 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
- Once your application is ready to rotate, it informs the navigator, which then initiates the rotation sequence
- Your application is notified of the rotation, resizes its window buffers accordingly, and redraws its updated window
- Your application informs the navigator that it's finished handling the rotation
- 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.
Graphics and windowing
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.
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 API to get this information.
You can use the following code sample to retrieve the height and width of the screen:
int screen_resolution; screen_resolution = atoi(getenv("WIDTH")); //get width screen_resolution = 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.
The BlackBerry Z10 smartphone (chipset A) 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.
The BlackBerry Z10 smartphone (chipset B) and the BlackBerry Q10 smartphone use the Qualcomm Adreno 225 GPU.
The BlackBerry Z30 smartphone uses the Qualcomm Adreno 320 GPU.
For more information on the graphics processors and their properties, see Find out hardware information
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.
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:
- Motion JPEG
- OGG (supported by multimedia renderer and the media player application only)
- Ogg Vorbis (supported by multimedia renderer and the media player application only)
- HTTP Live Streaming (version 3.0)
- OMA 1.0 Forward Lock (for .mp3 media only)
- Microsoft PlayReady
Changes to APIs
The BlackBerry 10 Native SDK adds two APIs that gives you more control over the playback of media files.The Media Controller API (mediacontroller.h) provides functions for playlist control (next track, previous track), volume control, and accessing the metadata of media being played. The Media Player API (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.
Changes to APIs
Applications that ran on BlackBerry Tablet OS could launch another application or pass data using navigator_invoke(). For example, you could pass a URL to open the media player to play music or open an email client to send a message.
The new invocation framework on BlackBerry 10 provides the same capability. On BlackBerry 10, the navigator_invoke() function is deprecated and you must not use it. Instead, you must change your code to use the APIs available for the invocation framework - namely the Invoke API (navigator_invoke.h). The Invoke API allows your application to launch other applications and allows itself to be launched to transfer data or expose additional functionality. For more information about using the invocation framework, see App Integration (navigator_invoke.h).
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.
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.
Application icon size
The application icon is your opportunity to showcase your application to users. The recommended icon sizes for BlackBerry 10 devices are different than the recommended application icon size for the BlackBerry PlayBook tablet (86 x 86 pixels). The recommended application icon sizes for BlackBerry 10 devices are as follows:
- 114x114 (pixels) for devices that have a screen resolution of 720x720 or 768x1280 (such as the BlackBerry Q10 and BlackBerry Z10 smartphones)
- 96x96 (pixels) for devices that have a screen resolution of 720x1280 (such as the BlackBerry Z30 smartphone)
Support for multiple application icons
The BlackBerry 10 OS chooses the correct icon to use based on the device that the application is running on. You specify the icon images to use in the BAR application descriptor file (bar-descriptor.xml).
Screen resolutions and splash screens
You specify the splash screen images to use in the BAR application descriptor file (bar-descriptor.xml). If the expected size for the splash screen doesn't match the device at runtime, the splash screen is chosen based on a best-fit algorithm for the device and is upscaled as required. For optimal presentation of your splash screen, you should provide images that match the resolutions (in pixels) that are available for various BlackBerry 10 devices:
- 768x1280 (15:9) for full touch screen devices such as the BlackBerry Z10 smartphone
- 720x1280 (16:9) for full touch screen devices, such as the BlackBerry Z30 smartphones
- 720x720 (1:1) for keyboard devices, such as the BlackBerry Q10 smartphone
Last modified: 2013-10-30