diff options
Diffstat (limited to 'src/qml/doc/src/cppintegration/definetypes.qdoc')
| -rw-r--r-- | src/qml/doc/src/cppintegration/definetypes.qdoc | 428 |
1 files changed, 311 insertions, 117 deletions
diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc index 2e8102bd65..feb9053632 100644 --- a/src/qml/doc/src/cppintegration/definetypes.qdoc +++ b/src/qml/doc/src/cppintegration/definetypes.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-cppintegration-definetypes.html \title Defining QML Types from C++ @@ -40,12 +16,17 @@ as an instantiable \l{qtqml-typesystem-objecttypes.html}{QML object type} from QML, or enabling a singleton instance of the class to be imported and used from QML. -Additionally, the \l {Qt QML} module provides mechanisms for implementing QML-specific +Additionally, the \l {Qt Qml} module provides mechanisms for implementing QML-specific features such as \e{attached properties} and \e{default properties} in C++. (Note that a number of the important concepts covered in this document are demonstrated in the \l{Writing QML Extensions with C++} tutorial.) +\b{NOTE:} All headers that declare QML types need to be accessible without any prefix from the project's include path. + +For more information about C++ and the different QML integration methods, +see the +\l {Overview - QML and C++ Integration} {C++ and QML integration overview} page. \section1 Registering C++ Types with the QML Type System @@ -69,6 +50,21 @@ exposed to QML but the type itself should not be instantiable. For a quick guide to choosing the correct approach to expose C++ types to QML, see \l {Choosing the Correct Integration Method Between C++ and QML}. +\section2 Preconditions + +All the macros mentioned below are available from the \c qqmlregistration.h +header. You need to add the following code to the files using them in order to +make the macros available: + +\code +#include <QtQml/qqmlregistration.h> +\endcode + +Furthermore, your class declarations have to live in headers reachable via your +project's include path. The declarations are used to generate registration code +at compile time, and the registration code needs to include the headers that +contain the declarations. + \section2 Registering an Instantiable Object Type \b{Any QObject-derived C++ class can be registered as the definition of a @@ -80,9 +76,20 @@ class instance can be manipulated from QML; as Types to QML} explains, the properties, methods and signals of any QObject-derived class are accessible from QML code. -To register a QObject-derived class as an instantiable QML object type, call -qmlRegisterType() to register the class as QML type into a particular type -namespace. Clients can then import that namespace in order to use the type. +To register a QObject-derived class as an instantiable QML object type, add +\c QML_ELEMENT or \c QML_NAMED_ELEMENT(<name>) to the class declaration. You +also need to make adjustments in the build system. For qmake, add +\c {CONFIG += qmltypes}, a \c {QML_IMPORT_NAME}, and a +\c QML_IMPORT_MAJOR_VERSION to your project file. For CMake, the file containing +the class should be part of a target set-up with +\l{qt_add_qml_module}{qt_add_qml_module()}. +This will register the class into the type namespace under the given major version, +using either the class name or an explicitly given name as QML type name. The +minor version(s) will be derived from any revisions attached to properties, +methods, or signals. The default minor version is \c 0. You can explicitly +restrict the type to be available only from specific minor versions by adding +the \c QML_ADDED_IN_VERSION() macro to the class declaration. Clients can +import suitable versions of the namespace in order to use the type. For example, suppose there is a \c Message class with \c author and \c creationDate properties: @@ -93,25 +100,62 @@ class Message : public QObject Q_OBJECT Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged) Q_PROPERTY(QDateTime creationDate READ creationDate WRITE setCreationDate NOTIFY creationDateChanged) + QML_ELEMENT public: // ... }; \endcode -This type can be registered by calling qmlRegisterType() with an appropriate -type namespace and version number. For example, to make the type available in -the \c com.mycompany.messaging namespace with version 1.0: +This type can be registered by adding an appropriate type namespace and version +number to the project file. For example, to make the type available in the +\c com.mycompany.messaging namespace with version 1.0: + +\if defined(onlinedocs) + \tab {build-qt-app}{tab-cmake}{CMake}{selected} + \tab {build-qt-app}{tab-qmake}{qmake}{} + \tabcontent {tab-cmake} + \else + \section3 Using CMake +\endif + \badcode + qt_add_qml_module(messaging + URI com.mycompany.messaging + VERSION 1.0 + SOURCES + message.cpp message.h + ) + \endcode +\if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmake} +\else + \section3 Using QMake +\endif + \code + CONFIG += qmltypes + QML_IMPORT_NAME = com.mycompany.messaging + QML_IMPORT_MAJOR_VERSION = 1 + \endcode + + If the header the class is declared in is not accessible from your project's + include path, you may have to amend the include path so that the generated + registration code can be compiled. + + \code + INCLUDEPATH += com/mycompany/messaging + \endcode +\if defined(onlinedocs) + \endtabcontent +\endif + -\code -qmlRegisterType<Message>("com.mycompany.messaging", 1, 0, "Message"); -\endcode The type can be used in an \l{qtqml-syntax-basics.html#object-declarations} {object declaration} from QML, and its properties can be read and written to, as per the example below: \qml -import com.mycompany.messaging 1.0 +import com.mycompany.messaging Message { author: "Amelie" @@ -119,6 +163,102 @@ Message { } \endqml +\section2 Registering Value Types + +Any type with a \l{Q_GADGET} macro can the registered as a +\l{qtqml-typesystem-valuetypes.html}{QML value type}. Once such a type is +registered with the QML type system it can be used as property type in QML +code. Such an instance can be manipulated from QML; as +\l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ +Types to QML} explains, the properties and methods of any value type are +accessible from QML code. + +In contrast to object types, value types require \b{lower case} names. The +preferred way to register them is using the \l{QML_VALUE_TYPE} or +\l{QML_ANONYMOUS} macros. There is no equivalent to \l{QML_ELEMENT} as your +C++ classes are typically going to have upper case names. Otherwise the +registration is very similar to the registration of object types. + +For example, suppose you want to register a value type \c{person} that consists +of two strings for first and last name: + +\code +class Person +{ + Q_GADGET + Q_PROPERTY(QString firstName READ firstName WRITE setFirstName) + Q_PROPERTY(QString lastName READ lastName WRITE setLastName) + QML_VALUE_TYPE(person) +public: + // ... +}; +\endcode + +There are some further limitations on what you can do with value types: +\list +\li Value types cannot be singletons. +\li Value types need to be default-constructible and copy-constructible. +\li Using QProperty as a member of a value type is problematic. Value types get + copied, and you would need to decide what to do with any bindings on the + QProperty at that point. You should not use QProperty in value types. +\li Value types cannot provide attached properties. +\li The API to define extensions to value types (\l{QML_EXTENDED}) is not public + and subject to future changes. +\endlist + +\section2 Value Types with Enumerations + +Exposing enumerations from a value type to QML requires some extra steps. + +Value types have lower case names in QML and types with lower case +names are generally not addressable in JavaScript code (unless you specify +\l{ValueTypeBehavior}{pragma ValueTypeBehavior: Addressable}). If you have +a value type in C++ with an enumeration you want to expose to QML, you +need to expose the enumeration separately. + +This can be solved by using \l{QML_FOREIGN_NAMESPACE}. First, derive from +your value type to create a separate C++ type: + +\code +class Person +{ + Q_GADGET + Q_PROPERTY(QString firstName READ firstName WRITE setFirstName) + Q_PROPERTY(QString lastName READ lastName WRITE setLastName) + QML_VALUE_TYPE(person) +public: + enum TheEnum { A, B, C }; + Q_ENUM(TheEnum) + //... +}; + +class PersonDerived: public Person +{ + Q_GADGET +}; +\endcode + +Then expose the derived type as a foreign namespace: + +\code +namespace PersonDerivedForeign +{ + Q_NAMESPACE + QML_NAMED_ELEMENT(Person) + QML_FOREIGN_NAMESPACE(PersonDerived) +} +\endcode + +This produces a \l{qtqml-typesystem-namespaces.html}{QML Namespace} +called \c Person (upper case) with an enumeration called \c TheEnum and +values \c{A}, \c{B}, and \c{C}. Then you can write the following in QML: + +\qml + someProperty: Person.A +\endqml + +At the same time you can still use your value type called \c person +(lower case) exactly as before. \section2 Registering Non-Instantiable Types @@ -135,23 +275,25 @@ not be instantiable should not be instantiable from QML \endlist -The \l {Qt QML} module provides several methods for registering non-instantiable +The \l {Qt Qml} module provides several macros for registering non-instantiable types: \list -\li qmlRegisterType() (with no parameters) registers a C++ type that is not -instantiable and cannot be referred to from QML. This enables the engine to -coerce any inherited types that are instantiable from QML. -\li qmlRegisterInterface() registers an existing Qt interface type. The type is +\li QML_ANONYMOUS registers a C++ type that is not instantiable and cannot be +referred to from QML. This enables the engine to coerce any inherited types that +are instantiable from QML. +\li QML_INTERFACE registers an existing Qt interface type. The type is not instantiable from QML, and you cannot declare QML properties with it. Using C++ properties of this type from QML will do the expected interface casts, though. -\li qmlRegisterUncreatableType() registers a named C++ type that is not -instantiable but should be identifiable as a type to the QML type system. This -is useful if a type's enums or attached properties should be accessible from QML -but the type itself should not be instantiable. -\li qmlRegisterSingletonType() registers a singleton type that can be imported -from QML, as discussed below. +\li QML_UNCREATABLE(reason) combined with with QML_ELEMENT or QML_NAMED_ELEMENT +registers a named C++ type that is not instantiable but should be identifiable +as a type to the QML type system. This is useful if a type's enums or attached +properties should be accessible from QML but the type itself should not be +instantiable. The parameter should be an error message to be emitted if an +attempt at creating an instance of the type is detected. +\li QML_SINGLETON combined with QML_ELEMENT or QML_NAMED_ELEMENT registers a +singleton type that can be imported from QML, as discussed below. \endlist Note that all C++ types registered with the QML type system must be @@ -195,11 +337,26 @@ Rectangle { A QJSValue may also be exposed as a singleton type, however clients should be aware that properties of such a singleton type cannot be bound to. -See \l{qmlRegisterSingletonType()} for more information on how implement and +See \l{QML_SINGLETON} for more information on how implement and register a new singleton type, and how to use an existing singleton type. +See \l{Singletons in QML} for more in-depth information about singletons. \note Enum values for registered types in QML should start with a capital. +\section2 Final properties + +Properties declared final using the \c FINAL modifier to \l Q_PROPERTY cannot +be overridden. This means that any properties or functions of the same name, +declared either in QML or in C++ on derived types, are ignored by the QML +engine. You should declare properties \c FINAL when possible, in order to avoid +accidental overrides. An override of a property is visible not only in +derived classes, but also to QML code executing the context of the base class. +Such QML code, typically expects the original property, though. This is a +frequent source of mistakes. + +Properties declared \c FINAL can also not be overridden by functions in QML, or +by \l Q_INVOKABLE methods in C++. + \section2 Type Revisions and Versions Many of the type registration functions require versions to be specified @@ -245,30 +402,20 @@ class CppType : public BaseType { Q_OBJECT Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1) + QML_ELEMENT signals: Q_REVISION(1) void rootChanged(); }; \endcode -To register the new class revision to a particular version the following -function is used: - -\code -template<typename T, int metaObjectRevision> -int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) -\endcode - -To register \c CppType version 1 for \c {MyTypes 1.1}: - -\code -qmlRegisterType<CppType,1>("MyTypes", 1, 1, "CppType") -\endcode +The revisions given this way are automatically interpreted as minor versions to +the major version given in the project file. In this case, \c root is only +available when \c MyTypes version 1.1 or higher is imported. Imports of +\c MyTypes version 1.0 remain unaffected. -\c root is only available when \c MyTypes version 1.1 is imported. - -For the same reason, new types introduced in later versions should use -the minor version argument of qmlRegisterType. +For the same reason, new types introduced in later versions should be tagged +with the QML_ADDED_IN_VERSION macro. This feature of the language allows for behavioural changes to be made without breaking existing applications. Consequently QML module authors @@ -276,29 +423,10 @@ should always remember to document what changed between minor versions, and QML module users should check that their application still runs correctly before deploying an updated import statement. -You may also register the revision of a base class that your type depends -upon using the qmlRegisterRevision() function: - -\code -template<typename T, int metaObjectRevision> -int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) - -template<typename T, int metaObjectRevision> -int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason) - -template<typename T, typename E, int metaObjectRevision> -int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason) -\endcode - -For example, if \c BaseType is changed and now has a revision 1, you can -specify that your type uses the new revision: - -\code -qmlRegisterRevision<BaseType,1>("MyTypes", 1, 1); -\endcode - -This is useful when deriving from base classes provided by other authors, -e.g. when extending classes from the Qt Quick module. +Revisions of a base class that your type depends upon are automatically +registered when registering the type itself. This is useful when deriving +from base classes provided by other authors, e.g. when extending classes from +the Qt Quick module. \note The QML engine does not support revisions for properties or signals of grouped and attached property objects. @@ -312,32 +440,27 @@ classes directly, if this is either not possible or is complicated by some other concerns, extension objects allow limited extension possibilities without direct modifications. -\e{Extension objects} add additional properties to an existing type. Extension -objects can only add properties, not signals or methods. An extended type -definition allows the programmer to supply an additional type, known as the -\e{extension type}, when registering the class. The properties are transparently +\e{Extension objects} add additional properties to an existing type. An extended +type definition allows the programmer to supply an additional type, known as the +\e{extension type}, when registering the class. Its members are transparently merged with the original target class when used from within QML. For example: -\snippet referenceexamples/extended/example.qml 0 +\qml +QLineEdit { + leftMargin: 20 +} +\endqml The \c leftMargin property is a new property added to an existing C++ type, \l QLineEdit, without modifying its source code. -The \l {QQmlEngine::}{qmlRegisterExtendedType()} function is for registering extended types. -Note that it has two forms. - -\code -template<typename T, typename ExtendedT> -int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) - -template<typename T, typename ExtendedT> -int qmlRegisterExtendedType() -\endcode +The QML_EXTENDED(extension) macro is for registering extended types. The +argument is the name of another class to be used as extension. -This functions should be used instead of the regular \c qmlRegisterType() -variations. The arguments are identical to the corresponding non-extension -registration functions, except for the ExtendedT parameter which is the type of -the extension object. +You can also use QML_EXTENDED_NAMESPACE(namespace) to register a namespace, and +especially the enumerations declared within, as an extension to a type. If the +type you are extending is itself a namespace, you need to use +QML_NAMESPACE_EXTENDED(namespace) instead. An extension class is a regular QObject, with a constructor that takes a QObject pointer. However, the extension class creation is delayed until the first @@ -345,9 +468,32 @@ extended property is accessed. The extension class is created and the target object is passed in as the parent. When the property on the original is 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 @@ -425,8 +571,9 @@ the attributes to be made accessible to \e attachee objects. For the attached property accesses. Consequently the attachment object may not be deleted until the attachee \c object is destroyed. -\li is declared as an attaching type, by calling the QML_DECLARE_TYPEINFO() - macro with the QML_HAS_ATTACHED_PROPERTIES flag +\li is declared as an attaching type, by adding the QML_ATTACHED(attached) macro + to the class declaration. The argument is the name of the + \e{attached object type} \endlist @@ -441,6 +588,7 @@ class Message : public QObject Q_OBJECT Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged) Q_PROPERTY(QDateTime creationDate READ creationDate WRITE setCreationDate NOTIFY creationDateChanged) + QML_ELEMENT public: // ... }; @@ -472,6 +620,7 @@ class MessageBoardAttachedType : public QObject { Q_OBJECT Q_PROPERTY(bool expired READ expired WRITE setExpired NOTIFY expiredChanged) + QML_ANONYMOUS public: MessageBoardAttachedType(QObject *parent); bool expired() const; @@ -485,20 +634,21 @@ signals: Then the \e {attaching type}, \c MessageBoard, must declare a \c qmlAttachedProperties() method that returns an instance of the \e {attached object type} as implemented by MessageBoardAttachedType. -Additionally, \c Message board must be declared as an attached type -through the QML_DECLARE_TYPEINFO() macro: +Additionally, \c MessageBoard must be declared as an attaching type +via the QML_ATTACHED() macro: \code class MessageBoard : public QObject { Q_OBJECT + QML_ATTACHED(MessageBoardAttachedType) + QML_ELEMENT public: static MessageBoardAttachedType *qmlAttachedProperties(QObject *object) { return new MessageBoardAttachedType(object); } }; -QML_DECLARE_TYPEINFO(MessageBoard, QML_HAS_ATTACHED_PROPERTIES) \endcode Now, a \c Message type can access the properties and signals of the attached @@ -530,6 +680,14 @@ qDebug() << "Value of MessageBoard.expired:" << attached->expired(); \endcode +\section3 Propagating Attached Properties + +\l QQuickAttachedPropertyPropagator can be subclassed to propagate attached properties +from a parent object to its children, similar to \l {Control::}{font} and +\l {Item::}{palette} propagation. It supports propagation through +\l {Item}{items}, \l {Popup}{popups}, and \l {Window}{windows}. + + \section2 Property Modifier Types A property modifier type is a special kind of QML object type. A property @@ -577,6 +735,8 @@ Item { } \endqml +This is commonly referred to as "on" syntax. + Clients can register their own property value source types, but currently not property value write interceptors. @@ -607,6 +767,7 @@ class RandomNumberGenerator : public QObject, public QQmlPropertyValueSource Q_OBJECT Q_INTERFACES(QQmlPropertyValueSource) Q_PROPERTY(int maxValue READ maxValue WRITE setMaxValue NOTIFY maxValueChanged); + QML_ELEMENT public: RandomNumberGenerator(QObject *parent) : QObject(parent), m_maxValue(100) @@ -672,7 +833,7 @@ assignment fails does the engine call the \l the type to also be used in contexts other than just as a value source. -\section2 Specifying Default Properties for QML Object Types +\section2 Specifying Default and Parent Properties for QML Object Types Any QObject-derived type that is registered as an instantiable QML object type can optionally specify a \e {default property} for the type. A default @@ -690,6 +851,7 @@ class MessageBoard : public QObject Q_OBJECT Q_PROPERTY(QQmlListProperty<Message> messages READ messages) Q_CLASSINFO("DefaultProperty", "messages") + QML_ELEMENT public: QQmlListProperty<Message> messages(); @@ -728,6 +890,37 @@ objects added to this \c data property are also added to the list of to be declared for an item without explicitly assigning them to the \l{Item::}{children} property.) +Additionally, you can declare a "ParentProperty" Q_CLASSINFO() to inform the QML +engine which property should denote the parent object in the QML hierarchy. For +example, the Message type might be declared as follows: + +\code +class Message : public QObject +{ + Q_OBJECT + Q_PROPERTY(QObject* board READ board BINDABLE boardBindable) + Q_PROPERTY(QString author READ author BINDABLE authorBindable) + Q_CLASSINFO("ParentProperty", "board") + QML_ELEMENT + +public: + Message(QObject *parent = nullptr) : QObject(parent) { m_board = parent; } + + QObject *board() const { return m_board.value(); } + QBindable<QObject *> boardBindable() { return QBindable<QObject *>(&m_board); } + + QString author() const { return m_author.value(); } + QBindable<QString> authorBindable() { return QBindable<QString>(&m_author); } + +private: + QProperty<QObject *> m_board; + QProperty<QString> m_author; +}; +\endcode + +Defining the parent property affords \l qmllint and other tools better insight +into the intention of your code and avoids false positive warnings on some +property accesses. \section2 Defining Visual Items with the Qt Quick Module @@ -753,7 +946,7 @@ its properties have been set. For example, this may be the case if the initialization is costly, or if the initialization should not be performed until all property values have been initialized. -The \l {Qt QML} module provides the QQmlParserStatus to be subclassed for these +The \l {Qt Qml} module provides the QQmlParserStatus to be subclassed for these purposes. It defines a number of virtual methods that are invoked at various stages during component instantiation. To receive these notifications, a C++ class should inherit QQmlParserStatus and also notify the Qt meta system @@ -766,6 +959,7 @@ class MyQmlType : public QObject, public QQmlParserStatus { Q_OBJECT Q_INTERFACES(QQmlParserStatus) + QML_ELEMENT public: virtual void componentComplete() { |