qtrs — Rust-style Qt6 bindings

A type-safe, builder-pattern-driven Qt6 GUI library for Rust. Built on cxx for zero-cost C++ interop, with RAII memory management and signal/callback bridging.

Features

• Builder pattern — chain .title("X").size(800, 600).show()
• RAII cleanup — automatic C++ deletion, parent-child aware (no double-free)
• Signal bridging — Qt signals invoke Rust closures via a global trampoline
• Layout ownership — adding a widget to a layout transfers ownership
• QML / Qt Quick support — load .qml files with Rust backend (feature = "qml")
• .ui file loading — load Qt Designer .ui files at runtime (feature = "ui")
• Zero unsafe in public API — all FFI is encapsulated

Quick Start

use qtrs::prelude::*;

fn main() {
    let app = Application::new();

    let mut window = Widget::new()
        .title("Hello, qtrs!")
        .size(400, 300)
        .build();

    let mut layout = VBoxLayout::with_parent(&window);

    let btn = PushButton::new("Click me")
        .on_clicked(|| println!("clicked!"))
        .build();
    let label = Label::new("Welcome!").build();

    layout.add_widget(Box::new(btn));
    layout.add_widget(Box::new(label));

    window.set_vlayout(layout.layout_ptr());
    window.show();

    app.exec();
}

Widgets

QML Example

use qtrs::prelude::*;

fn main() {
    let app = Application::new();
    let engine = QmlEngine::new();
    engine.load("main.qml");
    app.exec();
}

With main.qml:

import QtQuick 2.15
import QtQuick.Controls 2.15

Window {
    width: 400
    height: 300
    title: "QML with qtrs"
    visible: true

    Button {
        text: "Click me"
        anchors.centerIn: parent
        onClicked: backend.onButtonClicked()
    }

    Connections {
        target: backend
        function onButtonClicked() {
            console.log("Button clicked from Rust!")
        }
    }
}

Run with:

cargo run --features qml

Prerequisites

Qt6 with development headers:

macOS notes

After installing via Homebrew, tell pkg-config where to find Qt:

export PKG_CONFIG_PATH="$(brew --prefix qt@6)/lib/pkgconfig:$PKG_CONFIG_PATH"

Add this to your ~/.zshrc or ~/.bashrc for persistence.

Windows notes

The build script uses pkg-config to locate Qt. When using vcpkg, set the environment variable:

$env:PKG_CONFIG_PATH = "$env:VCPKG_ROOT\installed\x64-windows\lib\pkgconfig"

When using the official Qt installer, set CMAKE_PREFIX_PATH and ensure qmake6 is on your PATH.

$env:CMAKE_PREFIX_PATH = "C:\Qt\6.8.2\msvc2022_64"
$env:PATH += ";C:\Qt\6.8.2\msvc2022_64\bin"

A Microsoft Visual Studio build toolchain (MSVC) is required on Windows.

Installation

Add to your Cargo.toml:

[dependencies]
qtrs = "0.1.0"

Enable QML support:

[dependencies]
qtrs = { version = "0.1.0", features = ["qml"] }

Enable .ui file loading:

[dependencies]
qtrs = { version = "0.1.0", features = ["ui"] }

Enable both:

[dependencies]
qtrs = { version = "0.1.0", features = ["qml", "ui"] }

Memory management

Widgets are deleted automatically on Drop — unless they have a Qt parent (set explicitly or via layout). In that case Qt's parent-child tree handles deletion, preventing double-free.

Widget created without parent  ->  Drop deletes C++ object
Widget created with parent     ->  Drop skips deletion (Qt handles it)
Widget added to layout         ->  Layout takes ownership, Drop skips deletion

Thread safety

Qt GUI classes are not thread-safe. All widget creation, mutation, and the event loop must happen on the main thread.

License

MIT OR Apache-2.0 — see LICENSE-MIT and LICENSE-APACHE.