Writing platform-specific features
Every porting project is a little different, but there are certain aspects that are likely to require some conversion work in every app. For example, many of your apps probably display information or UI elements on the screen, so you need to consider how to do that using BlackBerry 10 libraries. You should also consider how to handle events, such as touch events, orientation change events, and so on.
The following sections describe the areas that you should consider as you port your app to BlackBerry 10. These sections also include links to API references, tutorials, and other resources to help you learn about the available features and how to implement them in your app. For a full list of libraries that are included with, and supported by, the BlackBerry 10 Native SDK, see Library support.
Graphics and windowing
The BlackBerry 10 Native SDK includes low-level libraries, such as the BlackBerry Platform Services (BPS) Library and Screen Graphics Subsystem Library, that provide fundamental UI functions that allow you to draw on the screen. You can also use Cascades, which provides a high-level UI framework with a lot of flexibility and built-in UI controls. Several Qt libraries are also available for you to use; see Library support for the full list.
BlackBerry 10 also supports OpenGL ES. To use OpenGL ES in your apps, first initialize the underlying EGL library that sits between OpenGL and the hardware of the BlackBerry 10 device. The Create an OpenGL window and Create a basic 3-D application tutorials show you how to draw something on the screen. To learn more about using OpenGL ES, see OpenGL ES.
If you want to use OpenGL ES in your apps, you should take a look at the Glview Library as well. This library includes functions that make it simpler to work with OpenGL ES.
If you're working with images, the Image Library lets you manipulate image data by using input/output streams and provides functions to retrieve supported image codecs, encode and decode image frames, and load image data from files. For more information about working with images, including configuration details and step-by-step instructions, see Images.
For the main event loop in your app, you should use the event handling capabilities of the BlackBerry Platform Services Library. For different types of events (such as touch, orientation, payments, and so on), BlackBerry Platform Services allows your app to register for notifications and get information about event properties. Then, depending on the event domain, you can handle the event accordingly. You can also use the Input Events Library to detect and respond to events from other input devices.
For an example of how BlackBerry Platform Services allows your app to handle events, download the Momentics IDE for BlackBerry and create a BlackBerry Project using one of the Core Native Application templates.
Touch screen input
The primary input method on BlackBerry 10 devices is the touch screen, and your app will most likely need to respond to touch events, such as taps, pinches, or swipes. You can either convert your app's input method to use the touch capability that the BlackBerry Platform Services provides (for an example, see Responding to touch events) or use the more advanced features of the Gestures Library, such as gesture sets and event callbacks.
If you want to avoid changing your app's input handlers, you can use a third-party library, such as TouchControlOverlay, that can convert touch screen input into other forms of input that your app may already use. The TouchControlOverlay library provides a convenient way to port apps that were written for devices without a touch screen to a touch screen device. For instructions on how to use this library in your own apps, see the TouchControlOverlay wiki on GitHub.
The navigator controls how apps appear on the device, such as making them appear full screen or minimized. BlackBerry 10 has specific design principles for how users start, minimize, and close an app, as well as how they open the app menu. Your app should follow these principles to provide a familiar and consistent experience. To learn more about these principles, see the UI Guidelines for BlackBerry 10.
The navigator service, which is part of the BlackBerry Platform Services Library, allows your app to determine whether a user requested a full screen or thumbnail display of your app, and to detect menu and exit events. You can also use this API to open local files on the device and open URIs (including URIs that correspond to apps on the device).
There are two types of BlackBerry 10 devices: full-touch devices that use a virtual keyboard and devices with a physical keyboard. To display and hide the virtual keyboard, and to retrieve useful properties, such as the height of the keyboard, you can use the virtual keyboard service from the BlackBerry Platform Services Library. For an example on how to use the virtual keyboard, see the Create the Keyboard application tutorial.
BlackBerry 10 devices also include physical keys or buttons, typically on the top or side of the device, that are designed for easy access. These keys include the Volume up, Volume down, and Power/Lock keys. You can use the button service to detect when a user presses one of these keys and your app can respond appropriately.
You can use the various sensors on BlackBerry 10 devices as additional sources of input for your app. The sensor service from the BlackBerry Platform Services Library includes functions that let you read data from sensors, such as the accelerometer, magnetometer, and altimeter. For example, if you want to handle accelerometer input, the sensor service allows you to configure the refresh rate of the accelerometer as well read the G-forces for the x, y, and z axes of the device.
For an example of how to use the accelerometer, see the Create the Falling Blocks application tutorial or Reading accelerometer forces recipe, or try the Accelerometer sample app. To learn more about using other sensors, see Sensors.
If you want your app to respond to device rotation or you want to lock the orientation of the device to either landscape or portrait orientation, you can use the orientation service from the BlackBerry Platform Services Library. The Sensor Library also includes several functions that you can use to manage orientation changes.
The Reading orientation events recipe can give you an idea of how to detect and respond to changes in the orientation of the device.
Global Positioning System (GPS) technology on BlackBerry 10 devices allows your app to locate the device anywhere in the world. If you want to obtain the latitude, longitude, altitude, heading, and other geolocation properties of the device, you can use the geolocation service from the BlackBerry Platform Services Library. For an example of how to use geolocation, see the Accessing geolocation data recipe or try the Geolocation sample app.
There are also two specialized libraries that you can use to work with location information. The Geocoding Library lets you determine a geographic coordinate given a location (geocoding), and conversely, determine a location given a geographic coordinate (reverse geocoding). The Geofencing Library lets you create virtual perimeters for real-world geographic areas.
You have a few options for audio programming with BlackBerry 10. If you want to use a high-level API that abstracts out the low-level details, the multimedia renderer service from the BlackBerry Platform Services Library and the OpenAL library provide media control and playback status functions. OpenAL is a commonly used, open source library that is available on BlackBerry 10 and lets you generate full 3-D audio. It also includes the OpenAL utility library (ALUT), which is great if you want to load files with different sound formats (such as .wav, .au, .raw, and so on). You can also take a look at the Multimedia Library, which provides even more functions to control media playback.
For examples of how to play audio using the multimedia renderer service, see the Playing audio recipe or Play a .wav file tutorial. There are also sample apps that show you how to play an .mp3 file or a .wav file and query the audio device for volume, input gain, and mute status.
The Audio Manager Library allows you to set up and control audio devices and their properties, including device status, volume, routing, and concurrency. The audio mixer service from the BlackBerry Platform Services Library provides functions for your app to interact with the audio mixer, allowing your app to adjust input and output levels and mute audio. The audio device service allows your app to determine the status of the audio device, such as the number of channels available and whether it supports input and volume control. To play system sounds, such as key clicks, lock and unlock sounds, and the camera shutter, you can use the sound player service.
If you want to have direct, low-level control over audio buffers and the channels, you can use the QNX Sound Architecture (QSA) library, which is similar to the Advanced Linux Sound Architecture (ALSA) but isn't strictly compatible.
To play videos, you use can use the multimedia renderer service from the BlackBerry Platform Services Library or the Simple DirectMedia Layer (SDL) open source library (a port that works with the Native SDK is available on GitHub). SDL is a cross-platform, multimedia library that's designed to provide video drivers and low-level access to audio and 3-D hardware using OpenGL. You can also use functions that are included in the Multimedia Library.
For an example of how to play video using the multimedia renderer API, see the Play a video tutorial.
The Near Field Communication (NFC) capability of BlackBerry 10 allows you to initiate connections and share data between an NFC tag and a BlackBerry 10 device. The Near Field Communication Library provides functions that you can use to connect with NFC tags and exchange data in various formats.
To learn more about general NFC principles and how to integrate NFC into your apps, see Near Field Communication.
You can use Bluetooth technology to connect BlackBerry 10 devices with other Bluetooth enabled devices, such as headsets and speakers. The Bluetooth Library provides functions to manage connected devices, work with the Bluetooth Generic Attribute Profile (GATT) and Human Interface Device (HID) Profile, and use Bluetooth low energy features.
For more information about using Bluetooth features in your apps, see Bluetooth.
BlackBerry 10 devices can connect to Wi-Fi networks to exchange data and access the Internet. The Wi-Fi Service Library lets you determine the status of Wi-Fi connections and receive events for changes in Wi-Fi connectivity.
For an example of how to retrieve Wi-Fi status, see Networking. To learn how to integrate other Wi-Fi features into your apps, including how to develop a Wi-Fi hotspot aggregator app, see Wi-Fi service.
File system access on BlackBerry 10 devices is restricted to certain areas, and each app has a dedicated working folder. There is also the option to access folders that are shared across apps, using a property set in the bar-descriptor.xml file. File access is governed by groups and permissions similar to how they are governed in UNIX.
For more information about the file system, see File system access.
BlackBerry 10 supports POSIX threads but has no link-time, pthread-specific threads. Some POSIX systems use –pthread or –lpthread, so if your app uses them, you may need to configure your build to handle them. You can learn about threads by reading Processes and Threads in the Get Programming with the BlackBerry 10 OS guide.
There are other guides available that can help you understand the fundamental concepts of the BlackBerry 10 OS, including memory management, clocks and timers, and message-passing services. Take a look at the Using low-level functionality section to read these guides.
Last modified: 2014-11-17