Cascades fundamentals

The Cascades framework lets you create visually engaging native applications with relative ease. Cascades is built on top of Qt, which is a C++ application framework . Many fundamental principles of Qt apply to Cascades as well, so it's important to understand a few key concepts to be able to work with Cascades effectively.

Qt and QML

Qt is a cross-platform application framework that's used primarily for creating applications that require a UI. Qt uses standard C++, but extends its functionality using several macros, the most important being the Q_OBJECT macro, which provides an inter-object communication mechanism called signals and slots.

Qt Modeling Language (QML) is a declarative language that's based on JavaScript and is included as part of Qt. It was developed as a simple but powerful language for developers to use to create UIs. Cascades uses a modified version of QML to let you create UIs for your apps.

For more information about how to use QML in Cascades, see QML fundamentals.

The Cascades and Qt frameworks

When developing with Cascades it's important to understand how the different pieces of the framework fit together.

A diagram showing the Cascades API stack.

The foundation of Cascades is Qt 4.8, which provides a set of non-visual foundation classes and objects. The Cascades UI framework provides a presentation layer for displaying visuals and running animations. Cascades also provides a set of platform and hardware APIs for integrating with the BlackBerry 10 OS. If you need lower-level functionality, Cascades applications can also hook into core APIs like the BlackBerry Platform Services (BPS) and Screen libraries.

Cascades UI framework

The Cascades UI framework (bb/cascades) is both fast and easy to use. The application logic and the UI rendering engine run on separate execution threads that communicate asynchronously. The separation of application and rendering logic means that the renderer doesn't need to wait for a long-running computation to complete before updating the UI. This is how Cascades helps your application present a UI at a consistently high frame rate, which keeps your UI smooth and responsive.

To create a sophisticated UI in a traditional, window-based UI framework, you might need to write a lot of code to draw your UI controls where you needed them, when you needed them. A simple animation or transition might require hundreds of lines of code. The graphics code for this type of UI can be difficult to maintain, especially for multiple screen sizes.

A diagram listing some of the Cascades APIs.

Using Cascades, you can accomplish complex UI elements with a fraction of the code required for a window-based UI. Cascades components are C++ objects that are exposed using QML. Cascades gives you the flexibility to create your UI in C++, QML, or both. You can declare your UI in QML and process events using JavaScript in line with your markup. Or you can use C++ if your application has a computationally intensive process or a sophisticated user interaction scenario that you can't process in QML and JavaScript. For more information about using JavaScript in your markup, see JavaScript in QML.

To demonstrate just how easy it is to create a UI in Cascades, here's how to create a button that rotates when it's pressed, in both QML and C++.

Creating a rotating button in QML

