From ce545a5bf291eec7c623e6f691842eca18b09ddc Mon Sep 17 00:00:00 2001
From: Fabian Kosmale <fabian.kosmale@qt.io>
Date: Fri, 14 Jun 2019 16:54:14 +0200
Subject: Introduce qmlRegisterSingletonInstance

This method is intended as a replacement for common setContextProperty use cases,
where the user is only using one single engine and has already created
the object.

Task-number: QTBUG-73064
Change-Id: Ib9ec023a0ad679aa22e90ebcb4a0c07622459c61
Reviewed-by: Simon Hausmann <simon.hausmann@qt.io>
---
 src/qml/doc/src/qmlfunctions.qdoc | 97 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 95 insertions(+), 2 deletions(-)

(limited to 'src/qml/doc')

diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc
index ab54b5fd1d..9c106558fd 100644
--- a/src/qml/doc/src/qmlfunctions.qdoc
+++ b/src/qml/doc/src/qmlfunctions.qdoc
@@ -487,8 +487,7 @@
 
    A QObject singleton type may be referenced via the type name with which it was registered, and this
    typename may be used as the target in a \l Connections type or otherwise used as any other type id would.
-   One exception to this is that a QObject singleton type property may not be aliased (because the
-   singleton type name does not identify an object within the same component as any other item).
+   One exception to this is that a QObject singleton type property may not be aliased.
 
    \b{NOTE:} A QObject singleton type instance returned from a singleton type provider is owned by
    the QML engine unless the object has explicit QQmlEngine::CppOwnership flag set.
@@ -618,6 +617,100 @@
    files using the singleton.
 */
 
+/*!
+   \fn int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int
+   versionMinor, const char *typeName, QObject* cppObject)
+   \relates QQmlEngine
+   \since 5.14
+
+   This function is used to register a singleton object \a cppObject, with a
+   particular \a uri and \a typeName. Its version is a combination of \a
+   versionMajor and \a versionMinor.
+
+   Installing a singleton type into a URI allows you to provide arbitrary
+   functionality (methods and properties) to QML code without requiring
+   individual instances of the type to be instantiated by the client.
+
+   Use this function to register an object of the given type T as a singleton
+   type.
+
+   A QObject singleton type may be referenced via the type name with which it
+   was registered; in turn this type name may be used as the target in a \l
+   Connections type, or like any other type ID. However, there's one
+   exception: a QObject singleton type property can't be aliased because the
+   singleton type name does not identify an object within the same component
+   as any other item.
+
+   \note \a cppObject must outlive the QML engine in which it is used.
+   Moreover, \cppObject must have the same thread affinity as the engine. If
+   you want separate singleton instances for multiple engines, you need to use
+   \l {qmlRegisterSingletonType}.  See \l{Threads and QObjects} for more
+   information about thread safety.
+
+    Usage:
+    \code
+    // First, define your QObject which provides the functionality.
+    class SingletonTypeExample : public QObject
+    {
+        Q_OBJECT
+        Q_PROPERTY(int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)
+
+    public:
+        explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {}
+
+        Q_INVOKABLE int doSomething()
+        {
+            setSomeProperty(5);
+            return m_someProperty;
+        }
+
+        int someProperty() const { return m_someProperty; }
+        void setSomeProperty(int val) {
+            if (m_someProperty != val) {
+                m_someProperty = val;
+                emit somePropertyChanged(val);
+            }
+        }
+
+    signals:
+        void somePropertyChanged(int newValue);
+
+    private:
+        int m_someProperty = 0;
+    };
+    \endcode
+
+    \code
+    // Second, create an instance of the object
+
+    // allocate example before the engine to ensure that it outlives it
+    QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample);
+    QQmlEngine engine;
+
+    // Third, register the singleton type provider with QML by calling this
+    // function in an initialization function.
+    qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get());
+    \endcode
+
+
+    In order to use the registered singleton type in QML, you must import the
+    URI with the corresponding version.
+    \qml
+    import QtQuick 2.0
+    import Qt.example.qobjectSingleton 1.0
+    Item {
+        id: root
+        property int someValue: MyApi.someProperty
+
+        Component.onCompleted: {
+            console.log(MyApi.doSomething())
+        }
+    }
+    \endqml
+
+   \sa qmlRegisterSingletonType
+ */
+
 /*!
   \fn int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName);
   \relates QQmlEngine
-- 
cgit v1.2.3