rust_qt_binding_generator 0.2.2

Generate code to build Qt applications with Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191

# Rust Qt Binding Generator

![Rust Qt Binding](demo/rust_qt_binding_generator.svg)

This code generator gets you started quickly to use Rust code from Qt and QML. In other words, it helps to create a Qt based GUI on top of Rust code.

Qt is a mature cross-platform graphical user interface library. Rust is a new programming language with strong compile time checks and a modern syntax.

## Getting started

There are two template projects that help you to get started quickly. One for [Qt Widgets](templates/qt_widgets) and one for [Qt Quick](templates/qt_quick). Just copy these folders as new project and start coding.


<table style="font-size: larger">
 <tr>
  <td style="background:#676767; color: white">Qt Widgets (main.cpp) / Qt Quick (main.qml)</td>
  <td>&#10229; UI code, written by hand</td>
 </tr>
 <tr>
  <td style="background:#3daefd">src/Binding.h</td>
  <td rowspan="3" style="valign: center">&#10229; generated from binding.json</td>
 </tr>
 <tr>
  <td style="background:#3daefd">src/Binding.cpp</td>
 </tr>
 <tr>
  <td style="background:#3daefd">rust/src/interface.rs</td>
 </tr>
 <tr>
  <td style="background:#676767; color: white">rust/src/implementation.rs</td>
  <td>&#10229; Rust code, written by hand</td>
 </tr>
</table>

To combine Qt and Rust, write an interface in a JSON file. From that, the generator creates Qt code and Rust code. The Qt code can be used directly. The Rust code has two files: interface and implementation. The interface can be used directly.

```json
{
    "cppFile": "src/Binding.cpp",
    "rust": {
        "dir": "rust",
        "interfaceModule": "interface",
        "implementationModule": "implementation"
    },
    "objects": {
        "Greeting": {
            "type": "Object",
            "properties": {
                "message": {
                    "type": "QString",
                    "write": true
                }
            }
        }
    }
}
```

This file describes an binding with one object, `Greeting`. `Greeting` has one property: `message`. It is a writable property.

The Rust Qt Binding Generator will create binding source code from this description:

```bash
rust_qt_binding_generator binding.json
```

This will create four files:

* *src/Binding.h*
* *src/Binding.cpp*
* *rust/src/interface.rs*
* rust/src/implementation.rs

Only `implementation.rs` should be changed. The other files are the binding. `implementation.rs` is initialy created with a simple implementation that is shown here with some comments.

```rust
use interface::*;

/// A Greeting
pub struct Greeting {
    /// Emit signals to the Qt code.
    emit: GreetingEmitter,
    /// The message of the person.
    message: String,
}

/// Implementation of the binding
/// GreetingTrait is defined in interface.rs
impl GreetingTrait for Greeting {
    /// Create a new greeting with default data.
    fn new(emit: GreetingEmitter) -> Greeting {
        Greeting {
            emit: emit,
            message: "Hello World!",
        }
    }
    /// The emitter can emit signals to the Qt code.
    fn emit(&self) -> &GreetingEmitter {
        &self.emit
    }
    /// Get the message of the Greeting
    fn message(&self) -> &str {
        &self.message
    }
    /// Set the message of the Greeting
    fn set_message(&mut self, value: String) {
        self.message = value;
        self.emit.message_changed();
    }
}
```

The building block of Qt and QML projects are QObject and the Model View classes. `rust_qt_binding_generator` reads a json file to generate QObject or QAbstractItemModel classes that call into generated Rust files. For each type from the JSON file, a Rust trait is generated that should be implemented.

This way, Rust code can be called from Qt and QML projects.

### Qt Widgets with Rust

This C++ code uses the Rust code written above.

```cpp
#include "Binding.h"
#include <QDebug>
int main() {
    Greeting greeting;
    qDebug() << greeting.message();
    return 0;
}
```

### Qt Quick with Rust

This Qt Quick (QML) code uses the Rust code written above.

```qml
Rectangle {
    Greeting {
        id: rust
    }
    Text {
        text: rust.message
    }
}
```

## Demo application

The project comes with a demo application that show a Qt user interface based on Rust. It uses all of the features of Object, List and Tree. Reading the demo code is a good way to get started.

<figure>
  <img src="demo/screenshots/demo.png" alt="Qt Widgets UI with Rust logic"/>
  <figcaption><a href="demo/src/main.cpp">Qt Widgets UI</a> with <a href="demo/rust/src/implementation/file_system_tree.rs">Rust logic</a></figcaption>
</figure>

<figure>
  <img src="demo/screenshots/demo2.png" alt="Qt Quick Controls UI with Rust logic"/>
  <figcaption><a href="demo/qml/DataAndChart.qml">Qt Quick Controls UI</a> with <a href="demo/rust/src/implementation/time_series.rs">Rust logic</a></figcaption>
</figure>

<figure>
  <img src="demo/screenshots/demo3.png" alt="Qt Quick Controls 2 UI with Rust logic"/>
  <figcaption><a href="demo/qml/FileTreeView2.qml">Qt Quick Controls 2 UI</a> with <a href="demo/rust/src/implementation/file_system_tree.rs">Rust logic</a></figcaption>
</figure>

## Docker development environment

To get started quickly, the project comes with a `Dockerfile`. You can start a docker session with the required dependencies with `./docker/docker-bash-session.sh`.

## More information on Qt

* [Initial blog post](https://www.vandenoever.info/blog/2017/09/04/rust_qt_binding_generator.html)

### Tutorials

* [Rust and QML: a timely example](https://www.vandenoever.info/blog/2017/09/10/time_for_rust_and_qml.html)
* [To do a Rust GUI](https://www.vandenoever.info/blog/2018/06/09/to-do-a-rust-gui.html)
* [Browsing your mail with Rust and Qt](https://www.vandenoever.info/blog/2018/09/16/browsing_your_mail_with_rust_and_qt.html)

### Presentation

* [Qt GUIs with Rust](https://archive.fosdem.org/2018/schedule/event/rust_qt_binding_generator/)

### Information on Qt

* [Qt](http://doc.qt.io/)
* [Qt Examples and tutorials](http://doc.qt.io/qt-5/qtexamplesandtutorials.html)
* [The QML Book](https://qmlbook.github.io/)

## Issues

Please [report bugs and feature requests](https://bugs.kde.org/enter_bug.cgi?product=rust-qt-binding-generator) in the KDE issue tracker, product "rust-qt-binding-generator".