Rust Qt Binding Generator lets you combine Rust code with a Qt1 graphical application. A previous blog shows how to make a simple clock. It’s a good idea to read that post before reading this more advanced post, because in this post we are getting serious.
This blog post shows how to write a to-do application. The data model is a list of to-do items. The source code for this example is available in the folder examples/todos in the Rust Qt Binding Generator repository.
Here is a screenshot of the finished application. The to-do application shows the steps to implement the to-do application. This application was the subject of a presentation on Rust Qt Binding Generator.
Model/View programming
Model/View programming is a big thing in Qt. It’s everywhere. It’s not trivial, but powerful. Please bear with me for a bit as we’ll talk about how this works. Rust Qt Binding Generator does most of the hard work for you, but it does not hurt to know a bit of how it does this.
One C++ class is the basis for all the model/view programming in Qt: QAbstractItemModel. As the name says, QAbstractItemModel is an abstract model for items. If you want to have a list, a tree or a table in your program, you’ll be deriving a class from QAbstractItemModel.
When your data is in a class derived from QAbstractItemModel, you can put that model in one or more simultaneous widgets. In Qt, you put a list in QListView, a tree in a QTreeView, and a table in a QTableView. QComboBox and QComplete also use a model for their data.
In QML, models are even more important. QML has a ListView, TreeView, and TableView as well, but also GridView, Repeater, MapItemView and more.
Any non-trivial application will have Qt models. So we’ll show you how to make a list model with Rust Qt Binding Generator.
A to-do application
The to-do application in this post implements the specification of the TodoMVC website. ‘MVC’ stands for Model-View-Controller. In this post, Rust supplies the Model. The View and Controller are written in QML. The to-do list above contains seven items. The three items that start with ‘check’ are there for the curious that would like to see what code for the communication between Rust and C++ looks like.
The first step in the to-do is ‘Write bindings.json’. bindings.json is the file where you describe the model of your application. The data in the to-do application is simple. It is a list of to-do items. So we define an object of type List. Each list item has two properties: a boolean completed and a QString description. You can see these fields in the JSON snippet below.
Both fields, completed and description are writable so the to-do can be toggled and the description text can be changed.
...
"objects": {
"Todos": {
"type": "List",
...
"itemProperties": {
"completed": {
"type": "bool",
"write": true
},
"description": {
"type": "QString",
"write": true
}
},
"functions": {
"add": {
"return": "void",
"mut": true,
"arguments": [{
"name": "description",
"type": "QString"
}]
},
...The field functions adds a function called add. It describes a Rust function for adding a to-do item. This function will be visible the the QML code.
Rust Qt Binding Generator creates three files from bindings.json with this command:
The created files are Bindings.h, Bindings.cpp, and interface.rs.
The Rust side
The generated file interface.rs contains a Rust trait that is derived from the data model. Here is the relevant part of the Rust trait:
pub trait TodosTrait {
fn new(emit: TodosEmitter, model: TodosList) -> Self;
fn emit(&self) -> &TodosEmitter;
fn row_count(&self) -> usize;
fn insert_rows(&mut self, _row: usize, _count: usize) -> bool { false }
fn remove_rows(&mut self, _row: usize, _count: usize) -> bool { false }
fn completed(&self, index: usize) -> bool;
fn set_completed(&mut self, index: usize, bool) -> bool;
fn description(&self, index: usize) -> &str;
fn set_description(&mut self, index: usize, String) -> bool;
}It is up to you to implement this trait in your code in a module implementation in a file called implementation.rs. (You can set a different name in bindings.json.) If implementation.rs does not yet exist, an initial version will be generated for you.
There’s quite a few functions that require implementing. Let’s go through them one by one. But first let’s write two structs that will hold our data.
#[derive(Default, Clone)]
struct TodosItem {
completed: bool,
description: String,
}
pub struct Todos {
emit: TodosEmitter,
model: TodosList,
list: Vec<TodosItem>,
}
impl TodosTrait for Todos {
...
}The struct Todos contains our to-do items in a Vec<TodosItem>. In addition, there are two members: a TodosEmitter called emit and a TodosList called model. These are used to communicate with the user interface. Whenever there is a change in our model, we call a function in either the TodosEmitter or the TodosList. In the previous blog post we already saw an emitter. It was used to emit a signal whenever the current time, an object property, changed. The model is new. It is present in list models and tree models. It is used to signal changes in the items in list and tree models.
Let’s get to the implementation of our trait.
new
new is the factory function that is called when the user interface creates a new instance of TodosTrait.
fn new(emit: TodosEmitter, model: TodosList) -> Todos {
Todos {
emit: emit,
model: model,
list: vec![TodosItem::default(); 0],
}
}emit
For some functions in the binding, such as for the destruction of the model, signals must be emitted. The function emit gives the binding code access to the emitter. The implementation is straight forward.
row_count
Things are getting a bit more interesting. The user interface needs to know how many items are in the list. row_count reports this number. We simply return the length of the Vec<TodosItem>
insert_rows and remove_rows
A to-do list is not very useful if you cannot add items. The trait functions insert_rows and remove_rows are called when the user wants to add or remove items. These functions receive two arguments. row is the index of the first row that is being added or removed. count is the number of rows that are being added.
If row or count do not make sense and no row can be added, false is returned.
fn insert_rows(&mut self, row: usize, count: usize) -> bool {
if count == 0 || row > self.list.len() {
return false;
}
self.model.begin_insert_rows(row, row + count - 1);
for i in 0..count {
self.list.insert(row + i, TodosItem::default());
}
self.model.end_insert_rows();
true
}
fn remove_rows(&mut self, row: usize, count: usize) -> bool {
if count == 0 || row + count > self.list.len() {
return false;
}
self.model.begin_remove_rows(row, row + count - 1);
self.list.drain(row..row + count);
self.model.end_remove_rows();
true
}This is where we get to see model in action. It is used before and after the model changes. Before rows are added begin_insert_rows must be called. end_insert_rows must be called immediately afterwards. Now all parts of the user interface that show our to-do list will be notified of the change.
insert_rows and remove_rows will be called from the GUI thread. Adding rows to the model can only be done in the GUI thread. If another thread would receive modifications to the model, it would have to buffer them and send a signal to the GUI thread to process the changes. There is an example of this in the Rust Qt Binding Generator demo application. The Rust type system ensures that these signals are only sent from the GUI thread.
completed, set_completed, description, and set_description
Our data model is a list of items with two properties each: completed and description. These correspond to two accessor functions in the trait. There are also two setters, set_completed and set_description. All four functions are called with the index of the item.
fn completed(&self, index: usize) -> bool {
self.list[index].completed
}
fn set_completed(&mut self, index: usize, v: bool) -> bool {
self.list[index].completed = v;
true
}
fn description(&self, index: usize) -> &str {
&self.list[index].description
}
fn set_description(&mut self, index: usize, v: String) -> bool {
self.list[index].description = v;
true
}For these functions, you do not need to inform the user interface. That is taken care of by the generated binding code. When items are modified outside of these functions, model.data_changed should be called to notify the user interface of the change.
add
Besides the standard model functions, we have to implement one more function. The functions field in bindings.json described a function called add. This function adds a new to-do item. The only parameter is a string. A newly inserted to-do item has not yet been completed, so completed is always false.
fn add(&mut self, description: String) {
let end = self.list.len();
self.model.begin_insert_rows(end, end);
self.list.insert(end, TodosItem { completed: false, description });
self.model.end_insert_rows();
}This function also uses model to signal to the GUI that the model has changed.
The QML side
The QML part of the to-do application consists of one QML file. This file is about 200 lines. Below are some cut down snippets from that file.
At the top, the Rust data model should be imported.
import RustCode 1.0;The data model, Todos is instantiated. It is given an id, todoModel and populated with some to-do items.
Todos {
id: todoModel
Component.onCompleted: {
add("write bindings.json")
add("run rust_qt_binding_generator")
add("check bindings.h")
add("check bindings.cpp")
add("check interface.rs")
add("write implementation.rs")
add("write main.qml")
}
}The application contains a text field that creates a new to-do item when a line of text is entered.
TextField {
id: input
Layout.fillWidth: true
placeholderText: qsTr("What needs to be done?")
onAccepted: {
const todo = text.trim()
if (todo) {
todoModel.add(todo)
}
input.clear()
}
}Each visible item in the to-do list is shown by a Component. These components are cleverly reused for newly visible items when scrolling. Each component contains a CheckBox and Label. The status of the CheckBox is retrieved from the model with checked: completed. The text in the Label is also retrieved from the model: text: description. When the CheckBox is toggled, the Rust model is changed: onToggled: todoModel.setCompleted(index, checked).
Component {
id: todoDelegate
RowLayout {
width: parent.width
CheckBox {
checked: completed
onToggled: todoModel.setCompleted(index, checked)
}
Label {
id: label
text: description
anchors.fill: parent
verticalAlignment: Text.AlignVCenter
font.strikeout: completed
font.pixelSize: 20
}
}
}To show all to-do items, a ListView is added. It is connected to the model with model: todoModel and to the delegate with delegate: todoDelegate.
Flickable {
anchors.fill: parent
ListView {
anchors.fill: parent
model: todoModel
delegate: todoDelegate
}
}
Concluding
The full application has some more features, but no new concepts. You’re invited to run and study the code. When you master writing models, you can write sophisticated applications in Qt.
A nice example is notquick, a viewer for mail boxes that uses Rust Qt Binding Generator. For more examples with trees and threading, check out the folder demo.
1: pronounced as kjuːt
Comments
Post a comment