Qt Bridges - Rust

Introduction

This library enables building modern Qt Quick user interfaces with a Rust backend. It allows you to run QML code and expose Rust data structures directly to the QML Engine, combining a declarative UI with Rust-based business logic.

Qt itself is written in C++, and Qt Bridge builds on CXX to access the required Qt interfaces. As a user, you do not need to write any C++ code. Instead, Rust structs and data can be exposed to QML using attribute macros provided by the library.

If your project requires mixing Rust and C++ code, using Qt Widgets, or accessing Qt modules that only provide a C++ API, consider using CXX-Qt instead.

Internally, the library relies on Qt concepts such as QObjects, properties, signals and slots, and the Model/View architecture. While these are exposed through a Rust-friendly API, familiarity with these Qt concepts will help you get the most out of building UIs with Qt Quick.

Project structure

This repos consists both of Qt Bridge itself under qtbridge directory as well as application examples in apps. For more detaild information, see the Qt Bridge - Rust git repo.

Requirements

To build this project, you’ll need:

• Rust (stable, version >= 1.87) - Visit rustup.rs to install
• Cargo and rustfmt (comes with Rust)
• Qt 6 installation
• C++ toolchain (compiler, linker etc)

Optional:

• clang-format available in build environment

Qt installation

The Qt installation must be present in the system and qmake must be in the system PATH. There are no special requirements to the Qt installation. It can be built from source or downloaded from download.qt.io. To ensure qmake is available, add the Qt bin directory to your PATH, for example:

Example (Linux):

export PATH=<PATH_TO_QT>/bin:$PATH

Example (Windows PowerShell):

$env:Path = "<PATH_TO_QT>\bin;" + $env:Path

Library paths

On Linux it might be also required to add the Qt/lib directory to the LD_LIBRARY_PATH.

Example:

export LD_LIBRARY_PATH=<PATH_TO_QT>/lib:$LD_LIBRARY_PATH

Build using cargo

cargo build

Run using cargo

cargo run --bin <binary_name>

Run tests

cargo test

Environment variables

The folder containing qmake must be in PATH, for example:

On Windows:

set PATH=%PATH%;D:\dev\qt_build\qtbase\bin\

On Linux:

export PATH=/home/john_doe/dev/qt_build/qtbase/bin:$PATH
export LD_LIBRARY_PATH="/home/john_doe/dev/qt_build/lib:$LD_LIBRARY_PATH"

Examples

Example code

Running a QML application is as easy as creating a QApp instance and loading the respective QML files:

use qtbridge::QApp;

fn main() {
    QApp::new()
        .load_qml(include_bytes!("Main.qml"))
        .run();
}

A Rust backend can be added with the #[qobject_impl] and #[qml_element] macros:

use qtbridge::{qobject_impl, qml_element};

#[derive(Default)]
pub struct Backend {
}

#[qobject_impl]
#[qml_element]
impl Backend {
    #[qslot]
    fn say_hello(&self) {
        println!("Hello World!")
    }
}

QML can use the backend as follows:

import QtQuick
import QtQuick.Controls
import hello_world

ApplicationWindow {
    visible: true

    Backend {
        id: backend
    }

    Button {
        anchors.centerIn: parent
        text: "Hello World!"
        onClicked: backend.sayHello()
    }
}

Provided Examples

There are two examples:

• hello_world
• minimal_app

To run those applications, you can use cargo run from one of its directories.

There are also the following aliases defined, which can be executed from the root dir:

Hello world example:

cargo run-hello-world

Minimal app example:

cargo run-minimal-app

API overview

Borrow checker and rules

Qt Bridges aims to respect the borrowing rules of Rust. All QObjects in Rust (implemented with qobject_impl) are designed to be held in Rc<RefCell<_>> structs. The QML engine also hold Rust objects through such references. With this construct, many references can be held and borrowed at runtime. Their QML representation can be copied following the ordinary JavaScript rules. A Rust object is only borrowed when a slot or property defined in Rust is invoked. If QML is unable to borrow the Rust object, it will panic. We are currently investigating alternative ways to handle this situation more gracefully.

