Doc: Describe QML_FOREIGN in "Defining QML Types from C++"

Fixes: QTBUG-83852
Change-Id: I8dd5fa6887ad607fe91ac658efa51152c46df36e
Reviewed-by: Maximilian Goldstein <max.goldstein@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 26 insertions, 0 deletions

diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc
index d5762f7d26..2fdd6edded 100644
--- a/src/qml/doc/src/cppintegration/definetypes.qdoc
+++ b/src/qml/doc/src/cppintegration/definetypes.qdoc
@@ -331,6 +331,32 @@ accessed, the corresponding property on the extension object is used instead.
 The \l{Extending QML - Extension Objects Example}{Extension Objects Example}
 demonstrates a usage of extension objects.
 
+\section2 Registering Foreign Types
+
+There may be C++ types that cannot be modified to hold the above mentioned
+macros. Those may be types from 3rdparty libraries, or types that need to
+fulfill some contract that contradicts the presence of those macros. You can
+still expose those types to QML, though, using the QML_FOREIGN macro. In order
+to do this, create a separate struct that consists entirely of the registration
+macros, like this:
+
+\code
+// Contains class Immutable3rdParty
+#include <3rdpartyheader.h>
+
+struct Foreign
+{
+    Q_GADGET
+    QML_FOREIGN(Immutable3rdParty)
+    QML_NAMED_ELEMENT(Accessible3rdParty)
+    QML_ADDED_IN_VERSION(2, 4)
+    // QML_EXTENDED, QML_SINGLETON ...
+};
+\endcode
+
+From this code, you get a QML type with the methods and properties of
+Immutable3rdParty, and the QML traits (e.g.: singleton, extended) specified in
+Foreign.
 
 \section1 Defining QML-Specific Types and Attributes