Crate qttypes

source ·
Expand description

This crate contains manually generated bindings to Qt basic value types. It is meant to be used by other crates, such as the qmetaobject crate which re-expose them.

The Qt types are basically exposed using the cpp crate. They have manually writen rust idiomatic API which expose the C++ API. These types are the direct equivalent of the Qt types and are exposed on the stack.

In addition, the build script of this crate expose some metadata to downstream crate that also want to use Qt’s C++ API. Build scripts of crates that depends directly from this crate will have the following environment variables set when the build script is run:

  • DEP_QT_VERSION: The Qt version as given by qmake.
  • DEP_QT_INCLUDE_PATH: The include directory to give to the cpp_build crate to locate the Qt headers.
  • DEP_QT_LIBRARY_PATH: The path containing the Qt libraries.
  • DEP_QT_COMPILE_FLAGS: A list of flags separated by ;
  • DEP_QT_FOUND: Set to 1 when qt was found, or 0 if qt was not found and the required feature is not set.
  • DEP_QT_ERROR_MESSAGE: when DEP_QT_FOUND is 0, contains the error that caused the build to fail

Finding Qt

This is the algorithm used to find Qt.

  • You can set the environment variable QT_INCLUDE_PATH and QT_LIBRARY_PATH to be a single directory where the Qt headers and Qt libraries are installed.
  • Otherwise you can specify a QMAKE environment variable with the absolute path of the qmake executable which will be used to query these paths.
  • If none of these environment variable is set, the qmake executable found in $PATH.

Philosophy

The goal of this crate is to expose a idiomatic Qt API for the core value type classes. The API is manually generated to expose required feature in the most rust-like API, while still keeping the similarities with the Qt API itself.

It is not meant to expose all of the Qt API exhaustively, but only the part which is relevant for the usage in other crate. If you see a feature missing, feel free to write a issue or a pull request.

Note that this crate concentrate on the value types, not the widgets or the the QObject. For that, there is the qmetaobject crate.

Usage with the cpp crate

Here is an example that make use of the types exposed by this crate in combination with the cpp crate to call native API:

In Cargo.toml

#...
[dependencies]
qttype = "0.1"
cpp = "0.5"
#...
[build-dependencies]
cpp_build = "0.5"

Note: It is important to depend directly on qttype, it is not enough to rely on the dependency coming transitively from another dependencies, otherwise the DEP_QT_* environment variables won’t be defined.

Then in the build.rs file:

fn main() {
    let mut config = cpp_build::Config::new();
    config.include(std::env::var("DEP_QT_INCLUDE_PATH").unwrap());
    for f in std::env::var("DEP_QT_COMPILE_FLAGS").unwrap().split_terminator(";") {
       config.flag(f);
    }
    config.build("src/main.rs");
}

With that, you can now use the types inside your .rs files:

ⓘ
let byte_array = qttypes::QByteArray::from("Hello World!");
cpp::cpp!([byte_array as "QByteArray"] { qDebug() << byte_array; });

You will find a small but working example in the qmetaobject-rs repository.

Cargo Features

  • required: When this feature is enabled (the default), the build script will panic with an error if Qt is not found. Otherwise, when not enabled, the build will continue, but any use of the classes will panic at runtime.
  • chrono: enable the conversion between QDateTime related types and the types from the chrono crate.

Link against these Qt modules using cargo features:

Cargo featureQt module
qtmultimediaQt Multimedia
qtmultimediawidgetsQt Multimedia Widgets
qtquickQt Quick
qtquickcontrols2Qt Quick Controls
qtsqlQt SQL
qttestQt Test
qtwebengineQt WebEngine

Structs

Enums

Type Aliases