CXX-Qt

CXX-Qt is a library designed to automate the generation of code for transferring data between Rust and C++. It enables the creation of common interfaces, such as QObjects, which can be exposed directly into QML.

Key architectural details:

• Internal Dependency: It relies on the cxx crate to facilitate the Rust/C++ boundary.
• Extensibility: For Qt interactions not covered by the built-in code generators, it is recommended to implement the logic directly in C++ and connect it to Rust using cxx code.
• Build System: The build system is based on CMake, but it remains compatible with standalone cxx workflows.

CXX-Qt is a set of Rust crates designed for creating bidirectional Rust ⇄ C++ bindings with Qt. It allows you to:

• Integrate Rust into C++ applications using CMake.
• Build Rust applications with Cargo that use Qt.
• Implement QObject subclasses in Rust, which can then be used from C++, QML, and JavaScript.

The project is split into two main functional parts:

1. cxx-qt-lib: A library of Rust bindings to common QtCore and QtGui classes built using CXX.
2. cxx-qt & cxx-qt-build: A pair of Rust and C++ code generators. They extend CXX with additional attributes to interface with Qt's signals & slots and property system.

The following specific feature implementations are available as standalone examples within the qml_features project:

• Properties and Invokables: How to define properties and invokables for QML.
• Signals: How to define and emit signals from Rust.
• Threading: How to use threaded logic within the CXX-Qt framework.
• Serialization: How to (de)serialize QObjects.
• Qt Types: How to use Qt types such as QVariant in Rust.
• Multiple QObjects: How to define multiple QObjects within a single bridge.
• Nested Objects: How to implement nested objects.

CXX-Qt is a library designed for safe interop between Rust and Qt. Unlike typical one-to-one bindings that attempt to wrap one language's idioms in the other, CXX-Qt uses CXX to bridge between normal Qt code and normal Rust code.

Core Workflow

1. Define: The developer describes a QObject using CXX-Qt macro annotations in Rust.
2. Generate: CXX-Qt uses macros and code generation to create the C++ representation of that object.
3. Bridge: The library uses macro expansion to define a CXX bridge, enabling safe interop and multi-threading between the two languages.

To facilitate this, CXX-Qt provides common Qt types for Rust that can be passed across the bridge, allowing Rust code to express common Qt idioms.

You can nest Rust-Qt objects by using a pointer to their QObject representation. To achieve this:

1. Define the type: Include the nested type in an extern block for your bridge as you would for any other type.
2. Use pointers: Use *mut T in your property definitions, invokable parameters, or signal parameters.

Important: When using *mut T, T must be the C++ CXX type, not the Rust struct itself.

To access mutable invokables or property setters on the nested object, you must convert the *mut T pointer to a Pin<&mut T>.

{{#include ../../../examples/qml_features/rust/src/nested_qobjects.rs:book_macro_code}}

The cxx-qt crate is the primary interface for users. It extends the CXX framework by adding support for the Qt Meta-Object-System. Use it to wrap Qt APIs and create your own Qt-compatible types, including:

• QObjects
• QEnums
• Properties
• Signals and Slots

Note that cxx-qt does not wrap the entire Qt API itself; it provides the tools for you to wrap the APIs you need. For common types, use cxx-qt-lib instead.

The extern "RustQt" block within a #[cxx_qt::bridge] module is used to declare Rust types and signatures that should be made available to Qt and C++. This section allows you to define Qt-specific features like QObjects, properties, methods, and signals. The CXX-Qt code generator uses these blocks to produce a C++ header file with a .cxxqt.h extension corresponding to your Rust file name.

#[cxx_qt::bridge]
mod ffi {
    extern "RustQt" {

    }
}

CXX-Qt provides traits to navigate the class hierarchy:

• Upcast: Allows a type to access its parent class.
• Downcast: Allows a type to access its child class.