Jolla and SailfishOS

2017-04-06 11:35

Linking C++ and QML code

While JavaScript (which QML is a version of) is a good tool for the presentation layer, I'm not eager to write all my business logic in it. There are many reasons why that is. But that is a discussion for some other time. Let's for now just stick with the argument, that there a many problems already solved in C/C++ libraries and there should be no reason to reinvent the wheel, just because you change the presentation layer.

There are two main reasons why I decided to have a look at Qt/QML (and hence Silica):

• Support for multiple platforms
• C/C++ binding

The multi-platform support I leave for some other project. For now, just look up the Internet if you are eager to learn more about it.

For D-Bus Inspector I was interested in how to make code written in C(++) available to a QML application.

It turns out that this not to hard to do.

C++ code

To test how to use C++ code from within QML we first need some C++ code.

Since this App is about accessing the D-Bus, I decided that the task of my first class should be to provide a list of the services available on the D-Session-Bus.

It is declared in dSessionBusServicesModel.h

• I base my service list on a QAbstractListModel, which provides the foundation that is needed to be able to use an object of the class as the list model for a QML widget (line 6).
• For being able to use this class in the QML context, we have to use the Q_OBJECT macro (line 8).
• Next we declare symbolic names for the fields (roles) indices of each entry in the list (line 10..12).
  We only have one (user) field per entry: NameRole - the name role = index of the field where we going to store the name of a service found.
• Line 14 declares an overload-constructor.
• In line 16 we (in-line) overload the rowCount(...) method of QAbstractListModel, so it returns the number of entries in the QVector serviceNames (see below).
• Line 17 declares an overload for QAbstractListModel's data(...) method (defined in dSessionBusServicesModel.cpp).
• Line 19 declares an overload method for the roleNames() method of QAbstractListModel.
• In line 21 we declare the new method getServiceName(...) and use the macro Q_INVOKEABLE to make it callable from the QML context.
• Finally in line 24 we define the private field serviceNames as a QVector of QStrings, that will hold the names of the services found on the D-Session-Bus.

dSessionBusServicesModel.cpp implements the DSessionBusServicesModel methods declared in it's .h file:

• We are going to access the D-Bus using the Qt library. So we import it's headers in line 1.
• Lines 5..15 hold the implementation of an overload constructor.
  • In line 8 the registered service names of the D-Session-Bus are fetched, using a method of the QDBusConnection class.
  • The result of the call is assigned to the reply variable.
  • In line 9 we test if the call was successful, by calling the isValid() method of the QDBusReply object reply.
  • The error handling in lines 10..11 has room for improvement, but for now we only log an error message to qDebug and kill the program with exit code 1.
  • If the call was successful we eventually reach line 13..14, in which the names of the services found are transferred from the (local) reply.value() QStringList to our object's QVector<QString> serviceNames.
• Lines 17..21 override QAbstractListModel's roleNames() method to return a QHash-table that describes our list model entries data structure.
  Since we only have one (user) field in each entry - the name field - our hash-table has only one entry, assigned in line 19.
• Lines 23..31 override QAbstractListModel's data() method that is used e.g. by widgets using the model to query a single field (int role) of a specific list entry (&index).
• For a more convenient access to the service names, we declared the getServiceName(...) method, that is implemented in lines 33..38.
  It returns a QString with the name stored at index i in serviceNames or an empty QString, if i is out of bounds of serviceNames.

QML type registering

So the model is pretty simple. We now just have to make it available in QML.

This is done by registering the type (class) with the QML system.

In the D-Bus Inspector project I do this in harbour-dbus-inspector.cpp, which provide the main() entry point for the application.

• In line 15 we include the header file of our class.
• In lines 21..24 we register the class with the QML system.
  • Line 21 tells QML which class to register (must be Q_OBJECT).
  • Line 22 declares the package name and version.
    Here you have to follow Jolla Harbour's naming rules for custom packages or the RPM validator will throw you out.
  • Line 23 declares the name you want to use in QML to access you C++ class.

QML type usage

All preparations down, we can now use our newly declared C++/QML type, like any native one.

• In line 4 we import the package.
• Since our class is a child of QAbstractListModel we can create an instance of it for the model property of e.g. a SilicaListView, as done in line 60.
  This creates a new instance of the DSessionBusServicesModel class, calling the overload constructor, that in turn fills the QVector<QString> serviceNames.

There is not much more to it. The rest is like using any other list model in QML:

• delegate in line 64 is called for each entry in the model to create a visual representation:
  • We can use name to access the value of this property of the current entry in the model (as done in line 70), since the list view has the hash-table DSessionBusServicesModel::roleNames() to find the index for name, used in DSessionBusServicesModel::data(...) to get the value (= service name).
• When the user selects a Label of the listView, onClick() is called (lines 75..79).
  The index of the label selected is available in onClick(). We can use it to extract the name of the service associated with the label by calling DSessionBusServicesModel::getServiceName(index), as done e.g. in line 78.

Summary

Using:

• An arbitrary Q_OBJECT class as an "interface" class
• qmlRegisterType<...>(...)
• And than an instance of the registered type in QML

Once we have created an instance of our "interface" Q_OBJECT, we are free to use it's Q_INVOKEABLE methods to invoke from the QML context any C/C++ code we desire.