import bb.cascades 1.2
Page {
    Button {
        id: rotatingButton
        text: "My Rotating Button"
        animations: [
            RotateTransition {
                id: rotButton
                toAngleZ: 360 
                duration: 350 
        onClicked: {

Creating a rotating button in C++

Page* root = new Page;
Button* myButton = Button::create("My Rotating Button");
RotateTransition* rotation = RotateTransition::create(myButton)
// Connect the button's clicked() signal to the animation's play()
// slot, so that when the button is clicked, the animation plays.
bool connectResult = QObject::connect(myButton, SIGNAL(clicked()),
     rotation, SLOT(play()));

// Check the result of the connect statement

To learn more about the Cascades UI framework, check out some of these useful UI topics:

Cascades platform libraries

The Cascades platform APIs are largely comprised of non-graphical classes that allow you to integrate with the underlying features of the BlackBerry 10 OS. You can use these APIs to interact with device hardware like the camera and microphone, or to integrate with core applications or services like the BBM Social Platform and the Invocation framework.

Unlike many of the Cascades UI classes, which inherit from UIObject, most platform APIs don't have a visual component to them. Because these classes aren't required for building a UI, most aren't registered for use in QML, which makes them more suited for use in C++. Among other things, this can help to make your code more modular as it helps reinforce the separation between UI and business logic. However, if your UI relies directly on a class that isn't registered for QML, you can still register it yourself and use it like any other QML component.

A diagram listing Cascades platform APIs.

Registering a QObject for QML

In this example, the ContactPicker class is registered for QML in main.cpp and is attached to the root component of the main.qml as an attached object. The only requirement for registering a class for QML is that it inherits from QObject.

// main.cpp

#include <bb/cascades/AbstractPane>
#include <bb/cascades/Application>
#include <bb/cascades/QmlDocument>
#include <bb/system/phone/Phone>

using namespace bb::cascades;

Q_DECL_EXPORT int main(int argc, char **argv)
    // Register the Phone class for QML
    qmlRegisterType<bb::cascades::pickers::ContactPicker>("bb.cascades.pickers", 1, 0, "ContactPicker");

    Application app(argc, argv);

    // Load the UI from main.qml
    QmlDocument *qml = QmlDocument::create("asset:///main.qml").parent(&app);

    // Create the application scene
    AbstractPane *appPage = qml->createRootObject<AbstractPane>();

    return Application::exec();
// main.qml

import bb.cascades 1.2
import bb.cascades.pickers 1.0

Page {    
    Container {        
        Button {
            text: "Open contact picker"
            onClicked: {
            attachedObjects: [
                ContactPicker {
                    id: contactPicker
                    onContactSelected: {
                        result.text = "You chose contact: " + contactId;
        Label {
            id: result
            text: "You chose contact: "
Namespace Description


Classes containing application and system utilities for retrieving information like the application state or memory consumption.


A class that is used to display ads.


Classes that allow you to create, customize, and display maps in your application.


Classes that allow you to access the camera on the device so you can capture and display images and video. You can also use these classes to display or read QR codes and bar codes.


Classes for displaying file, calendar, and contact pickers.


Classes for displaying a location picker that allows the user to browse from favorite and recent places.


Classes for storing and accessing different types of data, like JSON, XML, and SQL.


Classes for accessing device hardware, like the battery, radios, SIM card, and the LED.


A class containing error codes that indicate location request failures.


Classes for recording audio and displaying multimedia, such as audio and video.


Classes for using the Push Service to push content to the device.


Classes for managing personal information, like accounts, calendars, contacts, messages, and notebooks.


Classes for integrating with BlackBerry 10 OS features like the homescreen, notifications, Payment Service, and more.


Classes for integrating your app with the BBM Social Platform


Classes containing elements that can be placed on a map, as well as styles and utilities that let you draw boundaries, edges, and markers to make your app more useful to the user.


Classes for integrating user authentication with the Identity Service.


Classes for building system dialogs and menus, integrating NFC, using the Invocation Service, and more.


Classes representing useful utilities, like string validation and internationalization.

Qt modules

The Cascades framework is built on top of the Qt application framework. This architecture allows Cascades to leverage the Qt object model, event model, and threading model.

Qt is a cross-platform application framework that's mostly used to develop UI-driven applications. Qt uses and extends C++ through a code generator with Qt specific macros. The Cascades framework incorporates features of fundamental Qt classes (such as QtCore, QtNetwork, QtXml, and QtSql, and others) and builds on them. The QtCore modules supply an app developer with a Qt event loop and a signals and slots mechanism.

The signals and slots mechanism in Qt allows for powerful and flexible inter-object communication. This is generally used as the primary mechanism for sending and receiving messages within an application process. To learn more about this mechanism, see Signals and slots.

A diagram listing Qt APIs.

Qt provides thread support in the form of platform-independent threading classes, a thread-safe way of posting events, and signal-slot connections across threads. This makes it easy to develop portable multi-threaded applications.

To learn more about how Qt is supported by Cascades, see the Qt fundamentals.

Core libraries

For most apps, the Cascades and Qt APIs give you everything you need in terms of functionality. However, the BlackBerry 10 Native SDK also includes many other native C and C++ APIs (also known as core APIs) that you can use if you need to. In most cases, a core API has a corresponding Cascades API, so you should always double-check to see if an API is available in Cascades or Qt before you use the corresponding core API.

Some of the common core APIs that aren't available in Cascades are the Scoreloop and Crytography libraries. The BlackBerry Platform Services (BPS) library is another core library that is often used in Cascades. Although BPS has a number of Cascades equivalents, it's still useful as it provides developers with a single consistent interface that hooks into a number of different platform services. To see a complete listing of the core APIs that are available, see Library support.

A diagram listing core APIs.

Related resources


Last modified: 2013-12-21

comments powered by Disqus