book: document implemeting custom types

Author: ahayzen-kdab

book/src/concepts/types.md

@@ -52,6 +52,20 @@ If they are opaque, references or pointers must be used.
 
 For examples of how to wrap Qt objects, explore the [`cxx-qt-lib` source code](https://github.com/KDAB/cxx-qt/tree/main/crates/cxx-qt-lib).
 
+### Using a Custom Type with Containers or QVariant
+
+To use a custom type with containers find the trait that the container uses, eg for `QSet<T>` there is a `QSetElement` trait and for `QHash<K, V>` there is a `QHashPair` trait.
+
+Implement the trait for your custom type and then you can use the containers as described above.
+
+To use a custom type with `QVariant` implement the `QVariantValue` trait for your custom type, as seen below, then it can be used as normal.
+
+```rust,ignore
+{{#include ../../../examples/qml_features/rust/types.rs:book_qvariantvalue_impl}}
+```
+
+A full example of implementing a custom struct with `QVariant` is shown in the [qml_features types example](https://github.com/KDAB/cxx-qt/blob/main/examples/qml_features/rust/src/types.rs).
+
 ## Opaque Type Conversions
 
 If your type can't be marked as trivial for CXX, but the Qt API needs to take the type by value (eg `T` rather than `const T&` or `::std::unique_ptr<T>`),

examples/qml_features/CMakeLists.txt

@@ -51,6 +51,8 @@ target_link_libraries(${CRATE} INTERFACE
 )
 
 add_executable(${APP_NAME}
+    cpp/custom_object.h
+    cpp/custom_object.cpp
     cpp/main.cpp
     cpp/qabstractlistmodelcxx.h
     qml/qml.qrc
@@ -80,7 +82,12 @@ copy_qml_test(signals)
 copy_qml_test(threading)
 copy_qml_test(types)
 
-add_executable(${APP_NAME}_test "tests/main.cpp")
+add_executable(${APP_NAME}_test
+    cpp/custom_object.h
+    cpp/custom_object.cpp
+    cpp/qabstractlistmodelcxx.h
+    tests/main.cpp
+)
 target_include_directories(${APP_NAME}_test PRIVATE cpp)
 target_link_libraries(${APP_NAME}_test PRIVATE
     ${CRATE}

examples/qml_features/cpp/custom_object.cpp

@@ -0,0 +1,13 @@
+// clang-format off
+// SPDX-FileCopyrightText: 2022 Klarälvdalens Datakonsult AB, a KDAB Group company <[email protected]>
+// clang-format on
+// SPDX-FileContributor: Andrew Hayzen <[email protected]>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+#include "custom_object.h"
+
+bool
+qvariantCanConvertCustomStruct(const QVariant& variant)
+{
+  return variant.canConvert<CustomStruct>();
+}

examples/qml_features/cpp/custom_object.h

@@ -0,0 +1,37 @@
+// clang-format off
+// SPDX-FileCopyrightText: 2022 Klarälvdalens Datakonsult AB, a KDAB Group company <[email protected]>
+// clang-format on
+// SPDX-FileContributor: Andrew Hayzen <[email protected]>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+#pragma once
+
+#include <QObject>
+#include <QVariant>
+
+struct CustomStruct
+{
+  int value;
+};
+Q_DECLARE_METATYPE(CustomStruct);
+
+bool
+qvariantCanConvertCustomStruct(const QVariant& variant);
+
+class CustomObject : public QObject
+{
+  Q_OBJECT
+
+  Q_PROPERTY(int value MEMBER m_value)
+public:
+  CustomObject(QObject* parent = nullptr)
+    : QObject(parent)
+    , m_value(0)
+  {
+  }
+
+  Q_INVOKABLE CustomStruct asStruct() const { return CustomStruct{ m_value }; }
+
+private:
+  int m_value;
+};

examples/qml_features/cpp/main.cpp

@@ -18,6 +18,8 @@
 #include "cxx-qt-gen/threading_website.cxxqt.h"
 #include "cxx-qt-gen/types.cxxqt.h"
 
+#include "custom_object.h"
+
 int
 main(int argc, char* argv[])
 {
@@ -36,6 +38,8 @@ main(int argc, char* argv[])
     },
     Qt::QueuedConnection);
 
+  qRegisterMetaType<CustomStruct>("CustomStruct");
+  qmlRegisterType<CustomObject>("com.kdab.cxx_qt.demo", 1, 0, "CustomObject");
   qmlRegisterType<RustContainers>(
     "com.kdab.cxx_qt.demo", 1, 0, "RustContainers");
   qmlRegisterType<CustomBaseClass>(

examples/qml_features/qml/pages/TypesPage.qml

@@ -26,6 +26,9 @@ Page {
                 property var booleanVariant: types.boolean
                 property var pointVariant: types.point
                 property url url: types.url
+                property CustomObject customObject: CustomObject {
+                    value: 0
+                }
                 readonly property var urlVariant: url
 
                 onClicked: {
@@ -40,12 +43,15 @@ Page {
                             case 2:
                                 url = types.url == "https://kdab.com" ? "https://github.com/kdab/cxx-qt" : "https://kdab.com"
                                 return urlVariant;
+                            case 3:
+                                customObject.value += 1;
+                                return customObject.asStruct();
                             default:
                                 return null;
                         }
                     })());
 
-                    counter = (counter + 1) % 3;
+                    counter = (counter + 1) % 4;
                 }
             }
 
@@ -84,5 +90,12 @@ Page {
             text: qsTr("QUrl: %1").arg(types.url)
             wrapMode: Text.Wrap
         }
+
+        Label {
+            Layout.fillWidth: true
+            horizontalAlignment: Text.AlignHCenter
+            text: qsTr("CustomValue: %1").arg(types.customValue)
+            wrapMode: Text.Wrap
+        }
     }
 }

