Write platform-specific features

Every porting project is a little different, but the following aspects of every application are likely to require some conversion work:

  • Graphics and windowing
  • Event handling
  • Touch screen input
  • Application control
  • Keyboard
  • Accelerometer
  • Geolocation
  • Orientation
  • Audio
  • Video
  • NFC
  • File I/O
  • Threads

Graphics and windowing

The Native SDK includes low-level libraries, such as BlackBerry Platform Services and Screen (screen.h), that provide fundamental UI functions that allow you to draw on the screen. There are no higher-level UI libraries provided, but Qt has been ported and is available (see Library support at a glance). The other key thing in the area of UI and graphics is that BlackBerry 10 supports OpenGL ES.

To use OpenGL ES, first initialize the underlying EGL library that sits between OpenGL and the hardware of the BlackBerry 10 device. The Create an OpenGL window and the Create a basic 3-D application tutorials show you how to initialize and draw something on the screen.

Device image showing the Native SDK 3-D rotating cube sample.

Event handling

For the main event loop in your application, you should use the event handling capabilities of the BlackBerry Platform Services. For different types of events (touch, orientation, payments, etc.), BlackBerry Platform Services allows your application to register for notifications and get information about event properties. Then, depending on the event domain, you can handle the event accordingly. For examples on how BlackBerry Platform Services allows your application to handle events, you can look at the BlackBerry 10 OpenGL ES 1.1 Application Template Project in the Momentics IDE.

Touch screen input

The primary input method on BlackBerry 10 devices is the touch screen, and your application will most likely need to respond to touch events, such as taps, pinches, or swipes. You can either convert your application's input method to use the touch capability that theBlackBerry Platform Services provides (you can download a recipe describing touch handling here) or use the more advanced features of the Gestures Library, such as gesture sets and event callbacks.

If you want to avoid changing your application'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 application may already use. The main goal of TouchControlOverlay is to provide a convenient way to port applications that were written for non-touch screen devices onto a touch screen device. You can follow the instructions here to learn how to use it in your own application.

Application control

The navigator controls how applications appear on the device, such as making them appear full screen or minimized, as the user chooses between them. BlackBerry 10 has specific design principles for how users start, minimize, and exit the application, and open the application menu. Your application should follow these principles to provide familiarity and a consistent experience. The navigator.h API allows your application to determine whether a user requested full screen or thumb nailed, and to detect menu and exit events.

Device image showing the minimize video playback window.

Keyboard

There are two types of BlackBerry 10 devices, full-touch devices that use a virtual keyboard and devices with a physical, QWERTY keyboard. To display and hide the virtual keyboard, and to retrieve useful properties, such as the height of the keyboard, you can use the virtualkeyboard.h API from the BlackBerry Platform Services. For an example on how to use the virtual keyboard, you can look at the Create the Keyboard application.

Accelerometer

You can use the accelerometer as another source of inputs for your application. If you want to handle accelerometer inputs, use the sensor.h API from the BlackBerry Platform Services. It 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 on how to use the accelerometer, you can look at the Create the Falling Blocks application, the Reading accelerometer forces recipe, or try the Accelerometer sample application.

Geolocation

The GPS of the BlackBerry 10 device allows your application 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, use the geolocation.h API from the BlackBerry Platform Services. For an example on how to use geolocation, you can look at the Accessing geolocation data recipe or try the Geolocation sample application.

Orientation

If you want your application to respond to device rotation or you want to lock the orientation of the device to either landscape or portrait mode, you can use the orientation.h API from the BlackBerry Platform Services. The Reading orientation events recipe can give you an idea of how to detect and respond to changes in orientation of the BlackBerry 10 device.

Audio

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 API 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 in files with different sound formats (.wav, .au, .raw, etc.).

For an example on how to play audio using the multimedia renderer API, you can look at the Playing audio recipe. There are also sample applications that show you how to play an .mp3 file, 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 audiomixer.h API of the BlackBerry Platform Services provides functions for your application to interact with the audio mixer, allowing your application to adjust input and output levels and mute audio. The audiodevice.h API allows your application 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 soundplayer.h API from the BlackBerry Platform Services.

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 very similar to the Advanced Linux Sound Architecture (ALSA) but isn't strictly compatible.

Video

To play videos, you use can use the multimedia renderer API or the Simple DirectMedia Layer open-source library (a port that works with the Native SDK is available here). Simple DirectMedia Layer is a cross-platform, multimedia library designed to provide video drivers and low-level access to audio and 3-D hardware using OpenGL.

For an example on how to play video using the multimedia renderer API, you can look at the Play a video tutorial.

NFC

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. You can look at the NFC API to learn how to use this capability.

Data management

File system access on BlackBerry 10 devices is restricted to certain areas, and each application has a dedicated working folder. There is also the option to access folders that are shared across applications, 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 layout, you can look here.

Threads

The BlackBerry 10 OS supports POSIX threads but has no link-time, pthread-specific threads. Some other POSIX systems use –pthread or –lpthread, so if your application uses them, you may need to configure your build to handle them.

Last modified: 2013-12-21



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus