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:

  • UI and graphics
  • Event handling
  • Touch screen input
  • Application control
  • Virtual keyboard
  • Accelerometer
  • Geolocation
  • Orientation
  • Audio
  • Video
  • File I/O
  • Threads

UI and graphics

The Native SDK includes low-level libraries, such as BlackBerry Platform Services and 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 Open Source Components). The other key thing in the area of UI and graphics is that the BlackBerry PlayBook tablet supports OpenGL ES.

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

Device image showing the 3-D sample app.

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 of how BlackBerry Platform Services allows your application to handle events, you can look at the BlackBerry Tablet OS OpenGL ES 1.1 Application Template Project in the QNX Momentics IDE.

Touch screen input

The primary input method on BlackBerry PlayBook tablets 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 the BlackBerry Platform Services provides (a recipe describing touch handling is 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 the applications. The BlackBerry PlayBook tablet has specific design principles for how users start, minimize, 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 thumbnail view, and to detect menu and exit events.

Device image showing the mimimized video playback window.

Virtual 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 of how to use the virtual keyboard, you can look at the Keyboard tutorial.

Accelerometer

You can use the accelerometer as another source of input for your application. If you want to handle accelerometer input, 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 of how to use the accelerometer, you can look at the Falling Blocks tutorial, or the Reading accelerometer forces recipe.

Geolocation

The GPS of the BlackBerry PlayBook tablet 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 of 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 orientation, 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 PlayBook tablet.

Audio

You have a few options for audio programming on the BlackBerry PlayBook tablet. 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 status functions for playback. OpenAL is a commonly used, open-source library that is available on the BlackBerry PlayBook tablet 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 of 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 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 of how to play video using the multimedia renderer API, you can look at the Play a video tutorial.

File I/O

File system access on the BlackBerry PlayBook tablet 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 and here.

Threads

The BlackBerry Tablet 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.