diff options
Diffstat (limited to 'src/qml/doc/src')
| -rw-r--r-- | src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc | 33 | ||||
| -rw-r--r-- | src/qml/doc/src/qmlfunctions.qdoc | 140 | ||||
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc | 20 |
3 files changed, 154 insertions, 39 deletions
diff --git a/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc b/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc index 9c33979f40..0a824bb5b5 100644 --- a/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc +++ b/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc @@ -166,9 +166,12 @@ updated, and any \c onButtonTextChanged handlers would not be called. \section2 Invoking QML Methods -All QML methods are exposed to the meta-object system and can be called from C++ -using QMetaObject::invokeMethod(). Method parameters and return values passed -from QML are always translated into QVariant values in C++. +All QML methods are exposed to the meta-object system and can be called from +C++ using QMetaObject::invokeMethod(). You can specify types for the parameters +and the return value after the colon character, as shown in the code snippet +below. This can be useful, for example, when you want to connect a signal in +C++ with a certain signature to a QML-defined method. If you omit the types, +the C++ signature will use QVariant. Here is a C++ application that calls a QML method using QMetaObject::invokeMethod(): @@ -182,9 +185,12 @@ QMetaObject::invokeMethod(): \li \snippet qml/qtbinding/functions-qml/main.cpp 0 \endtable -Notice the Q_RETURN_ARG() and Q_ARG() arguments for QMetaObject::invokeMethod() -must be specified as QVariant types, as this is the generic data type used for -QML method parameters and return values. +Notice the parameter and return type specified after the colon. You can use \l +{QML Basic Types}{basic types} and \l {QML Object Types}{object types} as type +names. + +If the type is omitted in QML, then you must specify QVariant as type with +Q_RETURN_ARG() and Q_ARG() when calling QMetaObject::invokeMethod. \section2 Connecting to QML Signals @@ -210,9 +216,8 @@ QObject::connect(), so that the \c cppSlot() method is called whenever the \snippet qml/qtbinding/signals-qml/main.cpp 0 \endtable -When a QML object type is used as a signal parameter, the parameter should -use \l var as the type, and the value should be received in C++ using the -QVariant type: +A QML object type in a signal parameter is translated to a pointer to the class +in C++: \table \row @@ -226,7 +231,7 @@ QVariant type: id: item width: 100; height: 100 - signal qmlSignal(var anObject) + signal qmlSignal(anObject: Item) MouseArea { anchors.fill: parent @@ -241,18 +246,16 @@ QVariant type: { Q_OBJECT public slots: - void cppSlot(const QVariant &v) { - qDebug() << "Called the C++ slot with value:" << v; + void cppSlot(QQuickItem *item) { + qDebug() << "Called the C++ slot with item:" << item; - QQuickItem *item = - qobject_cast<QQuickItem*>(v.value<QObject*>()); qDebug() << "Item dimensions:" << item->width() << item->height(); } }; int main(int argc, char *argv[]) { - QApplication app(argc, argv); + QGuiApplication app(argc, argv); QQuickView view(QUrl::fromLocalFile("MyItem.qml")); QObject *item = view.rootObject(); diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index 969dd51433..b2d322465d 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -274,17 +274,16 @@ */ /*! - \fn int qmlRegisterType() - \relates QQmlEngine - \overload + \fn int qmlRegisterAnonymousType(const char *uri, int versionMajor) - This template function registers the C++ type in the QML - system. Instances of this type cannot be created from the QML - system. + This template function registers the C++ type in the QML system as an anonymous type. The + resulting QML type does not have a name. Therefore, instances of this type cannot be created from + the QML system. You can, however, access instances of the type when they are exposed as properties + of other types. - This function should be used when the type will not be referenced by name. - Specifically, it has to be used for C++ types that are used as the left-hand - side of a property binding. + Use this function when the type will not be referenced by name, specifically for C++ types that + are used on the left-hand side of a property binding. To indicate to which module the type belongs + use \a uri and \a versionMajor. For example, consider the following two classes: @@ -344,18 +343,29 @@ \code qmlRegisterType<Foo>("App", 1, 0, "Foo"); - qmlRegisterType<Bar>(); + qmlRegisterAnonymousType<Bar>("App", 1); \endcode As the \c Foo type is instantiated in QML, it must be registered - with the version of \l qmlRegisterType() that takes an import URI. + with the version of \l qmlRegisterType() that takes an element name. Returns the QML type id. + \since 5.14 \sa {Choosing the Correct Integration Method Between C++ and QML} */ /*! + \fn int qmlRegisterType() + \relates QQmlEngine + \overload + \deprecated + + Do not use this function. For anonymous type registrations, use \l qmlRegisterAnonymousType(), + and make sure to provide a URI and a major version. +*/ + +/*! \fn int qmlRegisterInterface(const char *typeName) \relates QQmlEngine @@ -448,7 +458,7 @@ */ /*! - \fn template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true) + \fn template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create) \relates QQmlEngine The form of this template function is: @@ -487,8 +497,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. @@ -538,7 +547,7 @@ Alternatively, you can use a C++11 lambda: \code - qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * { + qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * { Q_UNUSED(engine) Q_UNUSED(scriptEngine) @@ -564,6 +573,14 @@ \sa {Choosing the Correct Integration Method Between C++ and QML} */ + +/*! + \fn int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject*(QQmlEngine *, QJSEngine *)> callback) + \relates QQmlEngine + + \overload qmlRegisterSingletonType +*/ + /*! \fn int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName) \relates QQmlEngine @@ -611,6 +628,99 @@ */ /*! + \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 diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc index c4ecaf367c..401e099ebf 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc @@ -464,22 +464,24 @@ Unlike an ordinary property, an alias has the following restrictions: must be provided when the alias is first declared. \li It cannot refer to \l {Attached Properties and Attached Signal Handlers} {attached properties}. -\li It cannot refer to grouped properties; the following code will not work: +\li It cannot refer to properties inside a hierarchy with depth 3 or greater. The + following code will not work: \code - property alias color: rectangle.border.color + property alias color: myItem.myRect.border.color - Rectangle { - id: rectangle + Item { + id: myItem + property Rectangle myRect } \endcode - However, aliases to \l {QML Basic Types}{value type} properties do work: + However, aliases to properties that are up to two levels deep will work. + \code - property alias rectX: object.rectProperty.x + property alias color: rectangle.border.color - Item { - id: object - property rect rectProperty + Rectangle { + id: rectangle } \endcode \endlist |