Porting BlackBerry Z10 Apps to the Q10

For those who've never built BlackBerry 10 apps before, Cascades is the Qt-based UI framework for creating native visual applications on the BB10 platform (HTML5 is the principal non-native option). To get started with Cascades, head over to BlackBerry's developer site for instructions. After downloading the SDK, go to the Getting Started tab (under the Documentation tab) and check read the Introduction and Environment setup instructions.

The IDE is QNX's Momentics, an Eclipse-based tool suite that comes with all the BB10 goodies out of the box. You get two new perspectives tailored to BlackBerry development; the Qt Modeling Language (QML) Editing perspective and the QNX System Information perspective. QML is a language heavily based on JavaScript. In fact, it has a built-in JavaScript interpreter, so you can write JavaScript almost everywhere in QML. Figure 1 shows its place in the stack for the code I'll show in this article.

Figure 1: The development stack.

Cascades is used to create visual applications using C++ and/or QML. It's worth mentioning that Cascades is built directly on top of the BlackBerry 10 native SDK, so anything you need from the native SDK is also available.

Testing

To test your applications, you need either the simulator or an actual device. The simulator is a VMWare image, so you have to obtain a suitable player first. There are a few things to know about each environment: In the simulator, you do not have access to every feature. For example, there's no access to the phone API, nor is there full video codec support. If you opt to test on a real device, you'll need to go through an app-signing process and debug-token creation. Despite the hassle, if you can get your hands on a device, you should opt for that.

What's Different on the Q10?

In terms of development and environment, working with the Q10 is the same as for the Z10, except that you'll need to use the Dev Alpha C simulator if you are working with a simulator. Double check to ensure your app's screens display correctly on the Q10's square display. Also, be sure to remember BlackBerry power users: Consider their keyboard shortcut expectations.

The less conspicuous things you'll need to think about are the display technology (OLED) and pixel density.

1:1 Aspect Ratio

The Q10's screen dimensions are 720px by 720px. With this reduced vertical real estate, you want to limit the amount of vertical space your items take. Things such as margins and padding should be kept to the barest essentials. If you have listviews with large items, you should consider creating shorter versions of them for vertically restrained views. You'll also want to have less static chrome, so anything that doesn't need to be kept on the screen should scroll away or hide itself when not required.

If you're porting your app from the Z10 and did your homework before writing your QML, especially around layouts, you shouldn't have much trouble. Adapting your views to the 1:1 aspect ratio is mostly a straightforward layout exercise. The homework you should have done (and continue to do) includes:

1. Avoid AbsoluteLayout (use StackLayout and DockLayout instead)
2. Controls designed with StackLayout can specify relative space needs (in relation to siblings) by using the spaceQuota property of their layoutProperties
3. Avoid hard coding widths and heights
4. Minimize vertical real estate usage
5. Wrap anything that doesn't fit vertically in a ScrollView

Hopefully, you'll be able to write your code in a screen-size independent way, but in case you can't and need to have device-specific assets, you can always make use of the static asset selector shown in Figure 2.

Figure 2: The static asset selector. (Source: https://developer.blackberry.com.)

Basically, the project's assets can be organized into folders that hold specific assets for specific resolutions that will be automatically selected when the application starts.

If you need to size and position things dynamically, you might also need information from the DisplayInfo class. Unfortunately, it's not available in QML by default; however, it's easy to expose it via a call to qmlRegisterType:

// MyApplication.cpp
#include <bb/device/DisplayInfo>

MyApplication::MyApplication(bb::cascades::Application *app)
: QObject(app)
{
    // Register MyViewModel so it can be instantiated from QML
    qmlRegisterType<MyViewModel>("com.example.MyApplication", 1, 0, "MyViewModel");
    // Register DisplayInfo so it can be instantiated form QML 
    qmlRegisterType<bb::device::DisplayInfo>("com.example.MyApplication", 1, 0, "DisplayInfo");

    // create scene document from main.qml asset
    // set parent to created document to ensure it exists for the whole application lifetime
    QmlDocument *qml = QmlDocument::create("asset:///main.qml").parent(this);

    // create root object for the UI
    AbstractPane *root = qml->createRootObject<AbstractPane>();
    // set created root object as a scene
    app->setScene(root);
}

For this to work, you'll need to add a library to your .pro file:

#MyApplication.pro
APP_NAME = MyApplication

CONFIG += qt warn_on cascades10
LIBS += -lbbdevice

include(config.pri)

Then use it in QML:

Container {
    attachedObjects: DisplayInfo { id: displayInfo }
    preferredWidth: displayInfo.pixelSize.width
}

Because this class already exposes its members as Q_PROPERTY, you can just use it as is in QML.