需要 Qt >= 5.8

Cargo 功能

Cargo 提供了一种启用（或禁用默认）可选 功能 的方法。

日志

默认情况下，Qt 的日志系统未初始化，例如来自 QML 的 console.log 的消息不会去向任何地方。 "日志" 功能使您能够与 log crate（Rust 日志外观）集成。

该功能默认启用。要激活它，请尽早在 main() 中执行以下代码。

fn main() {
    qmetaobject::log::init_qt_to_rust();
    // don't forget to set up env_logger or any other logging backend.
}

chrono_qdatetime

启用 QDate 和 QTime 与 Rust chrono 包的互操作性。

默认情况下禁用此功能。

webengine

启用 QtWebEngine 功能。有关更多详细信息，请参阅示例。

默认情况下禁用此功能。

如果缺少 Qt C++ API 的包装器怎么办？

很可能你想要调用一个未被此 crate 包装的特定 Qt 函数。

在这种情况下，始终可以使用 cpp! 宏直接从你的 Rust 代码中访问 C++。

我们努力提高包装 API 的覆盖率，所以无论你需要什么，但目前在 GitHub 问题上提交功能请求或立即发送 Pull Request 都是受欢迎的。

教程：为 Qt C++ API 添加 Rust 包装器

本节介绍了如何创建自己的 crate 并带有新的 Qt 包装器，并遍历本存储库中提供的图形示例。

首先，设置你的 Cargo.toml 和 build.rs

1. 将 qttypes 添加到依赖项。很可能，你只会坚持最近在 crates.io 上发布的版本。

   [dependencies]
   qttypes = { version = "0.2", features = [ "qtquick" ] }
   

   将您需要的更多 Qt 模块添加到功能数组中。有关支持模块的完整列表，请参阅qttypes crate 文档。
   如果您 绝对需要 最新未发布的变化，请使用此代替 version = "..."

   • path = "../path/to/qmetaobject-rs/qttypes" 或
   • git= "https://github.com/woboq/qmetaobject-rs"

2. 将 cpp 添加到依赖项，将 cpp_build 添加到构建依赖项。您可以在 cpp 文档 页面上找到最新的说明。

   [dependencies]
   cpp = "0.5"
   
   [build-dependencies]
   cpp_build = "0.5"
   

3. 从 qmetaobject/build.rs 复制 build.rs 脚本。它将运行 cpp_build 对您的包，使用由 qttypes/build.rs 提供的环境。

现在，每次构建您的包时，cpp! 宏的内容都将收集到一个大 C++ 文件中，并将其编译成静态库，稍后将其链接到最终二进制文件。您可以在 Cargo 目标目录中找到此 cpp_closures.cpp 文件。理解其内容可能有助于故障排除。

cpp! 宏有两种形式。

• 带有双花括号 {{ 的形式将内容原样追加到 C++ 文件中。用于 #include 头文件，定义 C++ 结构体和类等。

• 另一种是在运行时调用表达式。它通常使用(括号)编写，它需要一个参数列表[ ]，并需要一个unsafe标记（要么在周围块中，要么作为第一个关键字内部）。

宏调用的顺序在每个文件（Rust模块）的基础上得到保留；但文件的处理顺序并不保证与mod声明的顺序相同。所以不要假设可见性——确保在每一个Rust模块的顶部包含所需的一切。

查看cpp的文档以了解更多关于其内部工作方式的信息。

现在我们准备就绪，让我们看看Graph示例的代码。它位于examples/graph目录中。

在添加包装器之前，我们将相关的#include行放入一个双大括号{{宏中。

cpp! {{
    #include <QtQuick/QQuickItem>
}}

如果您需要包含您自己的本地C++头文件，您也可以这样做！查看main qmetaobject crate是如何在需要它的每个Rust模块中包含qmetaobject_rust.hpp头文件的。

接下来，我们声明一个自定义QObject，就像在概述中一样，但这次它派生自QQuickItem。尽管其名称如此，#[derive(QObject)]过程宏可以与多个基类一起工作，只要它被正确包装并实现了QObject特质。

#[derive(Default, QObject)]
struct Graph {
    base: qt_base_class!(trait QQuickItem),

    // ...
}

我们希望调用当前在qmetaobject-rs API中没有公开的QQuickItem::setFlag方法，所以让我们直接调用它。

impl Graph {
    fn appendSample(&mut self, value: f64) {
        // ...
        let obj = self.get_cpp_object();
        cpp!(unsafe [obj as "QQuickItem *"] {
            obj->setFlag(QQuickItem::ItemHasContents);
        });
        // ...
    }
}

或者，我们可以添加一个适当的方法包装器，然后在没有unsafe的情况下调用它。

#[repr(C)]
enum QQuickItemFlag {
    ItemClipsChildrenToShape = 0x01,
    ItemAcceptsInputMethod = 0x02,
    ItemIsFocusScope = 0x04,
    ItemHasContents = 0x08,
    ItemAcceptsDrops = 0x10,
}

impl Graph {
    fn set_flag(&mut self, flag: QQuickItemFlag) {
        let obj = self.get_cpp_object();
        assert!(!obj.is_null());
        cpp!(unsafe [obj as "QQuickItem *", flag as "QQuickItem::Flag"] {
            obj->setFlag(flag);
        });
    }

    fn appendSample(&mut self, value: f64) {
        // ...
        self.set_flag(QQuickItemFlag::ItemHasContents);
        // ...
    }
}

请注意，C++方法接受可选的第二个参数，但由于Rust和FFI粘合剂不支持可选参数，它通常省略（并默认为true）。为了改善这种情况，我们可以在Rust函数中添加第二个必需参数，或者实现两个具有稍微不同名称的“重载”，例如set_flag(Flag, bool) & set_flag_on(Flag)或enable_flag(Flag)等。

如果对象在使用前被保证正确实例化和初始化，则不需要断言非空。这适用于以下情况：

• 直接调用QObject::cpp_construct()并存储在不可移动的内存位置；

• 构造QObjectPinned实例：对固定对象的任何访问或转换为QVariant都确保创建C++对象；

• 将对象实例化为QML组件。在设置任何属性或调用任何信号/槽之前，QML引擎总是正确地将其初始化为默认值。