From 53f64f76f430440dd1bd2e5d5b0dbdab6801b8c8 Mon Sep 17 00:00:00 2001 From: Ulf Hermann Date: Thu, 16 Feb 2023 09:39:24 +0100 Subject: Doc: How to combine custom singletons and qt_generate_foreign_qml_types First, make it more explicit that the QML engine really wants to own the singletons. Then explain how to combine qt_generate_foreign_qml_types with custom types you need to manually manage. Fixes: QTBUG-111169 Change-Id: I9e070c3482014691382c9c1279c918913bdf0307 Reviewed-by: Sze Howe Koh (cherry picked from commit 4f33440a6ce19fcd2a98a77dced76f874d8625c3) Reviewed-by: Qt Cherry-pick Bot --- src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc | 9 +++++++++ src/qml/doc/src/qmlfunctions.qdoc | 4 +++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc b/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc index c69b618df4..9bd412d36d 100644 --- a/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc +++ b/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc @@ -67,4 +67,13 @@ the \c QML_ELEMENT macro). The effect is equivalent to using \c QML_FOREIGN with custom structs in the QML library to expose the types. + +\note In order to implement custom behavior, such as exposing an existing +singleton instance with its own life cycle to QML, you should add custom types +to your QML library (mylib_declarative in the above example). In turn, you +should omit the \l QML_ELEMENT and similar macros from the original C++ classes +so that qt_generate_foreign_qml_types() does not generate more QML integration +structs for them. The QML macros, as well as any singleton factory functions, +can be added to the structs that contain the \l QML_FOREIGN. + */ diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index 7995f03674..005bd0be94 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -173,7 +173,9 @@ \c{T *create(QQmlEngine *, QJSEngine *)} when the type is first accessed. If both do exist and are accessible, the default constructor is preferred. If there is no default constructor and no factory function the singleton is - inaccessible. + inaccessible. The QML engine generally assumes ownership of the singleton and + will delete it when the engine itself is destroyed. You can prevent this by + calling QJSEngine::setObjectOwnership() on the singleton. In order to declare a default-constructible class as singleton, all you have to do is add \l QML_SINGLETON: -- cgit v1.2.3