Bringing your BlackBerry PlayBook apps to BlackBerry 10

How-to

While all the SDKs for BlackBerry® 10 are amazing, our pride and joy is the BlackBerry 10 Native SDK. If you’ve built native apps for the BlackBerry® PlayBook™ tablet, then you’ve used our BlackBerry Native SDK for Tablet OS. The new BlackBerry 10 Native SDK has the same underlying framework as the NDK platform and exposes many new APIs and tooling that will make your development experience even better. If you haven’t had a chance to download and write apps for the BlackBerry PlayBook tablet yet, now is a great time to start building some apps.

One of our priorities is to make sure that apps written with the BlackBerry Native SDK for Tablet OS will transition with minimal hassle to our BlackBerry 10 platform. We don’t want you, our developer community, to have to reinvent the wheel or tweak significant amounts of code. We also want to make sure that our developers are aware of changes coming to the platform that may impact them so they can prepare accordingly. With that in mind, I want to talk about two important upcoming changes to the BlackBerry 10 Native SDK in order to help developers prepare for upcoming releases. The motivation for both changes is to help developers scale their apps from tablets to phones.

The first change has to do with multi-icon support. We want to create a seamless way for developers to port their BlackBerry PlayBook tablet applications to the BlackBerry 10 smartphone. As we support two device screen sizes, applications may need to provide more than one icon size depending on the device they are being installed on. Developers will now be able to specify a list of icons and splash screens per locale and per resolution in the bar descriptor. These would be of various sizes to suit the different target displays. The runtime will then choose the icon and splash screen that matches the given display. We will be maintaining backwards compatibility, so existing apps written for the BlackBerry PlayBook tablet should not have to modify anything. However, if you are moving your app to a BlackBerry 10 device, you will have to specify icons and splash screens with alternate sizes.

The second important change is with respect to orientation. On BlackBerry 10, native applications will not be able to get the width and height values that they need for sizing their windows and determining orientation by querying the ‘WIDTH’ and ‘HEIGHT’ environment variables. If the width is greater than the height, the application will know it is running in landscape mode and vice versa. This behaviour has changed from BlackBerry PlayBook OS 2.0. On BlackBerry PlayBook OS 2.0, an application would query the screen APIs to get its width and height. For applications running on BlackBerry PlayBook OS 2.0, they can continue to rely on this behaviour as this is now going to change. On BlackBerry 10, however, applications are discouraged from querying for their width and height using the screen APIs. The following code snippet illustrates how an app can query for its width and height:

int screen_resolution[2];
screen_resolution[0] = atoi(getenv("WIDTH")); //get width
screen_resolution[1] = atoi(getenv("HEIGHT")); //get height

Once the application gets these values (which it can and should do at startup), the application can proceed to create and set up its window.

screen_create_window(&window, context);
rc = screen_set_window_property_iv(window,
SCREEN_PROPERTY_SIZE, screen_resolution);
if (rc) {
//handle error …
}

rc = screen_set_window_property_iv(screen_win,
SCREEN_PROPERTY_BUFFER_SIZE, screen_resolution);
if (rc) {
//handle error …
}

Applications written for BlackBerry 10 should not set the SCREEN_PROPERTY_ROTATION value, as Navigator will set this for the application automatically when it posts its window.

Furthermore, if you were writing native apps on BlackBerry PlayBook OS 2.0, you would have had to write extra logic to rotate your window based on what you read out from the “ORIENTATION” environment variable. The box below shows an example of how orientation was set up in the BlackBerry PlayBook OS 2.0 setup. This code can now be removed, thereby simplifying your setup logic.

//THIS CODE CAN NOW BE DELETED

int angle = atoi(getenv(“ORIENTATION”));
int buffer_size[2] = {screen_resolution[0], screen_resolution[1]};
int flip = false;

if ((orientation == LANDSCAPE) && (buffer_size[0] <
buffer_size[1])) {
//In landscape, rotate to portrait
buffer_size[0] = screen_resolution[1];
buffer_size[1] = screen_resolution[0];

if ((angle == 0) || (angle == 180)) {
//Landscape device in landscape mode
angle = 90;
} else if ((angle == 90) || (angle == 270)) {
//Portrait device in landscape mode
angle = 0;
}

flip = true;
}

if (flip) {
rc = screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_ROTATION,
&angle);
if (rc) {
//handle error …
}

rc = screen_set_window_property_iv(screen_win,
SCREEN_PROPERTY_BUFFER_SIZE, buffer_size);
if (rc) {
//handle error …
}
}

When it comes to determining current orientation, applications should always rely on the navigator to present current orientation. You should never use the accelerometer to determine orientation. The navigator will also inform the application when it needs to rotate and will initiate the rotation sequence by sending the application a rotate (PORTRAIT or LANDSCAPE) message. These new “rotate” messages are replacing the “orientation” messages on the current 2.0 Navigator. It is to be noted as well that the old orientation messages used to specify rotation in angles, while rotation will be specified as Landscape or Portrait in the new messages. These new units are much more intuitive in my opinion and map more closely with how we think of orientation on the device.

As a native app developer, there are several things you need to consider:

  • Continuing to support your application on BlackBerry PlayBook OS 2.0 won’t require any change – things will continue to work as before.
  • If you are developing a native app only for BlackBerry 10, you should make sure to use the new method of getting width and height parameters from navigator as well as using the new rotate messages.
  • If you already have an app on BlackBerry PlayBook OS 2.0 and want to move it to BlackBerry 10, you will have some minor changes to make to port your app over. Your code on BlackBerry PlayBook OS 2.0 will not be able to get the width/height parameters via environment variables, so you will continue to use the old methods. On BlackBerry 10, you should use the parameters you receive from navigator for this.

These changes are not drastic, and our hope is that you will be able to migrate from BlackBerry PlayBook OS 2.0 to BlackBerry 10 with minimal fuss. In passing, I should also point out that these changes target developers who are writing applications right on top of our low-level windowing framework, so these changes mainly impact game developers. If you are writing a Cascades™-based application, you should also be abstracted from most of these changes and should consult your Cascades documentation.

I am personally excited about these changes as they will enhance the development capabilities of the BlackBerry 10 Native SDK when it comes to supporting multiple resolutions and orientation. When the time comes for you to start developing or moving your app or game over to the BlackBerry 10 platform, you should definitely consult the developer documentation for more details on these two features and how they will impact your application.

Happy developing!

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus