QFace provides a set of IDL parsers which can help you convert easy-to-read interface definitions into compiling code!

It was written by a Qt/QML developer so it provides many useful features that are Qt-compatible. It was also recently ingested into the Qt Infotainment package

IDL - Interface Description Language

An IDL helps you describe code in a language independent way.

We can refer to the "meta-language" that QFace provides as QFace

Let's Describe!

Let's think about describing a Human Resources service that manages Employees.

We can call this service – the EmployeeService.

Let's define an object, or struct, called Employee that encapsulates one individual that works for this company. This struct can define the employee's name, age, and role. An employee's Role can be a list of positions within the company, i.e. Engineers, Managers, or Executives.

This EmployeeService might have a list of employees, or employeeList, which can be a list of type Employee.

This EmployeeService may also have two operations, one to hire and one to fire an employee. Let's call these methods hireEmployee(..) and fireEmployee(..); respectively. Both methods take a parameter of type Employee.

We can also create a signal that can be emitted whenever a new employee is hired, employeeHired(..). We can pass more context into this signal, e.g. the Employee that was hired.

Let's write this scenario as a QFace file:

module qml.guide.example 1.0

interface EmployeeService {
    int employeeCount
    list<Employee> employeeList
    
    void hireEmployee(Employee employee)
    void fireEmployee(Employee employee)
    
    signal employeeHired(Employee employee)
}

struct Employee {
    string firstName
    string lastName
    int age
    Role role
}

enum Role {
    Unknown,
    SoftwareEngineer,
    HardwareEngineer,
    QualityEngineer,
    ProjectManager,
    Manager,
    Executive
}

An important thing to remember at this stage is that the file above does follow QFace language rules, so every keyword (module, interface, struct, enum) is provided by QFace. The collection of the possible keywords that QFace provides will be referred to as the grammar of QFace.

Please read about the grammar that QFace supports here.

Getting started with the QFace generators

QFace generators are written in python3.

Start by using pip (python package manager) to install qface and its dependencies:

python3 -m pip install qface

Once qface is done installing, check the version:

$ python3 -m pip freeze | grep qface
qface==2.0.0

I have noticed some API changes between 1.X and 2.0, so please keep that in mind if the version of qface you are using is newer than this tutorial

Let's code!

Save the above EmployeeService and friends example to a file called qml.guide.example.qface. Notice how we try to keep the file name the same as the module name. This simplifies searching for right module when you have hundreds of QFace documents.

qml.guide.example.qface should look like this:

module qml.guide.example 1.0

interface EmployeeService {
    int employeeCount
    list<Employee> employeeList
    
    void hireEmployee(Employee employee)
    void fireEmployee(Employee employee)
    
    signal employeeHired(Employee employee)
}

struct Employee {
    string firstName
    string lastName
    int age
    Role role
}

enum Role {
    Unknown,
    SoftwareEngineer,
    HardwareEngineer,
    QualityEngineer,
    ProjectManager,
    Manager,
    Executive
}

Big Picture

This quasi-architecture-flow diagram is straight from the QFace manual. As you can see, we need to take our QFace Document (Interface Definition) which describes an EmployeeService, and feed that into Your Generator which uses the QFace (Generator Library) to finally produce Your Code.

Your Generator

Let's continue our escapade by writing the Your Generator part of the diagram above. We need to write a python3 script that uses the qface package we just downloaded from pip.

Open a new file and name it generator.py:

#!/usr/bin/env python3

from qface.generator import FileSystem, Generator

print("My QFace Generator goes here!")

Run it and make sure you have no errors. This confirms if pip installed the qface package correctly:

python3 generator.py

You can also set the script to executable so you can forever omit the python3 prefix to your command (offtopic: works because of the shebang):

chmod u+x generator.py
./generator.py

Now that we know qface is installed correctly, let's continue writing our generator. The contents of this generator are inspired by the QFace manual:

#!/usr/bin/env python3

from qface.generator import FileSystem, Generator

def generate(input, output):
    # parse the interface files
    system = FileSystem.parse(input)
    # ...

# call the generation function
generate('qml.guide.example.qface', 'generated_code_output')

What's going on here?

Let's start from the last line:

generate('qml.guide.example.qface', 'generated_code_output')

We are sending in our QFace document from above, and a folder name of where our final code output will be placed.

Inside the generate method, we are using qface.FileSystem to parse the QFace document and produce a variable called system which is of type System. This variable (shown in the diagram as ctx) is a python object that holds the grammar of our QFace document.

By reading the API documentation of System, we can see it has a property called modules.

We can use python's pprint package to print out the modules property to see what's inside:

#!/usr/bin/env python3

from qface.generator import FileSystem, Generator
from pprint import pprint

def generate(input, output):
    # parse the interface files
    system = FileSystem.parse(input)
    pprint(system.modules)

# call the generation function
generate('qml.guide.example.qface', 'generated_code_output')

You should see something like this:

qface uses language profile: EProfile.FULL
odict_values([<<class 'qface.idl.domain.Module'> name=qml.guide.example>])

Notice our module name is displayed, qml.guide.examples.

It is now easy to see the type hierarchy present inside the System type:

• System
• -> Module(s)
• ->-> Interface(s)
• ->-> Struct(s)
• ->-> Enum(s)

All of these types are stored as lists of dictionaries (maps) so we can easily iterate through them and print out the grammar of our QFace document:

#!/usr/bin/env python3

from qface.generator import FileSystem, Generator
from pprint import pprint

def generate(input, output):
    # parse the interface files
    system = FileSystem.parse(input)
    
    for module in system.modules:
        print("module.name = " + module.name)

        for interface in module.interfaces:
            print("interface.name = " + interface.name)

        for struct in module.structs:
            print("struct.name = " + struct.name)

        for enum in module.enums:
            print("enum.name = " + enum.name)

# call the generation function
generate('qml.guide.example.qface', 'generated_code_output')

Run this and you will see familiar names:

$ ./generator.py

qface uses language profile: EProfile.FULL
module.name = qml.guide.example
interface.name = EmployeeService
struct.name = Employee
enum.name = Role

Success! Our generator has reached it's first milestone. Sit back and reflect on what just happened.

We took a seemingly unknown IDL and turned it into grammatically significant types: modules (as a collection of interfaces, structs, and enums).

Just imagine the potential of evolving a simple generator like this to something grander!

Stay tuned for the next post in this series!

An enumerated type, or enum, is a data type consisting of a set of named values called elements, members, enumeral, or enumerators of the type.

Enums are incredibly useful when portraying status, options, or modes that are exclusive within a grouping. A common enum that is seen in QML is the Status enum which is present in the Image, Loader, and may other elements. A common groupong of Status has the following values:

Null
Ready
Loading
Error

These enums can be used to track the status of an object. In the case of the Loader element, we can check the status of the file or component being loaded:

Loader {
    source: "SampleSource.qml"
    onStatusChanged: {
        if (status == Loader.Error) {
            console.warn("Error loading", source, sourceComponent.errorString());
        }
    }
}

Creating your own enums

Enums are easy to create in Qt. Simply use the C++ enum identifier and use the Q_ENUM macro to generate Qt-specific helper code.

I have found the best practice to exposing enums is to create a class for each enum you need. This way, each enum is not specifically associated to the class that is using it.

Let's create a new enum for Status similar to what we saw above. Create a new C++ class called StatusClass. We'll explain why we add the Class word at the end of the class name later.

statusclass.h

#pragma once

#include <QObject>

class StatusClass : public QObject
{
    Q_OBJECT
public:
    explicit StatusClass(QObject *parent = nullptr);

};

statusclass.cpp

#include "statusclass.h"

StatusClass::StatusClass()
{

}

By default, this class inherits QObject and has the Q_OBJECT macro to generate relevant MOC data for a QObject.

Since this is an enum class, we don't need to expansive feature set of the Q_OBJECT macro. Let's use Q_GADGET instead. Note that using Q_GADGET doesn't allow us to emit signals; but since this is an enum class we don't expect to emit any signals.

A Q_GADGET version of the class looks like this:

statusclass.h

#pragma once

#include <QObject>

class StatusClass
{
    Q_GADGET
public:
    explicit StatusClass();
};

Now, let's add our C++ enum:

statusclass.h

#pragma once

#include <QObject>

class StatusClass
{
    Q_GADGET
public:
    explicit StatusClass();

    enum Value {
        Null,
        Ready,
        Loading,
        Error
    };
};

In order to generate the Qt-specific helpers for this enum, we need to use the Q_ENUM macro. Be careful not to confuse this with the older, deprecated Q_ENUMS macro. You can read about the differences on woboq.

statusclass.h

#pragma once

#include <QObject>

class StatusClass
{
    Q_GADGET
public:
    explicit StatusClass();

    enum Value {
        Null,
        Ready,
        Loading,
        Error
    };
    Q_ENUM(Value)
};

Great! Now, we're ready to use the Status enum in QML.

Let's register the StatusClass type in main.cpp. We use qmlRegisterUncreatableType as we do not want instances of the StatusClass to be created in QML as it is simply a wrapper to a C++ enum.

main.cpp

qmlRegisterUncreatableType<StatusClass>("qml.guide", 1, 0, "StatusClass", "Not creatable as it is an enum type");

