|
| 1 | +<!-- |
| 2 | +SPDX-FileCopyrightText: 2023 Klarälvdalens Datakonsult AB, a KDAB Group company <[email protected]> |
| 3 | +SPDX-FileContributor: Leon Matthes <[email protected]> |
| 4 | +
|
| 5 | +SPDX-License-Identifier: MIT OR Apache-2.0 |
| 6 | +--> |
| 7 | + |
| 8 | +# Defining a custom C++/QML constructor |
| 9 | + |
| 10 | +By default, CXX-Qt will generate a constructor that takes a single `QObject` pointer as optional argument (usually the QObject parent). |
| 11 | + |
| 12 | +It then: |
| 13 | +1. Calls the base class constructor with the optional parent pointer. |
| 14 | +2. uses [Rust's default trait][default-trait] to construct the inner Rust struct. |
| 15 | + |
| 16 | +For most cases this is good enough, however there are a few cases in which this will not be sufficient, for example: |
| 17 | +* the base class constructor expects arguments other than the parent QObject pointer, or a different type than QObject is used for the parent (for example QQuickItem's constructor takes a QQuickItem pointer). |
| 18 | +* the QObject needs to run code after it is initialized (e.g. open a connection to a server, etc.). |
| 19 | +* the Rust struct can't have a `default` implementation as it needs certain arguments for construction. |
| 20 | + |
| 21 | +To facilitate these use-cases CXX-Qt provides the [`Constructor` trait][constructor-trait]. |
| 22 | + |
| 23 | +## Implementing & Declaring a Constructor |
| 24 | +In order for CXX-Qt to generate a custom constructor, the `qobject::T` must implement the [`cxx_qt::Constructor` trait][constructor-trait]. |
| 25 | +Additionally, the constructor must be declared within the [cxx_qt::bridge](./bridge.md). |
| 26 | + |
| 27 | +This declaration uses Rust's `impl ... for` syntax, but with a few special rules: |
| 28 | +* The implementation block must be empty |
| 29 | +* If any of the associated types in the constructor are not `()`, they |
| 30 | + must be listed using `Type=(...)` in the constructor generics. |
| 31 | + |
| 32 | +Example: |
| 33 | +```rust,ignore,noplayground |
| 34 | +#[cxx_qt::bridge] |
| 35 | +mod qobject { |
| 36 | +{{#include ../../../examples/qml_features/rust/src/signals.rs:book_signals_struct}} |
| 37 | +
|
| 38 | +{{#include ../../../examples/qml_features/rust/src/signals.rs:book_constructor_decl}} |
| 39 | +} |
| 40 | +// Don't forget to actually implement the trait **outside** the bridge! |
| 41 | +``` |
| 42 | +[Full example](https://github.com/KDAB/cxx-qt/blob/main/examples/qml_features/rust/src/signals.rs) |
| 43 | + |
| 44 | +## Routing arguments of the Constructor |
| 45 | +A C++ constructor is more complex then a Rust struct initialization. |
| 46 | + |
| 47 | +Like a normal function, it takes a list of arguments. |
| 48 | +However, before the actual code inside the constructor is executed, C++ ensures the following: |
| 49 | +* The base class is constructed |
| 50 | +* All members of the struct are initialized (for CXX-Qt this includes the underlying Rust struct). |
| 51 | + |
| 52 | +Both of these steps may need any of the arguments given to the constructor. |
| 53 | +The code that is actually run *inside* the constructor may also need to access some of the arguments. |
| 54 | + |
| 55 | +`cxx_qt::Constructor` allows controlling how the arguments are passed around in the constructor using the `route_arguments` function. |
| 56 | +For this it uses three associated types as well as one generic type: |
| 57 | +* Constructor generic `Arguments` - argument list that the constructor takes. |
| 58 | +* `type BaseArguments` - argument list that is passed to the base class constructor. |
| 59 | +* `type NewArguments` - argument list used to construct the Rust struct using the `new` function. |
| 60 | +* `type InitializeArguments` - argument list that is passed to the code run within the constructor (the `initialize` function). |
| 61 | + |
| 62 | +These types must all be tuple types and can therefore support an arbitrary list of arguments. |
| 63 | + |
| 64 | +The `route_arguments` function takes the Arguments provided to the constructor and distributes them to the three different types in the above list. |
| 65 | +Doing this in Rust allows calling any base class constructor and controlling movement, copying or other operations on the arguments. |
| 66 | +Every constructor defined using `cxx_qt::Constructor` will execute this function once, before anything else in the Constructor happens and then distributes the resultant values to the appropriate steps of the QObject construction. |
| 67 | + |
| 68 | +As actual construction takes place in C++, all types used must be compatible with CXX as they must be able to pass the FFI barrier. |
| 69 | + |
| 70 | +## Constructing the Rust struct with arguments |
| 71 | +If the construction of the inner Rust struct requires some arguments, the `new` function of the Constructor can be given arguments by using the `NewArguments` associated type. |
| 72 | + |
| 73 | +Example: |
| 74 | +```rust,ignore |
| 75 | +#[cxx_qt::bridge] |
| 76 | +mod qobject { |
| 77 | + // ... |
| 78 | +
|
| 79 | +{{#include ../../../examples/qml_features/rust/src/properties.rs:book_constructor_new_decl}} |
| 80 | +} |
| 81 | +
|
| 82 | +{{#include ../../../examples/qml_features/rust/src/properties.rs:book_constructor_new_impl}} |
| 83 | +``` |
| 84 | + |
| 85 | +## Initializing the QObject |
| 86 | +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). |
| 87 | + |
| 88 | +The `initialize` function can be used to run code inside a constructor. |
| 89 | +It is given a pinned mutable self reference to the QObject and the list of `InitializeArguments`. |
| 90 | + |
| 91 | +### Using the `Initialize` trait |
| 92 | +As QML uses the default constructor, for most QML types only the `initialize` part of the constructor is of interest, as everything else is defaulted. |
| 93 | +To reduce the boilerplate of this use-case, CXX-Qt provides the [`Initialize`][initialize-trait] trait. |
| 94 | + |
| 95 | +If a QObject implements the `Initialize` trait, and the inner Rust struct is [Default][default-trait]-constructible it will automatically implement `cxx_qt::Constructor<()>`. |
| 96 | + |
| 97 | +Example: |
| 98 | +```rust,ignore |
| 99 | +{{#include ../../../examples/qml_features/rust/src/signals.rs:book_initialize_impl}} |
| 100 | + // ... |
| 101 | + } |
| 102 | +} |
| 103 | +``` |
| 104 | +[Full example](https://github.com/KDAB/cxx-qt/blob/main/examples/qml_features/rust/src/signals.rs) |
| 105 | + |
| 106 | +Then just remember to declare the `cxx_qt::Constructor<()>` inside the `cxx_qt::bridge`. |
| 107 | +```rust,ignore |
| 108 | +#[cxx_qt::bridge] |
| 109 | +mod qobject { |
| 110 | +{{#include ../../../examples/qml_features/rust/src/signals.rs:book_signals_struct}} |
| 111 | +
|
| 112 | +{{#include ../../../examples/qml_features/rust/src/signals.rs:book_initialize_decl}} |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +[constructor-trait]: https://docs.rs/cxx-qt/latest/cxx_qt/trait.Constructor.html |
| 117 | +[initialize-trait]: https://docs.rs/cxx-qt/latest/cxx_qt/trait.Initialize.html |
| 118 | +[default-trait]: https://doc.rust-lang.org/std/default/trait.Default.html |
0 commit comments