examples/qml_features/rust/src/types.rs

@@ -4,6 +4,32 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
 // ANCHOR: book_macro_code
+#[repr(C)]
+pub struct CustomStruct {
+    value: i32,
+}
+
+unsafe impl cxx::ExternType for CustomStruct {
+    type Id = cxx::type_id!("CustomStruct");
+    type Kind = cxx::kind::Trivial;
+}
+
+// ANCHOR: book_qvariantvalue_impl
+impl cxx_qt_lib::QVariantValue for ffi::CustomStruct {
+    fn can_convert(variant: &cxx_qt_lib::QVariant) -> bool {
+        ffi::qvariant_can_convert_custom_type(variant)
+    }
+
+    fn construct(value: &Self) -> cxx_qt_lib::QVariant {
+        ffi::qvariant_construct_custom_type(value)
+    }
+
+    fn value(variant: &cxx_qt_lib::QVariant) -> Self {
+        ffi::qvariant_value_custom_type(variant)
+    }
+}
+// ANCHOR_END: book_qvariantvalue_impl
+
 // ANCHOR: book_cxx_file_stem
 #[cxx_qt::bridge(cxx_file_stem = "types")]
 mod ffi {
@@ -17,7 +43,25 @@ mod ffi {
         type QVariant = cxx_qt_lib::QVariant;
     }
 
-    // TODO: should we show how to do custom types?
+    unsafe extern "C++" {
+        include!("custom_object.h");
+        type CustomStruct = super::CustomStruct;
+
+        #[rust_name = "qvariant_can_convert_custom_type"]
+        fn qvariantCanConvertCustomStruct(variant: &QVariant) -> bool;
+    }
+
+    // We can reuse the templates from cxx-qt-lib for the construct and value
+    #[namespace = "rust::cxxqtlib1::qvariant"]
+    unsafe extern "C++" {
+        include!("cxx-qt-lib/qvariant.h");
+
+        #[rust_name = "qvariant_construct_custom_type"]
+        fn qvariantConstruct(value: &CustomStruct) -> QVariant;
+        #[rust_name = "qvariant_value_custom_type"]
+        fn qvariantValue(variant: &QVariant) -> CustomStruct;
+    }
+
     #[cxx_qt::qobject]
     pub struct Types {
         #[qproperty]
@@ -26,6 +70,8 @@ mod ffi {
         point: QPointF,
         #[qproperty]
         url: QUrl,
+        #[qproperty]
+        custom_value: i32,
     }
 
     impl Default for Types {
@@ -34,6 +80,7 @@ mod ffi {
                 boolean: false,
                 point: QPointF::new(1.0, 2.0),
                 url: QUrl::from("https://kdab.com"),
+                custom_value: 0,
             }
         }
     }
@@ -47,6 +94,8 @@ mod ffi {
                 self.set_point(point);
             } else if let Some(url) = variant.try_value::<QUrl>() {
                 self.set_url(url);
+            } else if let Some(custom) = variant.try_value::<CustomStruct>() {
+                self.set_custom_value(custom.value);
             } else {
                 println!("Unknown QVariant type to load from");
             }

examples/qml_features/tests/main.cpp

@@ -18,13 +18,18 @@
 #include "cxx-qt-gen/threading_website.cxxqt.h"
 #include "cxx-qt-gen/types.cxxqt.h"
 
+#include "custom_object.h"
+
 class Setup : public QObject
 {
   Q_OBJECT
 
 public:
   Setup()
   {
+    qRegisterMetaType<CustomStruct>("CustomStruct");
+    qmlRegisterType<CustomObject>("com.kdab.cxx_qt.demo", 1, 0, "CustomObject");
+
     qmlRegisterType<CustomBaseClass>(
       "com.kdab.cxx_qt.demo", 1, 0, "CustomBaseClass");
     qmlRegisterType<FirstObject>("com.kdab.cxx_qt.demo", 1, 0, "FirstObject");

examples/qml_features/tests/tst_types.qml

@@ -22,6 +22,14 @@ TestCase {
         }
     }
 
+    Component {
+        id: componentCustomObject
+
+        CustomObject {
+
+        }
+    }
+
     Component {
         id: componentSpy
 
@@ -86,4 +94,20 @@ TestCase {
         compare(obj.boolean, true);
         compare(spy.count, 1);
     }
+
+    function test_variant_custom_type() {
+        const obj = createTemporaryObject(componentTypes, null, {});
+        const customObject = createTemporaryObject(componentCustomObject, null, {
+            value: 1,
+        });
+        const customValueSpy = createTemporaryObject(componentSpy, null, {
+            signalName: "customValueChanged",
+            target: obj,
+        });
+
+        compare(obj.customValue, 0);
+        obj.loadFromVariant(customObject.asStruct());
+        compare(obj.customValue, 1);
+        compare(customValueSpy.count, 1);
+    }
 }