Porting a Qt Quick app

Qt Quick apps are written using a combination of C++, QML, and JavaScript. Unlike Qt widget apps, Qt Quick apps use a declarative style and use the QtDeclarative paint engine to display to the screen.

Because of these differences, the process for porting a Qt Quick application to BlackBerry 10 differs slightly from porting a Qt widget-based application. This example describes how to port a Qt Quick application to BlackBerry 10 without making major changes to the code. If you want to rebuild or change part of your application using Cascades, switch to the Cascades focus by using the focus switcher in the upper-left corner of this page.

In this example, we'll port the clocks sample application that is provided with the Qt 4.8.6 desktop libraries. The clocks application draws three clocks on the screen to display the current time for New York, Mumbai, and Tokyo. You can download a binary installer for the Qt 4.8.6 libraries if you don't have them already. After you've installed the libraries, you can find the sample application at <Qt installation directory>\examples\declarative\toys\clocks.

To learn more about Qt Quick support, see Supported QML libraries.

Setting up the project

Unlike a Qt widget project, opening a Qt Quick project in Qt Creator and adding a bar-descriptor.xml file doesn't produce an app that runs on BlackBerry 10. The QML files cannot be directly run on the device, so you need to create a C++ app to load them. Click File > New File or Project. In the New dialog, click Applications > BlackBerry Qt Quick Application and click Choose. Here you can assign information and assets to the project. In the Project name field, enter clocks as the project name. In this example we won't make any additional changes, so click Next > Next > Next > Finish. This will create an empty project with a file structure BlackBerry 10 can use. Your new project should look like this:


Screen showing the initial project view of the clocks project in Qt Creator.

Next, copy your QML and image assets into the <path_to_workspace>\<projectname>\qml folder. After the files are copied, add those files to the clocks.pro file:

TEMPLATE = app

# Please do not modify the following line.
include(qmlapplicationviewer/qmlapplicationviewer.pri)

# Additional import path used to resolve QML modules in Creator's code model
QML_IMPORT_PATH =

# The .cpp file which was generated for your project. Feel free to hack it.
SOURCES += main.cpp

OTHER_FILES += bar-descriptor.xml \
    qml/background.png \
    qml/center.png \
    qml/clock.png \
    qml/Clock.qml \
    qml/clock-night.png \
    qml/clocks.qml \
    qml/hour.png \
    qml/minute.png \
    qml/quit.png \
    qml/QuitButton.qml \
    qml/second.png \

After you add the files, save clocks.pro, and the Project view is updated automatically to reflect the changes:


Screen showing the updated project view of the clocks project in Qt Creator.

Next, you need to define the main QML file for the project in main.cpp:

viewer.setMainQmlFile(QLatin1String("qml/clocks.qml")); // MAINQML

Because we simply copied the QML and image assets into the <project>\qml folder, we need to remove a reference to the original file structure in clocks.qml by removing import "content":

import QtQuick 1.0
import "content"

Becomes:

import QtQuick 1.0

After making this change, you are ready to build and run the app:

Screen showing the first attempt at running the clocks ported app on a BlackBerry 10 device.

Although the app is running, you should tweak the app to make it a little more user friendly.

Tweaking the UI

The main issue we want to address is how to optimize certain UI elements for the BlackBerry 10 screen size and resolution.

To begin, let's increase the size of the text that specifies the city so it's easier to read. In Clock.qml, change the font.pixelSize to 36:

Text {
    id: cityLabel
    y: 200; anchors.horizontalCenter: parent.horizontalCenter
    color: "white"
    font.bold: true; font.pixelSize: 36
    style: Text.Raised; styleColor: "black"
}

Next, we'll change the layout of the clocks to take advantage of the height of the screen. In clocks.qml, we change Row to Column:

Column {
    anchors.centerIn: parent
    Clock { city: "New York"; shift: -4 }
    Clock { city: "Mumbai"; shift: 5.5 }
    Clock { city: "Tokyo"; shift: 9 }
}

Next, we increase the spacing between the clocks:

id: clock
    width: 200; height: 280

Finally, we want to move the QuitButton to the bottom of the screen. In clocks.qml:

QuitButton {
    anchors.right: parent.right
    anchors.bottom: parent.bottom
    anchors.margins: 10
}

The app should now look like this:

Screen showing the finished clocks ported app running on a BlackBerry 10 device.

From here, your next step is signing and distributing the app on BlackBerry World. Although this example only shows how to port a simplistic Qt Quick app, it should be enough to get you started porting your own Qt Quick apps to BlackBerry 10.

Last modified: 2014-06-24



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

comments powered by Disqus