Enable gadget wrapping for custom value types

[ChangeLog][QtQml] Custom C++ value types annotated with Q_GADGET are now fully
accessible in the QML and QJSEngine JavaScript environment.

QJSEngine::toScriptValue can be used for injection and fromScriptValue to
extraction. The QML "built-in" gadget wrappers for QPoint and the gui types are
not exposed this way, toScriptValue(point) will still return an opaque QVariant
wrapper. We could expose the core types right away, but then we would be
lacking an API to enable use of the Gui types that are registered in QtQuick.

It would be better to make the core types in qtbase gadgets and thus enable
them without the need for hooks and init functions to be called by the user.

Task-number: QTBUG-29769
Change-Id: I8179cd599bdc1209ff61cfdbdda419cb400296bb
Reviewed-by: Lars Knoll <lars.knoll@digia.com>

1 files changed, 27 insertions, 0 deletions

diff --git a/src/qml/doc/src/cppintegration/data.qdoc b/src/qml/doc/src/cppintegration/data.qdoc
index c083d63e51..26d3060318 100644
--- a/src/qml/doc/src/cppintegration/data.qdoc
+++ b/src/qml/doc/src/cppintegration/data.qdoc
@@ -307,6 +307,33 @@ them with default constructed values, do not use the indexed delete operator
 ("delete sequence[i]") but instead use the \c {splice} function
 ("sequence.splice(startIndex, deleteCount)").
 
+\section2 Value types
+
+Some value types in Qt such as QPoint are represented in JavaScript as objects
+that have the same properties and functions like in the C++ API. The same
+representation is possible with custom C++ value types. To enable a custom
+value type with the QML engine, the class declaration needs to be annotated
+with \c{Q_GADGET}. Properties that are intended to be visible in the JavaScript
+representation need to be declared with \c Q_PROPERTY. Similarly functions need
+to be marked with \c Q_INVOKABLE. This is the same with QObject based C++ APIs.
+For example, the \c Actor class below is annotated as gadget and has
+properties:
+
+\code
+ class Actor
+ {
+     Q_GADGET
+     Q_PROPERTY(QString name READ name WRITE setName)
+ public:
+     QString name() const { return m_name; }
+     void setName(const QString &name) { m_name = name; }
+
+ private:
+     QString m_name;
+ }
+
+ Q_DECLARE_METATYPE(Actor)
+\endcode
 
 \section1 Enumeration Types