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).build()
• 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
• .ui file loading — load Qt Designer .ui files at runtime
• Compile-time embedding — ship .ui and .qrc resources inside the binary (qtrs-build)
• 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(btn);
    layout.add(label);

    window.set_layout(&layout);
    window.show();

    app.exec();
}

You can see demo.rs for details.

Widgets

Windows & Containers

Buttons & Controls

Text & Display

Item Views

Date & Time

Menus & Toolbars

Dialogs

Layouts

Styling & Utilities

System

Prerequisites

Qt6 with development headers:

Remember to set a PATH environment to tell qtrs where the qmake are.

Installation

Add to your Cargo.toml:

[dependencies]
qtrs = "0.5.8"

Compile-time .ui / .qrc embedding

By default .ui files are loaded from disk at runtime, and images / icons / fonts are read from the filesystem. To ship everything inside a single binary, use the companion qtrs-build crate: it runs Qt's own uic and rcc at compile time and links the results into your final executable.

Add it to your build.rs:

# Cargo.toml
[build-dependencies]
qtrs-build = "0.1"

// build.rs
fn main() {
    qtrs_build::Ui::embed().expect("embed ui files");
    qtrs_build::Rcc::embed().expect("embed resource files");
}

Directory conventions:

• Every *.ui file under <package>/ui becomes an embedded resource at :/qrc/<name>.ui — load it with UiLoader::load(":/qrc/<name>.ui", None).
• Every *.qrc file under <package>/resources is embedded verbatim; its resources are available under :/... (e.g. a <file alias="icon.png"> with prefix / resolves as :/icon.png).

Inside the binary the .ui XML and .qrc files are registered as Qt resources by their qInitResources_* initializers before main() runs, so no filesystem access is needed at runtime. See the qtrs-build crate docs for customising the Qt tool lookup (e.g. Qt5 vs Qt6 paths).

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.