advanced-connect_backend.md 4.77 KB
Newer Older
Jonah Brüchert's avatar
Jonah Brüchert committed
1
2
---
title: Connect logic to your QML user interface
3
weight: 203
Jonah Brüchert's avatar
Jonah Brüchert committed
4
description: Connect a backend to do calculations and supply your user interface with data to display
5
group: advanced
Jonah Brüchert's avatar
Jonah Brüchert committed
6
7
---

Carl Schwan's avatar
Carl Schwan committed
8
To integrate logic into the application, we need C++ backend classes that can do the important calculations. Writing logic in the QML files is discouraged, so try to move as much as possible to the backend, so QML is purely used for displaying the user interface, which is what it is best at.
Jonah Brüchert's avatar
Jonah Brüchert committed
9
10
11

For your new backend class, create two new files called `backend.cpp` and `backend.h`. Don't forget to add the new cpp file to the executable in `src/CMakeLists.txt`, next to main.cpp.

Carl Schwan's avatar
Carl Schwan committed
12
Add the following content to the new header file (the one with the `.h` extension):
Jonah Brüchert's avatar
Jonah Brüchert committed
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
```C++
#pragma once

#include <QObject>

class Backend : public QObject
{
    Q_OBJECT

public:
    explicit Backend(QObject *parent = nullptr);
};
```

The cpp file containing the definitions is similarly empty right now, it should contain something like the following:
```C++
#include "backend.h"

Backend::Backend(QObject *parent)
    : QObject(parent)
{

}
```

Carl Schwan's avatar
Carl Schwan committed
38
Currently the user interface doesn't know about your backend class. To change that, we need to register the new type in `main.cpp`. The backend will be created as a singleton, that means it will only be created once and exist through the whole time from starting the application to closing it.
Jonah Brüchert's avatar
Jonah Brüchert committed
39
40

To `main.cpp`, right after creating the `QQmlApplicationEngine`, add the type registration as follows:
Carl Schwan's avatar
Carl Schwan committed
41
```C++
Jonah Brüchert's avatar
Jonah Brüchert committed
42
43
44
45
    Backend backend;
    qmlRegisterSingletonInstance<Backend>("org.kde.example", 1, 0, "Backend", &backend);
```

Carl Schwan's avatar
Carl Schwan committed
46
Don't forget to include the new header file at the top of `main.cpp`.
Jonah Brüchert's avatar
Jonah Brüchert committed
47

Carl Schwan's avatar
Carl Schwan committed
48
From now on, the backend will be known to QML as `Backend`. It is contained in a module called `org.kde.example`. Since the module is part of the application, you don't need to worry about versioning it, just stay with 1.0 and use it consistently throughout the application.
Jonah Brüchert's avatar
Jonah Brüchert committed
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

In `main.qml`, import the new module:
```QML
import org.kde.example 1.0
```

Now we have connected the class holding the future logic to the application, but it still doesn't do anything. To change that, let's add a property to the class. Properties are a lot more than a simple variable. They can inform the UI about changes so it can update the right areas.

Right under the `Q_OBJECT` macro, add a new `Q_PROPERTY`.

```
Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
```

That seems like quite a lot for a simple property we'll use to show some text from the backend, right?
But a closer look reveals that this can already run logic when the property is read by the user interface, and when it is written. It will automatically inform frontend and backend of changes.

The reading and writing is based on getter and setter functions, so add a new private attribute to your class, like this, and add getter and setter functions.
```C++
private:
    QString m_introductionText = "Hello World!";
```

To the public section, add
Carl Schwan's avatar
Carl Schwan committed
73
```C++
Jonah Brüchert's avatar
Jonah Brüchert committed
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
    QString introductionText() const;
    void setIntroductionText(const QString &introductionText);
    Q_SIGNAL void introductionTextChanged();
```
The first function is the getter, the second the setter, and the third a signal that is emitted when the property was changed. The signal doesn't need any implementation in the cpp file, since it doesn't do much more than being emitted, but the getter and setter need to be implemented similar to the following:
```C++
QString Backend::introductionText() const
{
    return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
    m_introductionText = introductionText;
    Q_EMIT introductionTextChanged();
}
```

As you can see, when the setter is called, the signal will be emitted, and inform the ui and backend of the change.

To display the text, in `main.qml` add a heading displaying it right under the text property of the `Kirigami.Page` element that is already contained in the template.

The resulting code in that part of the file should look like this:
```
        ...
        Kirigami.Page {
            title: i18n("develop.kde.org tutorial")

            Kirigami.Heading {
                anchors.centerIn: parent
                text: Backend.introductionText
            }

            actions {
                main: Kirigami.Action {
                    ...
```

Now compile and start your program again.

Congratulations, you learned:
* How to register backend types to QML
* Add new elements to the QML file
* Create new QObject subclasses
* How to add properties and what they do
* What signals are

If you want to know more about the integration between QML and C++, we recommend reading the [official Qt documentation](https://doc.qt.io/qt-5/qtqml-cppintegration-definetypes.html).