Warning, /sdk/rust-qt-binding-generator/tutorial/rust_qt_binding_generator.md is written in an unsupported language. File is not indexed.

0001 # Rust Qt Binding Generator
0002 
0003 ![Rust Qt Binding Generator (Logo by Alessandro Longo)](rust_qt_binding_generator.svg)
0004 
0005 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.
0006 
0007 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.
0008 
0009 ## Getting started
0010 
0011 There are two template projects that help you to get started quickly. One for [Qt Widgets](https://commits.kde.org/rust-qt-binding-generator?path=templates/qt_widgets) and one for [Qt Quick](https://commits.kde.org/rust-qt-binding-generator?path=templates/qt_quick). Just copy these folders as new project and start coding.
0012 
0013 Here is a small schematic of how files made by the generator are related:
0014 
0015 <table>
0016  <tr>
0017   <td style="background:#676767;color:white;padding:1ex;">Qt Widgets (main.cpp) / Qt Quick (main.qml)</td>
0018   <td>&#10229; UI code, written by hand</td>
0019  </tr>
0020  <tr>
0021   <td style="background:#3daefd;padding:1ex;">src/Binding.h</td>
0022   <td rowspan="3" style="vertical-align:middle;">&#10229; generated from<br/>binding.json</td>
0023  </tr>
0024  <tr>
0025   <td style="background:#3daefd;padding:1ex;">src/Binding.cpp</td>
0026  </tr>
0027  <tr>
0028   <td style="background:#3daefd;padding:1ex;">rust/src/interface.rs</td>
0029  </tr>
0030  <tr>
0031   <td style="background:#676767;color:white;padding:1ex">rust/src/implementation.rs</td>
0032   <td>&#10229; Rust code, written by hand</td>
0033  </tr>
0034 </table>
0035 
0036 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.
0037 
0038 ```json
0039 {
0040     "cppFile": "src/Binding.cpp",
0041     "rust": {
0042         "dir": "rust",
0043         "interfaceModule": "interface",
0044         "implementationModule": "implementation"
0045     },
0046     "objects": {
0047         "Greeting": {
0048             "type": "Object",
0049             "properties": {
0050                 "message": {
0051                     "type": "QString",
0052                     "write": true
0053                 }
0054             }
0055         }
0056     }
0057 }
0058 ```
0059 
0060 This file describes an binding with one object, `Greeting`. `Greeting` has one property: `message`. It is a writable property.
0061 
0062 The Rust Qt Binding Generator will create binding source code from this description:
0063 
0064 ```
0065 $ rust_qt_binding_generator binding.json
0066 ```
0067 
0068 This will create four files:
0069 
0070 * *src/Binding.h*
0071 * *src/Binding.cpp*
0072 * *rust/src/interface.rs*
0073 * rust/src/implementation.rs
0074 
0075 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.
0076 
0077 ```rust
0078 // rust/src/implementation.rs
0079 
0080 use interface::*;
0081 
0082 /// A Greeting
0083 pub struct Greeting {
0084     /// Emit signals to the Qt code.
0085     emit: GreetingEmitter,
0086     /// The message of the greeting.
0087     message: String,
0088 }
0089 
0090 /// Implementation of the binding
0091 /// GreetingTrait is defined in interface.rs
0092 impl GreetingTrait for Greeting {
0093     /// Create a new greeting with default data.
0094     fn new(emit: GreetingEmitter) -> Greeting {
0095         Greeting {
0096             emit: emit,
0097             message: "Hello World!".into(),
0098         }
0099     }
0100     /// The emitter can emit signals to the Qt code.
0101     fn emit(&self) -> &GreetingEmitter {
0102         &self.emit
0103     }
0104     /// Get the message of the Greeting
0105     fn message(&self) -> &str {
0106         &self.message
0107     }
0108     /// Set the message of the Greeting
0109     fn set_message(&mut self, value: String) {
0110         self.message = value;
0111         self.emit.message_changed();
0112     }
0113 }
0114 ```
0115 
0116 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.
0117 
0118 This way, Rust code can be called from Qt and QML projects.
0119 
0120 ### Qt Widgets with Rust
0121 
0122 This C++ code uses the Rust code written above.
0123 
0124 ```cpp
0125 #include "Binding.h"
0126 #include <QDebug>
0127 int main() {
0128     Greeting greeting;
0129     qDebug() << greeting.message();
0130     return 0;
0131 }
0132 ```
0133 
0134 ### Qt Quick with Rust
0135 
0136 This Qt Quick (QML) code uses the Rust code written above.
0137 
0138 ```qml
0139 Rectangle {
0140     Greeting {
0141         id: rust
0142     }
0143     Text {
0144         text: rust.message
0145     }
0146 }
0147 ```
0148 
0149 ## Demo application
0150 
0151 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.
0152 
0153 <figure>
0154   <img src="demo.png" alt="Qt Widgets UI with Rust logic"/>
0155   <figcaption><a href="https://commits.kde.org/rust-qt-binding-generator?path=demo/src/main.cpp">Qt Widgets UI</a> with <a href="https://commits.kde.org/rust-qt-binding-generator?path=demo/rust/src/implementation/file_system_tree.rs">Rust logic</a></figcaption>
0156 </figure>
0157 
0158 <figure>
0159   <img src="demo2.png" alt="Qt Quick Controls UI with Rust logic"/>
0160   <figcaption><a href="https://commits.kde.org/rust-qt-binding-generator?path=demo/qml/DataAndChart.qml">Qt Quick Controls UI</a> with <a href="https://commits.kde.org/rust-qt-binding-generator?path=demo/rust/src/implementation/time_series.rs">Rust logic</a></figcaption>
0161 </figure>
0162 
0163 <figure>
0164   <img src="demo3.png" alt="Qt Quick Controls 2 UI with Rust logic"/>
0165   <figcaption><a href="https://commits.kde.org/rust-qt-binding-generator?path=demo/qml/FileTreeView2.qml">Qt Quick Controls 2 UI</a> with <a href="https://commits.kde.org/rust-qt-binding-generator?path=demo/rust/src/implementation/file_system_tree.rs">Rust logic</a></figcaption>
0166 </figure>
0167 
0168 ## Docker development environment
0169 
0170 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`.
0171 
0172 ## More information
0173 
0174 * [Rust Qt Binding Generator](https://cgit.kde.org/rust-qt-binding-generator.git/about)
0175 * [Qt](http://doc.qt.io/)
0176 * [Qt Examples and tutorials](http://doc.qt.io/qt-5/qtexamplesandtutorials.html)
0177 * [The QML Book](https://qmlbook.github.io/)