Channels ▼
RSS

Tools

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.

More Insights

White Papers

More >>

Reports

More >>

Webcasts

More >>

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.

The development stack
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.

The static asset selector
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.


Related Reading






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 

Video