Trait cxx_qt::Constructor

source · 
pub trait Constructor<Arguments>: CxxQtType {
    type NewArguments;
    type BaseArguments;
    type InitializeArguments;

    // Required methods
    fn route_arguments(
        arguments: Arguments
    ) -> (Self::NewArguments, Self::BaseArguments, Self::InitializeArguments);
    fn new(arguments: Self::NewArguments) -> <Self as CxxQtType>::Rust;

    // Provided method
    fn initialize(self: Pin<&mut Self>, arguments: Self::InitializeArguments) { ... }
}
Expand description

This trait can be implemented on any CxxQtType to define a custom constructor in C++ for the QObject.

The Arguments must be a tuple of CXX types that will be the arguments to the constructor in C++.

If this trait is implemented for a given CxxQtType, it must also be declared inside the cxx_qt::bridge macro. See the example below.

Note that declaring an implementation of this trait will stop CXX-Qt from generating a default constructor. Therefore an implementation of Default is no longer required for the Rust type.

§Minimal Example

#[cxx_qt::bridge]
mod qobject {
    extern "RustQt" {
        #[qobject]
        type MyStruct = super::MyStructRust;
    }

    // Declare that we want to use a custom constructor
    // Note that the arguments must be a tuple of CXX types.
    // Any associated types that aren't included here are assumed to be `()`.
    impl cxx_qt::Constructor<(i32, String), NewArguments=(i32, String)> for MyStruct {}
}

// Struct without `Default` implementation
pub struct MyStructRust {
    pub integer: i32,
    pub string: String
}

impl cxx_qt::Constructor<(i32, String)> for qobject::MyStruct {
    type BaseArguments = (); // Will be passed to the base class constructor
    type InitializeArguments = (); // Will be passed to the "initialize" function
    type NewArguments = (i32, String); // Will be passed to the "new" function

    fn route_arguments(args: (i32, String)) -> (
        Self::NewArguments,
        Self::BaseArguments,
        Self::InitializeArguments
    ) {
        (args, (), ())
    }

    fn new((integer, string): (i32, String)) -> MyStructRust {
        MyStructRust {
            integer,
            string
        }
    }
}

§Pseudo Code for generated C++ Constructor

You can imagine this trait as creating a constructor roughly like this:

class MyCxxQtType : public QObject {
    public:
        MyCxxQtType(Arguments... args)
            : QObject(Constructor::route_arguments(args).BaseArguments)
            , m_rust(Constructor::new(Constructor::route_arguments(args).NewArguments))
        {
            Constructor::initialize(*this, Constructor::route_arguments(args).InitializeArguments);
        }
}

Note that in reality, route_arguments will only be called once and all arguments will be moved, never copied.

§Initializing the QObject

In addition to running code before constructing the inner Rust struct, it may be useful to run code from the context of the QObject itself (i.e. inside the Constructor implementation).

The initialize function can be used to run code inside a constructor. It is given a pinned mutable self reference to the QObject and the list of InitializeArguments.

§Using the Initialize trait

The QML engine creates QML elements using their default constructor, so for most QML types only the initialize part of the constructor is of interest. To reduce the boilerplate of this use-case, CXX-Qt provides the Initialize trait.

If a QObject implements the Initialize trait, and the inner Rust struct is Default-constructible it will automatically implement cxx_qt::Constructor<()>.

Required Associated Types§

source

type NewArguments

The arguments that are passed to the new() function to construct the inner Rust struct. This must be a tuple of CXX compatible types.

This way QObjects can be constructed that need additional arguments for constructing the inner Rust type.

source

type BaseArguments

The arguments that should be passed to the constructor of the base class. This must be a tuple of CXX compatible types.

source

type InitializeArguments

The arguments that should be used to initialize the QObject in the initialize() function. This must be a tuple of CXX compatible types.

Required Methods§

source

fn route_arguments( arguments: Arguments ) -> (Self::NewArguments, Self::BaseArguments, Self::InitializeArguments)

This function is called by CXX-Qt to route the arguments to the correct places.

Using this function, you can split up the arguments required by the QObject constructor without additional copies.

source

fn new(arguments: Self::NewArguments) -> <Self as CxxQtType>::Rust

This function is called to construct the inner Rust struct of the CXX-Qt QObject. You can use this to construct Rust structs that do not provide a Default implementation.

Provided Methods§

source

fn initialize(self: Pin<&mut Self>, arguments: Self::InitializeArguments)

This function is called to initialize the QObject. After the members of the QObject is initialized, this function is called. This is equivalent to the body of the constructor in C++.

§Default

By default, this function does nothing

Object Safety§

This trait is not object safe.

Implementors§