Supported QML libraries

The main QML library used for building Cascades apps is the bb/cascades library. This library contains components for layouts, core controls, animations, and more.

To use these classes, you must import the library into your .qml file by specifying the library name and version number.

import bb.cascades 1.2

The library version that you specify corresponds to an API level as follows:

API level QML library

BlackBerry 10.0

bb.cascades 1.0

BlackBerry 10.1

bb.cascades 1.0

BlackBerry 10.2

bb.cascades 1.2

BlackBerry 10.3.0

bb.cascades 1.3

BlackBerry 10.3.1

bb.cascades 1.4

Although Cascades provides its own UI framework, it also supports some additional QML libraries that come with Qt. If you're porting Qt apps to BlackBerry 10, you can use an even larger set of libraries in your apps. For comparison, QML support for Cascades apps and ported BlackBerry 10 apps are as follows:

QML library BlackBerry 10 Cascades

Qt.labs.folderlistmodel 1.0



Qt.labs.gestures 1.0



Qt.labs.particles 1.0



QtMultimediaKit 1.1



QtMobility.connectivity 1.2



QtMobility.sensors 1.1, 1.2, 1.3



QtMobility.Subset.location 1.1, 1.2



QtQuick 1.0, 1.1


No *

* Cascades and Qt Quick both use QtDeclarative, but Cascades does not use the same paint engine as Qt Quick. As a result, mixing Qt Quick UI components with Cascades UI components in the same app can cause issues. For more information about using Qt Quick components in Cascades, see Qt Quick support.

Qt Quick support

Generally, Cascades does not provide support for any visual components within Qt Quick. While some components may work, it's recommended that you use the Cascades equivalent instead. In particular, you should never use any property animators coming from Qt Quick (for example, PropertyAnimation, NumberAnimation, ColorAnimation, RotationAnimation, and so on). The Cascades animations have a much better performance than their Qt Quick equivalents.

Supported components (use at your own risk)

Component Description


The Binding element allows arbitrary property bindings to be created.


The Connections element describes generalized connections to signals.


The State element defines configurations of objects and properties.


The StateChangeScript element allows you to run a script in a state.


The StateGroup element provides state support for non-item elements.


The QML global Qt object provides useful enums and functions from Qt.


The QtObject element is a basic QML element that is used to expose the objectName property. Although the QtObject component is supported, using QtObject from the bb::cascades namespace is the recommended approach for using non-visual objects in Cascades so you can avoid importing the entire Qt Quick library.


The Timer item triggers a handler at a specified interval.


The WorkerScript element enables the use of threads in QML. This component must be used with caution, as Cascades objects cannot be called from a non-UI thread.

Using Qt Quick components

Because BlackBerry 10 supports Qt Quick libraries, you can write or reuse Qt Quick UI code in a Cascades project while making only minor modifications to the standard application template. To use Qt Quick components in a Cascades app:

  1. Create a Cascades project.
  2. In the src folder of your project, select applicationui.cpp and applicationui.hpp, right-click, and select Delete. Click OK when you are prompted to delete the files from the file system.
  3. Double-click main.cpp to open the file in the editor and replace the contents of the file with the following code:
    #include <QtGui/QApplication>
    #include <QtDeclarative/QDeclarativeView>
    #include <QtDeclarative/QDeclarativeEngine>
    int main(int argc, char *argv[])
        QApplication application(argc, argv);
        QDeclarativeView view;
        // Qt.quit() called in embedded .qml by default only emits
        // quit() signal, so do this (optionally use Qt.exit()).
        return application.exec();
  4. Right-click your project and select Clean.

After you finish, open main.qml and add your Qt Quick code.

Last modified: 2015-03-31

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

comments powered by Disqus