It is important that you do not hold a reference to any object that is accessed from QML when QApp::run() is executed. For example, the following code will fail when the QML engine tries to call into a slot defined in Rust:

let qobject1: Rc<RefCell<Backend>> = Backend::default_with_attached_qobject();
let qobject2: Rc<RefCell<Backend>> = Backend::default_with_attached_qobject();

QApp::new()
    .with_initial_properties(& [
        ("rustmodel1", qobject1.borrow().as_qvariant()),
        ("rustmodel2", qobject2.borrow().as_qvariant()),
    ])
    .load_qml(include_bytes!("main.qml"))
    .run();

Isolating the borrowing into separate calls resolves the issue:

let qobject1: Rc<RefCell<Backend>> = Backend::default_with_attached_qobject();
let qobject2: Rc<RefCell<Backend>> = Backend::default_with_attached_qobject();

let initial_properties = [
    ("rustmodel1", qobject1.borrow().as_qvariant()),
    ("rustmodel2", qobject2.borrow().as_qvariant()),
];
QApp::new()
    .with_initial_properties(&initial_properties)
    .load_qml(include_bytes!("main.qml"))
    .run();

This is an evolving API and we aim to make it safer in the future.

QApp

QApp represents a Qt QML application and acts as the entry point for all applications. It allows running QML code and injecting Rust objects into it.

qobject_impl

The #[qobject_impl] macro allows user-defined Rust structs to integrate with Qt and QML by supporting signals, slots, and properties. When a struct is annotated with #[qobject_impl], the macro analyzes the contents of the struct’s impl block and generates the required glue code to connect the struct to Qt’s meta-object system.

Using this macro, a developer can:

• Notify QML about events related to a Rust object (via signals).
• Define slots that can connect to signals or be invoked directly from QML.
• Expose object values to QML as properties, supporting read and optionally write access.

For more details, see the Rust documentation for #[qobject_impl].

qml_element

The #[qml_element] macro makes Rust structures instantiable from QML. It has to be used together with #[qobject_impl]. This lets you to write idomatic QML code.

QVec

QVec provides an API similar to Rust’s standard Vec. In addition, it is recognized by QML as a model and can be used with UI elements such as ListView, Repeater, and other components that require a model.

Currently, QVec can only be exposed to QML through the initial properties of the QML engine.

Resource system

The best way to get artifacts, such as icons, into a QML application is through the Qt Resource System. To inject data into the Qt Resource System, you can use the macro include_bytes_qml! or the function qresource::register_bytes.

Future Plans

• Enable interoperability with CXX-Qt.
• Enable interoperability with other libraries such as tokio.
• Enable QObjects as properties (complex properties).
• Currently we provide QVec as an abstraction for QAbstractItemModel. We aim to provide a trait based API with more flexibility in the future.
• The minimal_app shows an API that resembles CXX-Qt. This will be replaced with an API that looks more native.
• Merge macros qobject_impl and qml_element.
• Remove all C++ Qt classes from the API: Currently, some operations require the usage of QVariant, QModelIndex and there likes. We are working on an API that does not require those.
• Provide Qt dependencies as a crate to enable a streamlined installation through cargo.
• Remove the dependency on Qt binaries like qmake and maybe a C++ tool chain.
• Extend IDE support, in particular for VS Code. Enable the QML language server to understand types generated in Rust.

Terms and Conditions

This is a pre-release implementation of Qt Bridge for Rust. By installing this package, you agree to the terms and conditions stated in https://www.qt.io/terms-conditions. These terms and conditions also apply to the Qt Framework, which is used as a major dependency in this package.

The Qt Bridge for Rust is built using the Rust language and SDK, which is maintained by the Rust Foundation

Qt Bridge for Rust resides on top of Rust and does not modify it in any form. Rust is a trademark of the Rust Foundation. This project is not affiliated with or endorsed by the Rust Foundation.

An application built with Qt Bridge for Rust will include code from other crates. The main dependency is CXX, "Safe interop between Rust and C++", licensed under Apache 2.0 License or MIT license.