The last argument is a simple reason as to why the type is uncreatable. A warning will be logged if a user tries to instantiate this class:

qrc:/main.qml:16 Not creatable as it is an enum type

Now you can reference these enum values in QML:

main.qml

import QtQuick 2.9
import QtQuick.Window 2.2

import qml.guide 1.0

Window {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    Component.onCompleted: {
        console.log(StatusClass.Ready);
    }
}

You will see the integer 1 printed in your log.

Why did we use Class at the end of the enum name? Let's clarify.
We created a class called StatusClass that wraps an enum called Value.

Our goal was to create an enum that can be exposed to both Qt and QML. We protected the instantiation of StatusClass from QML by using qmlRegisterUncreatableType. To protect the instantiation of an element in C++, we need to make the constructor private.

statusclass.h

#pragma once

#include <QObject>

class StatusClass
{
    Q_GADGET
public:
    enum Value {
        Null,
        Ready,
        Loading,
        Error
    };
    Q_ENUM(Value)

private:
    explicit StatusClass();
};

To use this class in C++, we would have to reference the class name and the Value enum name, e.g. void setStatus(StatusClass::Value status)

This requires us to reference Value to get the actual enum type. We can avoid this by using typedef to expose StatusClass::Value as Status:

typedef StatusClass::Value Status;

Now, our method signature can be void setStatus(Status status).
Much cleaner, isn't it?

For this typedef to work properly with QML, we must register both StatusClass and Status. This ensures the "Status" type is registered to the metatype system which allows us to assign a type of StatusClass to a type of Status via QML.

qRegisterMetaType<Status>("Status");
qmlRegisterUncreatableType<StatusClass>("qml.guide", 1, 0, "Status", "Not creatable as it is an enum type");

Voila! You have exposed an enum from Qt to QML, and also protected the enum for proper use in C++.

See the examples above in the qml.guide GitHub repository.

Live reloading or hot reloading is all the rage these days. One of the best examples of hot reloading is React Native.

Check out a video of it here:

Live reloading is extremely useful to quickly develop and iterate over the user interface aspect of an application.

The majority of Qt / QML developers I have met (myself included, until recently) underestimate the capability of hot reloading QML applications. We are so accustomed to building and running an application, even for the slighest of changes (width, height, color, and other static data).

There are many solutions to the hot reloading problem in Qt + QML. They all have their own advantages and disadvantages. I prefer to use a combination of all the below to accomplish a variety of UI tasks for a project:

Terrarium

Terrarium is a live reloader documented here.

Advantages:

• Quick prototyping with a built-in editor.
• Great for QML interviews.

Disadvantages:

• Not useful for projects as it can only read from the TextEdit element that is built-in to the application.

Qml LiveReload

Qml LiveReload is available here.

After building, the target is placed at /usr/local/bin (for some reason..)
To use,

/usr/local/bin/qmllive /path/to/file.qml

Advantages:

• Easy to use, simply build and execute a QML file with the binary specified above.
• Hard to use with large projects, does not preserve states

Disadvantages:

• Out of build target.. builds to /usr/local/bin/qmllive
• Reloads the entire application

QmlLive

I lightly covered QmlLive here.

Advantages:

• Application preserves workspace, you can easily open and close the app and restore your workspace
• Allows deployment of a runtime to an embedded device to see a UI reload live on a different device.

Disadvantages:

• Reloads the entire application
• UI states are not preserved upon reload

Custom Loader + QQmlEngine Solution

This is my preferred solution. I believe it is the most flexible one as it provides reload capability to individual pieces of a project's user interface; unlike some of the aforementioned solutions which reload the entire user interface.

Before diving into the code that powers this method of live reloading, let's investigate how the QmlEngine works with respect to the loading of QML elements.

In QML, a Component is a template that defines an object. A Component can be used to build objects that have a well-defined structure and interface.

Component {
    id: _componentIconLabel
    
    Row {
        property var icon
        property var text
        Image {
            width: 50; height: 50
            source: parent.icon
        }
        Text {
            text: parent.text
        }
    }
}

Button {
    onClicked: {
        var iconLabelObject = _componentIconLabel.createObject(root);
        iconLabelObject.text = "Hello World"; 
        // NOTE: These properties can be set before the 
        // element is created by using the createObject 
        // method's second argument
    }
}

In the example above, we already created the Component by declaring it in QML. You can also create a Component by loading a file.

Once a Component is created, it is cached in the QmlEngine.

How does this cache work? Let's dig a little deeper into the sources.

1. Component uses the QmlEngine's QmlTypeLoader to get the type of what is being loaded into a Component. More information can be read in the Qt sources here.

2. QmlTypeLoader provides a getType method that checks a cache (QmlTypeCache), if there is a hit it returns cached data, else, it loads in new data.

To allow for hot or live reloading, it is crucial for us to ignore the cache and reload from disk. The criteria for checking cache is not particularly sophisticated as every type is registered by URL / type name.

Since we do not want modify the criteria for how Component caching works in Qt sources, we can work around this cache by simply clearing it when a reload is required.

QmlEngine provides two methods for manipulating the QML type component cache.

QQmlEngine::trimComponentCache() - Trims component cache entries for components that are no longer used. This is a very difficult criteria to satisfy as components are generally used widely throughout a QML project.

See Qt sources here

QQmlEngine::clearComponentCache() - Clears the entire component cache. If an element is still used, it is at risk of causing warnings throughout the UI as when the same type is loaded again, it will be loaded into a new cache entry. This new cache entry and the old active element will no longer match.

This is a small inconvenience for the benefit of hot reloading. By clearing the entire component cache, we can simply reload a QML file to view updated changes.

See Qt sources here.

Let's get down to business.

There are a few ways you can implement this:

• Option A: Build a custom Component loader in Qt C++, reference QmlEngine directly in C++
• Option B: Extend the QML Loader and expose a reference to the QmlEngine to QML

I prefer Option B, so let's do it:

First, let's create an example project with a Window, a Loader, and a Component.

main.qml

import QtQuick 2.9
import QtQuick.Window 2.2

Window {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    Loader {
        id: _loader

        function reload() {
            source = "";
            source = "Circle.qml";
        }

        anchors.centerIn: parent
        source: "Circle.qml"
    }

    MouseArea {
        anchors.fill: parent
        onClicked: {
            _loader.reload();
        }
    }
}

Add a MouseArea and a method in the loader called reload. We will use these to prove that the QmlEngine and its associates are caching types.

In this example, we are creating a Loader and load in file called Circle.qml:

Circle.qml

import QtQuick 2.9

Rectangle {
    width: 300
    height: 300
    radius: width / 2

    color: "blue"
}

Run the UI and you will see this:

Keep the UI open. Now, modify Circle.qml to make the Rectangle color red:

Circle.qml

import QtQuick 2.9

Rectangle {
    width: 300
    height: 300
    radius: width / 2

    color: "red"
}

Now that the Circle is red, click on the UI to reload the Loader.

Notice how the Circle remains blue? This Loader is being reloaded yet the Circle is still blue. This is proof that the Component created from Circle.qml is cached. It's also apparent that the cache is not keyed by the contents of Circle.qml.

Let's keep working until we can figure out how to make the Circle change colors when we click the UI.

Above, we learned about the methods available in the QmlEngine to trim and clear the cache in the QmlEngine. Let's use some of these methods.

To use a method from the QmlEngine in QML land, we must expose it. Let's do it via context properties.

Here is our auto-generated (by project template) main.cpp:

original main.cpp

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
#if defined(Q_OS_WIN)
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
#endif

    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

Let's use context properties to expose the engine to QML. Context properties are simply magic global variables that are available in all of QML without the need of importing anything.

modified main.qml

#include <QGuiApplication>
#include <QQmlApplicationEngine>

#include <QQmlContext>

int main(int argc, char *argv[])
{
#if defined(Q_OS_WIN)
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
#endif

    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;

    engine.rootContext()->setContextProperty("$QmlEngine", &engine);

    engine.load(QUrl(qgetenv("MAIN_QML")));
    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

In this code, we are exposing a global variable called $QmlEngine as a context property of the QmlEngine's root context. This allows the $QmlEngine variable to be used from any QML file loaded inside this this particular engine.

Also note how we replaced the qrc:// URL with a qgetenv. We do not want Qt to compile our resources into a binary QRC file as this would require us to rebuild the project when changing a QML file.

I have removed the use of QRC in almost every large-scale project I've worked on. Compiling QML files into resource files is very detrimental to developer productivity. Compiling QML files into resources can easily be enabled for release or production builds and avoided in developer builds.

We should run our application with the environment variable specified, e.g:

MAIN_QML=../HotReloading/main.qml ./bin/HotReloading

Now that we have a reference to the QmlEngine, let's invoke the QQmlEngine::clearComponentCache when we are reloading the Loader element in main.qml:

main.qml

import QtQuick 2.9
import QtQuick.Window 2.2

Window {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    Loader {
        id: _loader

        function reload() {
            source = "";
            $QmlEngine.clearComponentCache();
            source = "Circle.qml";
        }

        anchors.centerIn: parent
        source: "Circle.qml"
    }

    MouseArea {
        anchors.fill: parent
        onClicked: {
            _loader.reload();
        }
    }
}

Let's try this again. Build your code and run the UI again.
Modify the color of the Rectangle in Circle.qml.

Click the circle. Did it change colors?

Nope! Now we got a warning:

qrc:/main.qml:15: TypeError: Property 'clearComponentCache' of object QQmlApplicationEngine(0x7fff58907a98) is not a function

What gives? It seems that QQmlEngine::clearComponentCache is not allowed to be invoked by QML. It is a public method, but it does not have the Q_INVOKABLE flag.

Let's create a utility class that exposes an aliased function that calls QQmlEngine::clearComponentCache. These kinds of hoops are common when attempting to expose Qt functionality to QML.

We have two options here, we can either create a brand new class that extends QObject or we can create a brand new class that extends QQmlApplicationEngine. The latter is simpler as we don't need to pass in the QQmlEngine object.

Create a new file called EnhancedQmlApplicationEngine:

enhancedqmlapplicationengine.h

#pragma once

#include <QQmlApplicationEngine>

class EnhancedQmlApplicationEngine : public QQmlApplicationEngine
{
    Q_OBJECT
public:
    explicit EnhancedQmlApplicationEngine(QObject *parent = nullptr);

    Q_INVOKABLE void clearCache();
};

enhancedqmlapplicationengine.cpp

#include "enhancedqmlapplicationengine.h"

EnhancedQmlApplicationEngine::EnhancedQmlApplicationEngine(QObject *parent)
    : QQmlApplicationEngine(parent)
{

}

void EnhancedQmlApplicationEngine::clearCache()
{
    this->clearComponentCache();
}

Note how we had to name the method clearCache instead of clearComponentCache since the latter was already taken by the super class, QQmlEngine by proxy of QQmlApplicationEngine.

Use this new engine in main.cpp:

main.cpp

#include <QGuiApplication>
#include <QQmlContext>

#include "enhancedqmlapplicationengine.h"

int main(int argc, char *argv[])
{
#if defined(Q_OS_WIN)
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
#endif

    QGuiApplication app(argc, argv);

    EnhancedQmlApplicationEngine engine;

    engine.rootContext()->setContextProperty("$QmlEngine", &engine);

    engine.load(QUrl(qgetenv("MAIN_QML")));
    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

Update your reload method in main.qml to call our new clearCache method:

import QtQuick 2.9
import QtQuick.Window 2.2

Window {
    visible: true
    width: 640
    height: 480
    title: qsTr("Hello World")

    Loader {
        id: _loader

        function reload() {
            source = "";
            $QmlEngine.clearCache();
            source = "Circle.qml";
        }

        anchors.centerIn: parent
        source: "Circle.qml"
    }

    MouseArea {
        anchors.fill: parent
        onClicked: {
            _loader.reload();
        }
    }
}

Voila! Build your code again.

Run the UI.

Now, you can scatter these Loader elements with a custom reload method throughout your UI. Whenever you need to reload, you can. This allows for rapid UI development, especially when building out individual widgets or scenes.

This Hot Reloading solution can be extended:

• Use a QFileSystemWatcher class to track the loaded file for changes. When a change is signaled, reload the Loader.
• Use a Timer to reload constantly while developing.

The source code is available on the qml.guide GitHub repository.

QtAutomotiveSuite Overview

QtAutomotiveSuite is a collection of Qt-based projects geared towards the Automotive industry.

Some projects in the suite include:

• Qt ApplicationManager - An application framework that can emulate the behavior of on OS at the application-layer of an automotive platform. It allows developers to build a SystemUI and several Applications that may be launched in separate processes.

• QFace - An IDL format with a python-based generator tha simplifies the development of large scale interfaces, structs, and enums.
  

• QML Live - A hot reloading application that automatically refreshes QML files when they are changed. This tool greatly simplifies the development of UIs by automatically reloading an application view without requiring the developer to re-compile and re-run an application.

Qt ApplicationManager

The Qt ApplicationManager provides one primary function: Provide the ability to run multi-process applications using the Wayland protocol implemented by QtWayland.

Common terminology:
SystemUI - The main homescreen of an application. This UI is loaded in the main process alongside Qt ApplicationManager code and is responsible for forking new processes. This is analogous to the homescreen on your mobile phone. If the system ui dies, the entire project is killed including all applications.

ApplicationUI - The available applications that are loaded by Qt ApplicationManager. These applications can be pre-installed or even installed at runtime. This is analogous to an application on your mobile phone. If an application on your mobile phone dies, you may be redirected to the homescreen or system ui.

Advantages of multi-process

• Isolated processes per application - In the domain of automotive, this allows infotainment develoeprs the ability to launch a Navigation application, a Radio application, and a Settings application in separate linux processes. If the Navigation application crashes, the rest of the system is left unharmed. The Radio application and Settings application remain intact.

• Application resource usage - Since the Navigation application, Radio application, and Settings application are running in separate processes, the system is able to report back resource usage per application. QtApplicationManager provides CpuConsumption and MemoryConsumption for each process. With this, we can figure out, for example, that the Navigation application is using 300MB of RAM, the Radio application is using 100MB of RAM and the Settings application is using 120MB of RAM. In a traditional single-process setup, all applications would be in a single process and there is no way of knowing how much machine resource is being used by one piece of this group of applications.

Disadvantages of multi-process

With advantages come disadvantages. And with multi-process being the leading advantage, we would have to write these disadvantages off as a debt of innovation.

• Inter-application Communication - In single-process, if the Navigation application needed to talk to the Radio application, we could simply refer to the Navigation application by QML id, i.e.

import QtQuick 2.7

Window {
    SystemUi { id: _systemUi }
    NavigationApplication { id: _navigationApplication } 
    RadioApplication { id: _radioApplication } 
    SettingsApplication { id: _settingsApplication } 
}

We could simply refer to _navigationApplication by id and invoke methods, modify properties, send signals, etc:

Button {
    onClicked: _navigationApplication.routeToHome();
}

In multi-process, these applications are represented in the SystemUI as proxies living in the same process; however, each application is actually running in its own process. Each process has its own memory space; therefore, the memory referred to by the _navigationApplication pointer does not actually exist.

This prevents us from simply using the id to invoke methods, modify properties, send signals, etc. This work must be done using IPC or Inter-process Communication

• Singletons - QtQuick developers far too often rely on singletons to manage global data or references to objects deeply nested within their object hierarchy. This is no longer supported as each process has its own QQmlEngine instance and cannot synchronize singletons across these engines.

• Resource Usage - As each application is running in its own process, linux requires each process to load symbols from any shared libraries (e.g. Qt libs) in each process. This results in duplication of memory for each process. This would also result in duplication for assets such as fonts, images, media, etc.
  

• Developer experience - Multi-process in Qt ApplicationManager uses QtWayland which is only available on Linux operating systems. From my experience, good production developers nowadays will use MacOS (which provides the ability to open design files in Photoshop, Sketch, Zeplin) and translate them into running code. Since MacOS does not support QtWayland – QtApplicationManager falls back to a single-process emulated mode. The downside; however, is that this single-process emulated mode does not prevent deveopers from accessing different application elements by id and could therefore break when the code is moved to a multi-process capable environment such as linux.

QFace

QFace is a very easy to use IDL format which includes a grammatical model template support to automatically generate Qt classes.
It is well-documented here: https://doc-snapshots.qt.io/qtivi-5.10/qtivi-attribution-qface.html

QmlLive

QmlLive is well-documented here:
https://doc.qt.io/QtQmlLive/index.html

Advantages

• Hot reloading is the new rage in development. It allows UI developers to quickly modify pixel values, colors, etc. and see their creation live on screen.
• Allows deployment of a runtime to an embedded device to see a UI reload live on a different device.

Disadvantages

• This solution is too generic; reloads the entire application
• UI states are not preserved upon reload

Tips

• Qt ApplicationManager (and the majority of the QtAutomotiveSuite) was developed by Pelagicore in their Munich, Germany office.
• Github - https://github.com/qt/qtapplicationmanager
• Two developers from Pelagicore have contributed the majority of the Qt ApplicationManager, Robert Griebl and Dominik Holland.
• Another developer from Pelagicore, Juergen Ryannel , created QFace
• Major props to the team at Pelagicore!

Stay tuned for more in-depth posts for each of the above projects

The absolute basic element in QML is QtObject:

import QtQml 2.2

QtObject {
    property var name: "John Doe"
}

A QtObject is a QML representation of the QObject element. This can be seen in Qt source code here where the QML base types are registered:

...
void QQmlEnginePrivate::registerBaseTypes(const char *uri, int versionMajor, int versionMinor)
{
    ...
    qmlRegisterType<QObject>(uri,versionMajor,versionMinor,"QtObject");
    ...

QtObject is a non-visual element and is very useful for grouping together or creating blocks of business logic in the otherwise UI-heavy QML land.

Private properties in QML

Controlling access to QML-based objects is not possible, i.e. it is not possible to use the membership keywords such as private, public, or protected in QML.

To workaround this slight inconvenience, developers can use the QtObject element to privatize methods or properties.

Let's say we want to build a Slider component that can be used by anyone. We want to ensure our API is clean and indestructible.

Start with the Slider UI.

• First, build the track or the line that the slider circle will move on
• Second, build the scrubber or the circle that the user will interact with
• Third, add a MouseArea in the scrubber so it is interactive. We set the minimumX and maximumX so the center of the circle is at the ends of the line when its value is minimized or maximized, respectively.

Slider.qml

import QtQuick 2.7

Item {
    id: root
    width: 200
    height: 40

    Rectangle {
        id: _rectangleTrack
        anchors.centerIn: parent
        width: parent.width - _rectangleScrubber.width
        height: 4
        color: "#222222"
    }

    Rectangle {
    	id: _rectangleScrubber
    	anchors.verticalCenter: _rectangleTrack.verticalCenter
    	width: parent.height / 2
    	height: width
    	radius: width / 2

    	color: "#EEEEEE"

    	border.color: "#DDDDDD"
    	border.width: 2

        MouseArea {
            anchors.fill: parent
            drag.target: parent
            drag.minimumX: 0
            drag.maximumX: _rectangleTrack.width
    	}
    }
}

Now run your Slider.qml through qmlscene and you should see this:

Now that we have a UI for this Slider, let's expose an API.

Several great examples of APIs are already written, and in this case, Qt has already built a Slider. In the interest of learning from the ground up, let's take three properties from their API:

• value - The current value held by the slider. This is calculated by mapping the percentage of the scrubber on the track to the difference between the maximumValue and minimumValue properties
• minimumValue - The smallest possible value, i.e. the value when the scrubber is at 0%
• maximumValue - The largest possible value, i.e. the value when the scrubber is at 100%

    property real value: 0.0
    property real minimumValue: 0.0
    property real maximumValue: 10.0

We will use floating point values for maximum flexibility.

Now, let's connect this API to our UI elements. It's important to consider the user of each property in order to build a stable, secure API.

The value property will be used by:

• External: Developers who use the Slider element can set a real number to the value property
• Internal: When a user of the Slider UI element drag the scrubber, logic that lives internal to the Slider will update the value property to accurately reflect the new value.

The minimumValue and maximumValue properties will be used by:

• External: Developers who use the Slider element can set these two values to create a range of possible values for the Slider
• Internal: This value is never changed by internal logic of the Slider element

Now we're ready to connect our properties to our UI elements. Let's begin with the value property. When the Slider element is first created, we want to ensure the default real number of the value property affects where the position of the scrubber is on the track.

Set the value property to 5.0; this indicates the scrubber is halfway through the track.

percentageAlongTheTrack = value / (maximumValue - minimumValue)

Plugging in our numbers we get:

50% = 5.0 / (10.0 - 0.0)

We can use this simple equation to set the x value of the scrubber:

x: _rectangleTrack.width * (root.value / (root.maximumValue - root.minimumValue))

Here's the entire file for clarity:

Slider.qml

import QtQuick 2.7

Item {
    id: root

    property real value: 5.0
    property real minimumValue: 0.0
    property real maximumValue: 10.0

    width: 200
    height: 40

    Rectangle {
        id: _rectangleTrack
        anchors.centerIn: parent
        width: parent.width - _rectangleScrubber.width
        height: 4
        color: "#222222"
    }

    Rectangle {
    	id: _rectangleScrubber
    	anchors.verticalCenter: _rectangleTrack.verticalCenter

    	x: _rectangleTrack.width * (root.value / (root.maximumValue - root.minimumValue))

    	width: parent.height / 2
    	height: width
    	radius: width / 2

    	color: "#EEEEEE"

    	border.color: "#DDDDDD"
    	border.width: 2

        MouseArea {
            anchors.fill: parent
            drag.target: parent
            drag.minimumX: 0
            drag.maximumX: _rectangleTrack.width
    	}
    }
}

That is already a decent amount of logic within a UI element. Let's move it to the root element:

import QtQuick 2.7

Item {
    id: root

    property real value: 4.0
    property real minimumValue: 0.0
    property real maximumValue: 10.0

    property int scrubberXPosition: _rectangleTrack.width * (value / (maximumValue - minimumValue))

    width: 200
    height: 40

    Rectangle {
        id: _rectangleTrack
        anchors.centerIn: parent
        width: parent.width - _rectangleScrubber.width
        height: 4
        color: "#222222"
    }

    Rectangle {
    	id: _rectangleScrubber
    	anchors.verticalCenter: _rectangleTrack.verticalCenter

    	x: root.scrubberXPosition

    	width: parent.height / 2
    	height: width
    	radius: width / 2

    	color: "#EEEEEE"

    	border.color: "#DDDDDD"
    	border.width: 2

        MouseArea {
            anchors.fill: parent
            drag.target: parent
            drag.minimumX: 0
            drag.maximumX: _rectangleTrack.width
    	}
    }
}

We can make it readonly so the developers who use the Slider component cannot overwrite our logic:

readonly property int scrubberXPosition: _rectangleTrack.width * (value / (maximumValue - minimumValue))

Our API has now been extended by one property; unwillingly:

• value
• minimumValue
• maximumValue
• scrubberXPosition

It is really necessary for us to expose a readonly property for the scrubber's x position? In this case, no. This is where a private member in C++ is quite useful; however, since we are in QML land, we do not have such capability.

Enter QtObject:

We can use a QtObject as a lightweight container to wrap our logic since it is unwanted as an exposed API:

import QtQuick 2.7

Item {
    id: root

    property real value: 4.0
    property real minimumValue: 0.0
    property real maximumValue: 10.0

    width: 200
    height: 40

    QtObject {
        id: internal

        readonly property int scrubberXPosition: _rectangleTrack.width * (root.value / (root.maximumValue - root.minimumValue))
    }

    Rectangle {
        id: _rectangleTrack
        anchors.centerIn: parent
        width: parent.width - _rectangleScrubber.width
        height: 4
        color: "#222222"
    }

    Rectangle {
    	id: _rectangleScrubber
    	anchors.verticalCenter: _rectangleTrack.verticalCenter

    	x: internal.scrubberXPosition

    	width: parent.height / 2
    	height: width
    	radius: width / 2

    	color: "#EEEEEE"

    	border.color: "#DDDDDD"
    	border.width: 2

        MouseArea {
            anchors.fill: parent
            drag.target: parent
            drag.minimumX: 0
            drag.maximumX: _rectangleTrack.width
    	}
    }
}

We have now reduced our API back to the original three properties we wanted:

• value
• minimumValue
• maximumValue

Let's continue building our Slider element.

Whenever a user drags the scrubber, we want the value property to update. We can add this logic directly to the scrubber Rectangle using an onXChanged handler:

...
Rectangle {
    id: _rectangleScrubber
    anchors.verticalCenter: _rectangleTrack.verticalCenter

    x: internal.scrubberXPosition

    onXChanged: {
        root.value = (x / _rectangleTrack.width) * (root.maximumValue - root.minimumValue)
    }

    width: parent.height / 2
    height: width
    radius: width / 2
        
        ...

Now, we run into a similar problem as we did above. This logic should not be in a UI element; but rather a logic block. We now have the QtObject; let's move our logic into there:

QtObject {
    id: internal

    readonly property int scrubberXPosition: _rectangleTrack.width * (root.value / (root.maximumValue - root.minimumValue))

    Connections {
        target: _rectangleScrubber
        onXChanged: {
            root.value = (x / _rectangleTrack.width) * (root.maximumValue - root.minimumValue)
        }
    }
}

Now, use qmlscene to run your program:

file:///qmlguide/examples/QtObject/Slider.qml:18 Cannot assign to non-existent default property

Uh oh! What does this mean?

The issue here is that since QtObject is exactly a QObject registered using qmlRegisterType; as we saw above, it is not prepared for the likeness of QML. QQuickItem derived elements have a data property is set as the default property.

What is a default property? Whenever you use the QML syntax to create an object hierarchy, the child elements have to go somewhere.
The child elements have to be stored somewhere in the parent.

Car {
    Tire { }
    Tire { }
    Tire { }
    Tire { }
}

In this example, the Car element has four child Tire elements. Given that Car is a QQuickItem derived class, the Tire elements are automatically placed into the default property which is data.

Setting the default property in C++

In C++, this is accomplished using Q_CLASSINFO("DefaultProperty", "data") and building up a QQmlListProperty for the data member. You can see how Qt does this for QQuickItem here.

Setting the default property in QML

In QML, this is accomplished in a much easier way. We can simply use the default directive prior to the property name.

Create a new QML file called BaseObject.qml:

BaseObject.qml

import QtQml 2.2

QtObject {
    default property var data
}

Now, any new element that is created within this object instance is automatically placed within the data property.

Update your Slider element to look like this:

Slider.qml

import QtQuick 2.7

Item {
    id: root

    property real value: 5.0
    property real minimumValue: 0.0
    property real maximumValue: 10.0

    width: 200
    height: 40

    BaseObject {
        id: internal

        readonly property int scrubberXPosition: _rectangleTrack.width * (root.value / (root.maximumValue - root.minimumValue))

        Connections {
            target: _rectangleScrubber
            onXChanged: {
                root.value = (x / _rectangleTrack.width) * (root.maximumValue - root.minimumValue)
            }
        }
    }

    Rectangle {
        id: _rectangleTrack
        anchors.centerIn: parent
        width: parent.width - _rectangleScrubber.width
        height: 4
        color: "#222222"
    }

    Rectangle {
    	id: _rectangleScrubber
    	anchors.verticalCenter: _rectangleTrack.verticalCenter

    	x: internal.scrubberXPosition

    	width: parent.height / 2
    	height: width
    	radius: width / 2

    	color: "#EEEEEE"

    	border.color: "#DDDDDD"
    	border.width: 2
    	
        MouseArea {
            anchors.fill: parent
            drag.target: parent
            drag.minimumX: 0
            drag.maximumX: _rectangleTrack.width
    	}
    }
}

Run your code again, and voila! Everything's working great.

There are more touch ups you can do to the Slider element to avoid binding loops. Use the pressed boolean of the MouseArea to avoid recalculating the scrubberXPosition of the scrubber when it is being dragged. When the scrubber is released, the binding of root.value to internal.scrubberXPosition needs to be re-established.

The code in this tutorial is available at the qml.guide GitHub repo.

NOTE: This is Part 2 of the Data Models Deconstructed series, see Part 1 here.

QAbstractListModel is the tried and true way of exposing data from Qt C++ to QML. This abstract class provides an interface or contract that is adhered to by QtQuick elements such as ListView, PathView, GridView, and Repeater.

Because of this contract set forth by QAbstractListModel, Qt is able to provide a very efficient mechanism of data exposure to QML.

Efficiencies can be seen in many things including:

• Inserting items to a data set
• Moving items in a data set
• Editing items in a data set
• Removing items from a data set

These dataset manipulation methods allow us to update QML UIs or views without heavy performance impact.

If a list of top 100 music tracks needs to be displayed in QML, and one track at index #10 is changed, we don't need to rebuild the entire dataset and the list UI doesn't need to be completely re-drawn. The element at index #10 is modified in the dataset, and correspondingly the element at index #10 in the list UI is updated without modifying the list scroll position or any other visual element of the list.

QAbstractListModel Basics

Since QAbstractListModel is an abstract class, it provides an interface or contract that must be implemented or adhered to by the user.

It is essentially useless in itself as it is an interface. Extend it, implement it.

int rowCount();
QVariant data();
QHash<int, QByteArray> roleNames()

There is a good amount of detail on how to do this here:
http://doc.qt.io/qt-5/qabstractlistmodel.html

QAbstractListModel Caveats

If you read the above Basics section and the Qt documentation linked above, you may notice that the roleNames requirement is quite cumbersome.

If you have a model of music tracks, each model item would be a music track.

Imagine a QML-based API looking like this:

MusicTrackModel {
    MusicTrack { }
    MusicTrack { }
    MusicTrack { }
    MusicTrack { }
}

Here, MusicTrackModel is the class name of your model, and each MusicTrack is an item within your model.

Say the MusicTrack is defined as:

QtObject {
    property string title
    property string artistName
    property int duration
}

Each property of the MusicTrack item is considered a roleName of the MusicTrackModel.

The C++ shortened implementation of the MusicTrackModel would look like this:

...
...
...

class MusicTrackModel : QAbstractListModel {
    Q_OBJECT

public:
    enum ModelRoles {
        TitleRole = Qt::UserRole + 1,
        ArtistNameRole,
        DurationRole
    };
    
    ...
    ...
    ...
    
    QHash<int, QByteArray> roleNames() const
    {
        QHash<int, QByteArray> roles;
        roles[TitleRole] = "title";
        roles[ArtistNameRole] = "artistName";
        roles[DurationRole] = "duration";
        return roles;
    }
}

As can be seen, there is tight coupling between the model and the model item. This may be useful for some cases where this model couples with another object to sort / filter the data before sending it to the QML-side of the codebase.

However; for most use-cases, the model items, i.e. MusicTrack, will be QObject-derived objects with properties that are distinguishable via the QMetaObject. If having restricted properties per model item is not a concern, you can build a generic model for all QObject-derived items. These items can be defined in Qt or in QML.

Building a generic model that holds any QObject-derived class

When designing an object that will be exposed to QML, I have found it easier to start with the API of the object, then work towards the implementation

Designing the QML-facing API

Let's start with the QML API for what a generic model that can hold any QObject-derived class:

DataObjectModel {
    id: _dataObjectModel
    
    QtObject {
        property string title: "The first track"
        property string artistName: "John Doe"
        property int duration: 230213
    }
    QtObject {
        property string title: "The second track"
        property string artistName: "John Doe"
        property int duration: 123111
    }
    QtObject {
        property string title: "The third track"
        property string artistName: "John Doe"
        property int duration: 12239991
    }
}

ListView {
    ...
    model: _dataObjectModel
}

As we can see here, we would like a model that can be fed into a QtQuick view; i.e. a ListView. This model is constructed by placing QtObject's within it.

Let's simplify the API by creating a new component called MusicTrack, e.g. MusicTrack.qml

QtObject {
    property string title
    property string artistName
    property int duration
}

Now, our simplified API use-case is:

DataObjectModel {
    id: _dataObjectModel
    
    MusicTrack {
        title: "The first track"
        artistName: "John Doe"
        duration: 230213
    }
    MusicTrack {
        title: "The second track"
        artistName: "John Doe"
        duration: 123111
    }
    MusicTrack {
        title: "The third track"
        artistName: "John Doe"
        duration: 12239991
    }
}

ListView {
    ...
    model: _dataObjectModel
}

Building the QAbstractListModel implementation

Let's call our model DataObjectModel to fit our API design.

DataObjectModel doesn't seem to have any properties in the example above, but let's consider the hidden API of a standard QtQuick-provided model, i.e. ListModel

A ListModel has:

• count - The total number of items in the model
• append(..) - A method to append an object to the model
• insert(.., ..) - A method to insert an object to a particular index of the model
• get(..) - A method to get the object at a particular index from the model

This is a standard API amongst many pre-built models in QtQuick. Let's include these in our DataObjectModel.

Let's start by creating a new C++ class in your project with QtCreator.

Go to File > New File or Project

Name your class DataObjectModel and derive it from QObject, for now:

You should now have a header file, dataobjectmodel.h that looks like this:

#ifndef DATAOBJECTMODEL_H
#define DATAOBJECTMODEL_H

#include <QObject>

class DataObjectModel : public QObject
{
    Q_OBJECT
public:
    explicit DataObjectModel(QObject *parent = nullptr);

signals:

public slots:
};

#endif // DATAOBJECTMODEL_H

I prefer using #pragma once with C++11, instead of the defines that are generated by by QtCreator templates:

dataobjectmodel.h

#pragma once

#include <QObject>

class DataObjectModel : public QObject
{
    Q_OBJECT
public:
    explicit DataObjectModel(QObject *parent = nullptr);

signals:

public slots:
};

Now, let's derive our class from QAbstractListModel:

dataobjectmodel.h

#pragma once

#include <QAbstractListModel>

class DataObjectModel : public QAbstractListModel
{
    Q_OBJECT
public:
    explicit DataObjectModel(QObject *parent = nullptr);

signals:

public slots:
};

dataobjectmodel.cpp

#include "dataobjectmodel.h"

DataObjectModel::DataObjectModel(QObject *parent)
    : QAbstractListModel(parent)
{

}

Build it, make sure your code is building!

Now, let's setup the properties from the API we designed earlier:

Start with the count property:

Add a Q_PROPERTY under the Q_OBJECT macro:

...
Q_PROPERTY(int count READ count WRITE setCount NOTIFY countChanged)
...

To generate the setters / getters, simply right click on the Q_PROPERTY designator and right click, Refactor -> Generate Missing Q_PROPERTY members

dataobjectmodel.h

#pragma once

#include <QAbstractListModel>

class DataObjectModel : public QAbstractListModel
{
    Q_OBJECT
    Q_PROPERTY(int count READ count WRITE setCount NOTIFY countChanged)

    int m_count;

public:
    explicit DataObjectModel(QObject *parent = nullptr);

    int count() const
    {
        return m_count;
    }

signals:
    void countChanged(int count);

public slots:
    void setCount(int count)
    {
        if (m_count == count)
            return;

        m_count = count;
        emit countChanged(m_count);
    }
};

Move the implementations to the cpp file by right clicking on the signature and Refactor -> Move definition to dataobjectmodel.cpp

I also prefer moving the member variable, m_count to a specific private block at the bottom of the document:

dataobjectmodel.h

#pragma once

#include <QAbstractListModel>

class DataObjectModel : public QAbstractListModel
{
    Q_OBJECT
    Q_PROPERTY(int count READ count WRITE setCount NOTIFY countChanged)

public:
    explicit DataObjectModel(QObject *parent = nullptr);
    int count() const;

signals:
    void countChanged(int count);

public slots:
    void setCount(int count);

private:
    int m_count;
};

dataobjectmodel.cpp

#include "dataobjectmodel.h"

DataObjectModel::DataObjectModel(QObject *parent)
    : QAbstractListModel(parent)
{

}

int DataObjectModel::count() const
{
    return m_count;
}

void DataObjectModel::setCount(int count)
{
    if (m_count == count)
        return;

    m_count = count;
    emit countChanged(m_count);
}

Now, initialize the count to 0 in the cpp file:

dataobjectmodel.cpp

...

DataObjectModel::DataObjectModel(QObject *parent)
    : QAbstractListModel(parent)
    , m_count(0)
{

}

...

Let's continue building out our API:

• count - The total number of items in the model
• append(..) - A method to append an object to the model
• insert(.., ..) - A method to insert an object to a particular index of the model
• get(..) - A method to get the object at a particular index from the model

The remaining three API considerations are methods. We can create methods simply by adding Q_INVOKABLE to a standard C++ method.

dataobjectmodel.h

...
public:
    Q_INVOKABLE void append(QObject* o);
    Q_INVOKABLE void insert(QObject* o, int i);
    Q_INVOKABLE QObject* get(int i);
...

Add stub implementations into dataobjectmodel.cpp.

Now, let's step back and think about what we're building.
We are building a wrapper to a set of data that we want to expose to QML. This wrapper provides the API we designed above.

If DataObjectModel is simply a wrapper, where is the real data stored?

The data is stored inside the DataObjectModel class. Let's add a new private member called m_data and use the QList data structure to store a list of object pointers.

dataobjectmodel.h

...
private:
    int m_count;
    QList<QObject*> m_data;
...

Now, let's think back to how we can complete our wrapper to provide data from the m_data list. At the start of this article, we learned about how the QAbstractListModel is essentially an interface or contract that many different elements adhere to. We need to make sure we fulfill our side of this contract by implementing the methods required by the QAbstractListModel.

Which methods do we need to implement?

Let's add these methods for rowCount(..), data(..,..), and roleNames() to our DataObjectModel class:

    int rowCount(const QModelIndex &p) const;
    QVariant data(const QModelIndex &index, int role) const;
    QHash<int, QByteArray> roleNames() const;

• rowCount - This method simply returns the count of items in m_data as this is our data set. The argument p is unused and can be masked in a Q_UNUSED(p) block to avoid compiler warnings.

int DataObjectModel::rowCount(const QModelIndex &p) const
{
    Q_UNUSED(p)
    return m_data.size();
}

• data - This method is how a ListView or other view element that ingests the model can access individual data objects and properties. The argument index is the index of the element in the list – 0 of course is the first element in the the list. The argument role is the enum value of the property described by the roleNames method.
• Since we have dynamic properties in the objects that are added to this model, the concept of roles are not needed; therefore, to satisfy our contract with QAbstractListModel, we will only have one dummy role (see the roleNames bullet point below).
• The implementation of this method is simply returning an item at index of the m_data list where we store our data. We must wrap our object in a QVariant to satisfy the method signature. Since we only have one dummy role, we will wrap the role argument with Q_UNUSED to avoid compiler warnings.

QVariant DataObjectModel::data(const QModelIndex &index, int role) const
{
    Q_UNUSED(role)
    return QVariant::fromValue(m_data[index.row()]);
}

• roleNames - This method is a mapping of role enums to string values of their keys. Since we are allowing dynamic roles, we essentially only have one value here which refers to our object, called dataObject. This value is a dummy role but is still used on the QML side to refer to the object inside of a delegate, i.e. in a QtQuick view element, e.g. ListView
• The implementation of this method simply returns a QHash with one role. We use a static QHash variable called pHash as this preserves the map through consequent calls to the roleNames() method.

QHash<int, QByteArray> DataObjectModel::roleNames() const
{
    static QHash<int, QByteArray> *pHash;
    if (!pHash) {
        pHash = new QHash<int, QByteArray>;
        (*pHash)[Qt::UserRole + 1] = "dataObject";
    }
    return *pHash;
}

Now we have implemented the features required by the QAbstractListModel contract. What's left?

Well, so far, we have built a wrapper to our data set held by the member variable m_data. If you have noticed, there is nothing in this variable. m_data is empty and our count is 0.

Inserting Data Objects into the DataObjectModel

Let's discuss how we can get data into our model and subsequently into our member variable m_data. We of course have the API methods insert(.., ..) and append(..) that we must implement:

• append - Appending an object to our model simply involves us appending the object to our list variable, m_data, and emitting the necessary change signals – to adhere to our contract – so the user of our QAbstractListModel implementation knows that our data has been updated.
• The implementation of this method starts by retrieving the current count of the data set. As we are appending an object to the end of our list, we can use this count value to instruct the QAbstractListModel interface as to where we are inserting our rows using the beingInsertRows method. We then append our object to the list m_data. Since count was a Q_PROPERTY, it is advisable to emit a changed signal as anyone who is bound to this on the QML side should receive an update when an object is appended. Finally, signal through the QAbstractListModel that we are done with the endInsertRows method.

void DataObjectModel::append(QObject *o) {
    int i = m_data.size();
    beginInsertRows(QModelIndex(), i, i);
    m_data.append(o);
    
    // Emit changed signals
    emit countChanged(count());
    
    endInsertRows();
}

• insert - Inserting an element allows a user to insert an object to a specified index of the model.
• The implementation is nearly identical to the implementation of the append method:

void DataObjectModel::insert(QObject *o, int i)
{
    beginInsertRows(QModelIndex(), i, i);
    m_data.insert(i, o);

    // Emit changed signals
    emit countChanged(count());

    endInsertRows();
}

It is not necessary to invoke a beginMoveRows for the rows that are displaced by this insertion. In my testing, this seems to be handled internally.

See the Qt Documentation for more information regarding beginInsertRows

It seems we have implemented the entire API for DataObjectModel! Slow down, we have one more thing to do. Remember how we wanted to use DataObjectModel in QML?

DataObjectModel {
    id: _dataObjectModel
    
    MusicTrack {
        title: "The first track"
        artistName: "John Doe"
        duration: 230213
    }
    MusicTrack {
        title: "The second track"
        artistName: "John Doe"
        duration: 123111
    }
    MusicTrack {
        title: "The third track"
        artistName: "John Doe"
        duration: 12239991
    }
}

ListView {
    ...
    model: _dataObjectModel
}

The MusicTrack objects are children of the DataObjectModel. Sadly, being children of an object is not enough for us to be able to automatically insert them into our list m_data. We need add a default property to where the MusicTrack or any other QObject-derived class will be parented to when placed inside the DataObjectModel QML block.

DataObjectModel {
    // How do we get any element that is instantiated here to be
    // added to our model?
}

Let's start by defining the QQmlListProperty that will be holding a reference to the our MusicTrack objects.

Add a new public method called content that is a QQmlListProperty of QObject, i.e. QQmlListProperty<QObject>

dataobjectmodel.h

...
public:
    explicit DataObjectModel(QObject *parent = nullptr);
    QQmlListProperty<QObject> content();
...

This QQmlListProperty will define callbacks that will be executed whenever the QML object tree is modified.

We can see how this works in our implementation of the content() method. We have added 4 slots or callbacks to the return value for appending, count, at and clear.

We will declare and define these static slots later.

dataobjectmodel.cpp

QQmlListProperty<QObject> DataObjectModel::content()
{
    return QQmlListProperty<QObject>(this,
                                     0,
                                     &DataObjectModel::dataObjectAppend,
                                     &DataObjectModel::dataObjectCount,
                                     &DataObjectModel::dataObjectAt,
                                     &DataObjectModel::dataObjectClear);
}

QQmlListProperty will call those static slots for append, count, at, and clear whenever an element is modified in the QML object tree. We pass in this, or a reference to the DataObjectModel instance itself into the QQmlListProperty constructor so we can get a reference to it in the implementation of the static callbacks below.

See Qt Documentation for more information.

Let's define these methods:

dataobjectmodel.h

...
public slots:
    static void dataObjectAppend(QQmlListProperty<QObject> *list, QObject *e);
    static int dataObjectCount(QQmlListProperty<QObject> *list);
    static QObject* dataObjectAt(QQmlListProperty<QObject> *list, int i);
    static void dataObjectClear(QQmlListProperty<QObject> *list);
...

And declare them:

dataobjectmodel.cpp

...
void DataObjectModel::dataObjectAppend(QQmlListProperty<QObject> *list, QObject *o)
{
    DataObjectModel *dom = qobject_cast<DataObjectModel*>(list->object);
    if (dom && o) {
        dom->append(o);
    }
}

int DataObjectModel::dataObjectCount(QQmlListProperty<QObject> *list)
{
    DataObjectModel *dom = qobject_cast<DataObjectModel*>(list->object);
    if (dom) {
        return dom->m_data.count();
    }
    return 0;
}

QObject *DataObjectModel::dataObjectAt(QQmlListProperty<QObject> *list, int i)
{
    DataObjectModel *dom = qobject_cast<DataObjectModel*>(list->object);
    if (dom) {
        return dom->get(i);
    }
    return 0;
}

void DataObjectModel::dataObjectClear(QQmlListProperty<QObject> *list)
{
    DataObjectModel *dom = qobject_cast<DataObjectModel*>(list->object);
    if (dom) {
        dom->m_data.clear();
    }
}
...

For each of these callbacks, we simply grab a reference to our DataObjectModel instance and execute commands to manipulate our data set represented by the member variable m_data.

Each MusicTrack object would be received as an argument o into the dataObjectAppend function.

Finally, to ensure the MOC associates the content method as the DataObjectModel's default property, we must add two lines, one for the Q_PROPERTY declaration and another with the Q_CLASSINFO declaration.

...
// Include the QQmlListProperty class
#include <QQmlListProperty>

class DataObjectModel : public QAbstractListModel {
    Q_OBJECT
    Q_DISABLE_COPY(DataObjectModel)
    Q_PROPERTY(int count READ count NOTIFY countChanged)

    // Add these two lines
    Q_PROPERTY(QQmlListProperty<QObject> content READ content)
    Q_CLASSINFO("DefaultProperty", "content")
...

Voila! Your class is now ready to use in QML. Simply register it via qmlRegisterType and you can begin using it!

Example Usage

import QtQuick 2.7

Window {
    id: root
    
    DataObjectModel {
        id: _dataObjectModel

        MusicTrack {
            title: "The first track"
            artistName: "John Doe"
            duration: 230213
        }
        MusicTrack {
            title: "The second track"
            artistName: "John Doe"
            duration: 123111
        }
        MusicTrack {
            title: "The third track"
            artistName: "John Doe"
            duration: 12239991
        }
    }

    ListView {
        anchors.fill: parent
        model: _dataObjectModel
        delegate: Item {
            width: ListView.view.width
            height: 40
            
            Text {
                anchors.centerIn: parent
                font.bold: true
                // NOTE: This is where the roleName comes into play
                // There is a magic object called "dataObject" that references the
                // MusicTrack object for this particular index
                text: dataObject.title + " by " + dataObject.artistName
            }
        }
    }
}

And that's it!

Sample code is available in the qml.guide GitHub repository.

What is QML and QtQuick?

QML, or Qt Markup Language, is a declarative language used to simplify the development with its neatly organized grammatical structure. QML is used to build QtQuick, to assist in building complex user interfaces. It's an easy to learn Javascript-based declarative markup and allows the quick creation and deployment of GUIs.

Getting Started with Qt/QML

Download the Qt online installer for the best installation and setup. This installer will also assist you in installing mobile versions for iOS and Android; including any dependencies that are needed.

Preferred installation method: Qt Installer

Offline and online installers are available here.

• A qt.io account is needed to install.
• Edit: As reader @Larpon reports, it is possible to skip the login step in the installer.
• Build Kits are setup properly in QtCreator.

Alternate installation method

You may use repository installation. Do note that these installs may require additional setup. You will also need to download the QtCreator IDE separately.

• A qt.io account is not needed when using this method.
• Build Kits require additional setup in QtCreator.

# On macOS with homebrew:
brew install qt5

# On Ubuntu with apt:
sudo apt-get install qt5

QtCreator

QtCreator is the preferred IDE for Qt-based projects.

Start by downloading and installing the Qt SDK which includes the Qt libraries and the Qt Creator IDE.

Once you've installed the Qt SDK, go ahead and launch QtCreator, the well-built IDE for anything Qt. Create a new project. Choose a new Qt Quick Application which will allow maximum flexibility in creating C++/QML hybrid applications.

Choose a name for your project. The name you place in here can be changed later by simply renaming the *.pro file that is created.

In this example, QtCreator will automatically create two folders:

$ ls /Users/niraj/Work/qmlguide/examples/
- ExampleQtQuickApplication/
- build-ExampleQtQuickApplication-Qt510-Debug/

Build Systems

A variety of build systems are supported by QtCreator.

qmake

qmake is Qt's original build system. It uses an esoteric language to generate Makefiles which are then used by the make tool to build code into binaries.

qmake is the preferred build system when building Qt code for multiple supported platforms, i.e. iOS and Android.

I have found it difficult to integrate other open source projects with qmake-based projects cleanly. This can always be supported by wrapping qmake in bash-based build scripts.

The qmake tool helps simplify the build process for development projects across different platforms. It automates the generation of Makefiles so that only a few lines of information are needed to create each Makefile. You can use qmake for any software project, whether it is written with Qt or not.

CMake

CMake is an open source build tool used for many C/C++ projects.

CMake is preferred if the platform is not iOS / Android. I have found CMake the better option as it can be easily integrated with many open source applications / projects. It is also really well documented.

CMake is an open-source, cross-platform family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice.

QBS

This is a relatively new build system, maintained by Qt, based on the QML language.
More information can be found here.

Qbs is a tool that helps simplify the build process for developing projects across multiple platforms. Qbs can be used for any software project, regardless of programming language, toolkit, or libraries used.

Building and Running

Hit the green play button and your project will build and run!

You will now see a blank window similar to this:

QtQuick - Basic Elements

QML is a language, QtQuick is a UI framework built on top of Qt in the QML language.

Item - This element is the absolute basic element. It is a pure QQuickItem with no visible or drawn pixels. Every QML element extends the Item element. I generally use this element as a wrapper element for pages, screens, dialogs, etc. It's generally preferred for structures over the Rectangle element due to it's undrawn and invisible nature.

anchors is a object property of Item that allows you to position any Item-derived element relative to any other Item-derived element. This is one of the greatest features of QML when designing GUIs for multiple resolution.

Rectangle - This element is basically an Item element with a colored fill. It is possible to have an uncolored Rectangle by using color: "transparent" as a property. Again, Item is usually preferred to a Rectangle due to this colored fill. It is more efficient to use an Item as a wrapper as it reduces the number of pixels required to be drawn; especially on GL graphics views where the entire screen is repainted when one pixel is changed.

Another advantage of the Rectangle element over the Item element is that it contains a border property. This can prove useful when one requires other items, such as Images, to be surrounded by a colored border of variable width. See more properties of Rectangle in the Qt Documentation.

Image - This element is used to load an image, from a local file or from a URL. It is important to understand the asynchronous property of the Image element. By default, if your source is a local file, asynchronous: false is default. If your source is a network file (indicated by the http search path), asynchronous: true would be the default.

This is an important consideration when building GUIs with image-based structures, or GUIs that rely on the width/height of the image that's expected to be loaded. We'll go over more of this later on in this guide. View the Qt documentation for more helpful properties of the Image element.

BorderImage - This element is great for using one graphic at multiple width/height scenarios. This is very similar to Android's 9-patch image drawing mechanism – with the main difference being the BorderImage only allows for one stretchable zone in the x or y direction. Android's 9-patch allows for multiple stretch zones.

A Qt port is available in QtQuick Controls in the Android style here.

This element is very useful when building different sized buttons with the same graphic. View the Qt documentation for several visual examples.

Gradient - This element draws a color-blend (gradient). It can be assigned to the gradient property of Rectangle.

Text - This element is the preferred choice when displaying text on a GUI. This element accepts HTML as an input to the text property. This will prove useful when you need to bold or italicize only parts of text; for example, text: "<b>Name:</b>John Doe". You will need to consider alignment whenever using the Text element. Lucky for us, the guys at Qt developed a very intuitive method of aligning any piece of text.

Here're a couple examples you can refer to when dealing with text:

When dealing with paragraphs of text, maximumLineCount, wrapMode, and elide will prove immensely useful.

Combining a Text element with a Flickable element can give you a neat panning effect for scrollable Text views. Just set the Flickable's contentWidth and contentHeight to the Text element's paintedWidth and paintedHeight respectively.

TextEdit - This element can be used to provide keyboard input into your GUI. I prefer using a heavily modified Text element to achieve this task when using a touchscreen device as this element doesn't provide the flexibility in alignment and fill as the Text element. View more information about TextEdit in the Qt Documentation.

MouseArea - This element allows hitareas to be placed in your GUIs. This element (using anchors) can fill every Item-derived element with a hitarea. It is generally acceptable to subclass the basic MouseArea element with a MouseArea element that contains anchors.fill: parent as the MouseArea must know who to apply the hitarea to; in more cases than not, the MouseArea will fill it's parent.

The Qt MouseEvent system employs three crucial mouse events; including press, release, and click. A click is always built of one press and one release. Mouse events always follow this order: press, release, click. A click is only achieved if the press and release occur on the same MouseArea.

This is an important concept when building GUIs for touchscreen devices where a user may accidentally "press" a button, but "release" over another part of the GUI. This will have no effect on the GUI as the click event will not be created. This allows the user to change their mind while navigating a GUI.

Also, when building GUIs for touchscreens, one must take into consideration the touch resolution of the touchscreen. If a resistive touchscreen is used, accuracy can be within ~20%. By increasing the size of the mousearea relative to the button it is covering, can allow a more user-friendly experience. To do this, use anchors.centerIn: parent assuming the parent is the button. Then, set the width and height of the MouseArea to 1.5x the width and height of the intended button target.

The MouseArea element also contains several drag properties to allow dragging of any Item-derived element across a screen. This is particularly tricky as you would have to implement a position persisting mechanism to triumph the deletion of any QML components. Read more about the MouseArea in the Qt Documentation.

QtQuick View Elements

View elements in QtQuick strictly adhere to the model-view paradigm in that each View element we cover in this section has a model and a delegate property.

The model can be a ListModel, XmlListModel, QAbstractListModel, a QList of QObjects, a QStringList, and several other Javascript-based data structures. See here for more information about data models.

The delegate is generally a Component-based object that you would like to repeat. For a list view of text, this would be a rectangle with text in it. For a coverflow-esque carousel, this would be an image. Components are useful in low-resource environments as they're not instantiated until needed.

ListView - This element is useful in creating lists or carousels of objects. The ListView element does not allow a repeating or circular carousel. The ListView element can be positioned horizontally or vertically using the orientation property.

ListView inherits Flickable; allowing developers to modify the contentX and contentY of the element.

PathView - This element is useful in creating more customized carousels of objects. The PathView includes an additional path property and a pathItemCount property that allows you to set the track on which the objects move around the view. The PathView is always a repeating or circular view. The PathView element can be positioned horizontally, vertically, diagonally, along any axis using the path property with the Path element. The PathAttribute property helps add different attributes for objects on different parts of the path make the PathView one of the most flexible views available in QtQuick.

PathView does not inherit Flickable. If you're trying to modify the position of an item along a PathView, consider the highlightRangeMode by modifying the preferredHighlightBegin and the preferredHighlightEnd of your PathView.

The choice between a ListView element and a PathView element for your next carousel or list relies on one simple fact: Does your view need to repeat? If so, you need a PathView. Does your view require non-straight paths? If so, you need a PathView.

GridView - This element is useful in creating grids of objects. GridView relies on two important properties, cellWidth and cellHeight to properly calculate the size of each object's wrapper. The component delegate would be placed within this cell.

GridView also inherits Flickable; allowing developers to modify the contentX and contentY of the element.

Design Pattern: Singletons

The Singleton design pattern is a useful software design pattern for Qt/QML applications that need access to certain services or logic-heavy backend components.

My favorite explanation of the problem solved by the singleton design pattern:

The application needs one, and only one, instance of an object. Additionally, lazy initialization and global access are necessary.
By SourceMaking.

Method 1: Exposing a Qt C++ Class as a QML Singleton

Qt's preferred way to expose a Qt C++ Class as a QML Singleton is by using qmlRegisterSingletonType which is fairly well documented.

This method can be used to register a singleton provider (basically an instance() method with a different signature) of a certain class to a uri which can then be imported in QML through a QQuickExtensionPlugin.

The singleton provider, or instance method, is called by the QQmlEngine when the singleton is first used in QML – and not when the import is first used.

Because of this behavior, it is very difficult to precisely control the instantiation of the singleton object.

In this example, we are using a singleton called Theme to build up a custom Text element:

import QtQuick 2.7
import QmlGuide 1.0

Text {
    font.pixelSize: Theme.adjustedFontSize(24)
    font.family: Theme.fontFamily
}

The singleton called Theme is under the QmlGuide 1.0 import. This import is where we want to register our Theme class:

qmlRegisterSingletonType("QmlGuide", 1, 0, "Theme", Theme::singletonProvider);

The last argument in the qmlRegisterSingletonType macro is a callback, defined as QObject *(*callback)(QQmlEngine *, QJSEngine *).

This callback is invoked the first time the Theme singleton is used, i.e. in the example above, the Theme::singletonProvider callback is executed when font.pixelSize is set to Theme.adjustedFontSize(24).

In this example, the Theme::singletonProvider callback would never be executed, and therefore, the Theme object would never be created, even though import QmlGuide 1.0 is specified:

import QtQuick 2.7
import QmlGuide 1.0

Text {

}

This can potentially lead to dangerous code follies, as the simplest case of a developer logging the Theme object can create the singleton:

import QtQuick 2.7
import QmlGuide 1.0

Text {
    Component.onCompleted: {
        console.log("Theme: ", Theme);
    }
}

Generally, once a developer sees the Theme singleton being logged in the example above – they will automatically assume the Theme object is being initialized correctly. However, once the console.log statement is removed, the Theme object is no longer initialized.

For most users, this behavior of extreme lazy instantiation is perfectly okay. For those users who are focused on performance optimization or application start up times, may find this a PITA.

Method 2: Using the QmlEngine's root context to set context properties

This method counters method #1 in stating clearly that:

I do not want the QmlEngine to manage my singletons – I will manage them myself.

QmlContext allows us to manipulate the context hierarchy of a tree of elements within a QmlEngine.

This feature can be used to add global properties to all QML files within a single QmlEngine. This allows us to replicate the behavior of a singleton by exposing a QmlContext property through the QmlEngine::rootContext

In the Theme class, we can define a registerSingleton(..) method:

...

void Theme::registerSingleton(QQmlEngine *qmlEngine)
{
    if (!s_instance) {
        s_instance = new Theme(qmlEngine);
    }
    QQmlContext *rootContext = qmlEngine->rootContext();
    rootContext->setContextProperty("Theme", s_instance);
}

...

Now, in main.cpp, we can invoke this method by passing in a reference to the QQmlEngine object:

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;

    Theme::registerSingleton(&engine);

    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

Now, we can use the Theme object in QML:

...

Text {
    anchors.centerIn: parent
    font.pixelSize: 42
    font.family: Theme.fontFamily

    text: "Hello World"
}
    
...

Note that the import QmlGuide 1.0 statement is no longer necessary as the Theme object was registered to the rootContext of the QQmlEngine which means it is available in all QML files that are built by this QQmlEngine.

As can be seen, the statement:

Theme::registerSingleton(&engine);

can be invoked in any order the developer sees fit. This helps when tuning an application for startup and even for runtime performance. If a QML developer tries to use the Theme object before it is instantiated, a warning will be output. And as always, warnings guide developers between good practices and evil ones.

Sample code is available in the qml.guide GitHub repository.

Qt provides many different methods of exposing data and using data in QML Model Views, i.e. the ListView, PathView, or GridView

Over this many part series of posts, we will investigate the many methods of exposing data to QML views – starting from the simplest, to the most complex.

QML / Javascript Array

The simplest method is using a Javascript array to feed primitive type-based data into a ListView.

All QML delegates inside a model view contain a model property that represents the data for that particular index in the data model array.

In this example, the data model is a JS array – therefore, the data is available directly through the modelData property of the model object.

Qt documentation uses magic to demonstrate this. They use modelData directly since this pointer is available as a context property of the delegate. It is optional to reference the color value using model.modelData but it is more verbose to a bystander reading the code.

import QtQuick 2.5

Item {
    id: root
    
    property var colors: ["red", "white", "blue"]

    width: 640; height: 480

    ListView {
        id: _listView
        anchors.fill: parent

        model: root.colors
        delegate: Rectangle {
            id: _rectangleDelegate
            width: ListView.view.width
            height: ListView.view.height / 3
            
            // Use the colors array to change
            // the color of this Rectangle
            color: model.modelData

            // Many times developers misuse
            // model views by accessing the array
            // directly, i.e.
            // color: root.colors[model.index]
            // or
            // color: root.colors[index]
        }
    }
}

QML has grown to be a fairly unstructured language. It may be due to its heritage as a rapid prototyping language or possibly its javascript lineage.

Because of this, many C++ developers find it difficult to organize QML for scalability.

Here is a coding standard that has evolved over many years of QML experience. It provides a well structured approach to creating identifiers for objects as well as a clean hierarchical approach to defining properties.

Let's have a look:

import QtQuick 2.5

Item {
    id: root

    signal clicked
    property alias text: _textButton.text

    function open() { }
    function close() { }

    Rectangle {
        id: _rectangleButton
        anchors.centerIn: parent
        width: 100
        height: 40

        Text {
            id: _textButton
            anchors.fill: parent
            anchors.margins: 4

            horizontalAlignment: Text.AlignHCenter
            verticalAlignment: Text.AlignVCenter
            elideMode: Text.ElideRight
        }

        MouseArea {
            id: _mouseAreaButton
            anchors.fill: parent
            onClicked: { 
                root.clicked();
            }
        }
    }
}

The General Rules

Here are a collection of general rules to follow to ensure every developer has equal opportunity for QML code structure and scalability. These techniques work very well in projects ranging from a few lines of code to 100,000+ lines of code.

The top-most element of every page must have root as its identifier.

Using root as the identifier creates a known standard for every QML component separated into its own QML file. This speeds up development as the developer knows the root element of a document is identified as root.

All identifiers (with the exception of the root element as well as QtObject elements) must follow this indistinguishable format, _[componentName][componentDescription]

Using _[componentName][componentDescription] allows for a clean standardization of element identifiers. It allows a developer to know what type of component they are referencing to. When paired with developer knowledge of the codebase; specifically QML element types, this single guideline can save hours of developer time.

...
Item {
    id: _itemContainer
    // ...
}
...

...
Button {
    id: _buttonOpenList
    // ...
}
...

...
ListView {
    id: _listViewAlbums
    // ...
}
...

Hierarchical Order of Declarations

A common hierarchy promotes code sustainability and clarity. This guideline is similar to a Q_PROPERY/public/private/protected/signals/slots hierarchy in C++.

// Qt imports first, then custom imports
import QtQuick 2.5
// Alias Qt imports that are rarely used (that a developer wouldn't understand)
import QtGraphicalEffects 1.0 as QGE

import custom.import 1.0