diff options
Diffstat (limited to 'src/qml/doc')
23 files changed, 1003 insertions, 274 deletions
diff --git a/src/qml/doc/snippets/code/backend/backend.h b/src/qml/doc/snippets/code/backend/backend.h index fa7ce9eb86..6c64236bc7 100644 --- a/src/qml/doc/snippets/code/backend/backend.h +++ b/src/qml/doc/snippets/code/backend/backend.h @@ -53,11 +53,13 @@ #include <QObject> #include <QString> +#include <qqml.h> class BackEnd : public QObject { Q_OBJECT Q_PROPERTY(QString userName READ userName WRITE setUserName NOTIFY userNameChanged) + QML_ELEMENT public: explicit BackEnd(QObject *parent = nullptr); diff --git a/src/qml/doc/snippets/code/backend/backend.pro b/src/qml/doc/snippets/code/backend/backend.pro new file mode 100644 index 0000000000..8bd2422718 --- /dev/null +++ b/src/qml/doc/snippets/code/backend/backend.pro @@ -0,0 +1,17 @@ +QT += qml + +#![registration] +CONFIG += qmltypes +QML_IMPORT_NAME = io.qt.examples.backend +QML_IMPORT_MAJOR_VERSION = 1 +#![registration] + +HEADERS += \ + backend.h + +SOURCES += \ + backend.cpp \ + main.cpp + +RESOURCES += \ + main.qml diff --git a/src/qml/doc/snippets/code/backend/main.cpp b/src/qml/doc/snippets/code/backend/main.cpp index 91a012dfda..52fcb38621 100644 --- a/src/qml/doc/snippets/code/backend/main.cpp +++ b/src/qml/doc/snippets/code/backend/main.cpp @@ -51,14 +51,10 @@ #include <QGuiApplication> #include <QQmlApplicationEngine> -#include "backend.h" - int main(int argc, char *argv[]) { QGuiApplication app(argc, argv); - qmlRegisterType<BackEnd>("io.qt.examples.backend", 1, 0, "BackEnd"); - QQmlApplicationEngine engine; engine.load(QUrl(QStringLiteral("qrc:/main.qml"))); diff --git a/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp index d74cc13d04..b41a9b4dff 100644 --- a/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp @@ -51,84 +51,102 @@ #include "avatarExample.h" #include <QQmlEngine> #include <QQmlComponent> +#include <QGuiApplication> -void registerTypes() +struct Expectations { -//![0] - qmlRegisterType<AvatarExample>("Qt.example", 1, 0, "AvatarExample"); -//![0] -} + QQmlEngine engine; -void expectOne() -{ + void expectOne() + { //![1] -QQmlComponent component(&engine, "exampleOne.qml"); -QObject *object = component.create(); -// The scarce resource will have been released automatically -// by this point, after the binding expression was evaluated. -delete object; + QQmlComponent component(&engine, "qrc:/exampleOne.qml"); + QObject *object = component.create(); + // The scarce resource will have been released automatically + // by this point, after the binding expression was evaluated. + bool expectedResult = (object->property("avatarWidth").toInt() == 100); + delete object; //![1] -} + Q_ASSERT(expectedResult); + } -void expectTwo() -{ + void expectTwo() + { //![2] -QQmlComponent component(&engine, "exampleTwo.qml"); -QObject *object = component.create(); -// The scarce resource will not have been released automatically -// after the binding expression was evaluated. -// Since the scarce resource was not released explicitly prior -// to the binding expression being evaluated, we get: -bool expectedResult = (object->property("avatar").isValid() == true); -delete object; + QQmlComponent component(&engine, "qrc:/exampleTwo.qml"); + QObject *object = component.create(); + // The scarce resource will not have been released automatically + // after the binding expression was evaluated. + // Since the scarce resource was not released explicitly prior + // to the binding expression being evaluated, we get: + bool expectedResult = (object->property("avatar").isValid() == true); + delete object; //![2] -} + Q_ASSERT(expectedResult); + } -void expectThree() -{ + void expectThree() + { //![3] -QQmlComponent component(&engine, "exampleThree.qml"); -QObject *object = component.create(); -// The resource was preserved explicitly during evaluation of the -// JavaScript expression. Thus, during property assignment, the -// scarce resource was still valid, and so we get: -bool expectedResult = (object->property("avatar").isValid() == true); -// The scarce resource will not be released until all references to -// the resource are released, and the JavaScript garbage collector runs. -delete object; + QQmlComponent component(&engine, "qrc:/exampleThree.qml"); + QObject *object = component.create(); + // The resource was preserved explicitly during evaluation of the + // JavaScript expression. Thus, during property assignment, the + // scarce resource was still valid, and so we get: + bool expectedResult = (object->property("avatar").isValid() == true); + // The scarce resource will not be released until all references to + // the resource are released, and the JavaScript garbage collector runs. + delete object; //![3] -} + Q_ASSERT(expectedResult); + } -void expectFour() -{ + void expectFour() + { //![4] -QQmlComponent component(&engine, "exampleFour.qml"); -QObject *object = component.create(); -// The scarce resource was explicitly preserved by the client during -// the importAvatar() function, and so the scarce resource -// remains valid until the explicit call to releaseAvatar(). As such, -// we get the expected results: -bool expectedResultOne = (object->property("avatarOne").isValid() == true); -bool expectedResultTwo = (object->property("avatarTwo").isValid() == false); -// Because the scarce resource referenced by avatarTwo was released explicitly, -// it will no longer be consuming any system resources (beyond what a normal -// JS Object would; that small overhead will exist until the JS GC runs, as per -// any other JavaScript object). -delete object; + QQmlComponent component(&engine, "qrc:/exampleFour.qml"); + QObject *object = component.create(); + // The scarce resource was explicitly preserved by the client during + // the importAvatar() function, and so the scarce resource + // remains valid until the explicit call to releaseAvatar(). As such, + // we get the expected results: + bool expectedResultOne = (object->property("avatarOne").isValid() == true); + bool expectedResultTwo = (object->property("avatarTwo").isValid() == false); + // Because the scarce resource referenced by avatarTwo was released explicitly, + // it will no longer be consuming any system resources (beyond what a normal + // JS Object would; that small overhead will exist until the JS GC runs, as per + // any other JavaScript object). + delete object; //![4] -} + Q_ASSERT(expectedResultOne); + Q_ASSERT(expectedResultTwo); + } -void expectFive() -{ + void expectFive() + { //![5] -QQmlComponent component(&engine, "exampleFive.qml"); -QObject *object = component.create(); -// We have the expected results: -bool expectedResultOne = (object->property("avatarOne").isValid() == false); -bool expectedResultTwo = (object->property("avatarTwo").isValid() == false); -// Because although only avatarTwo was explicitly released, -// avatarOne and avatarTwo were referencing the same -// scarce resource. -delete object; + QQmlComponent component(&engine, "qrc:/exampleFive.qml"); + QObject *object = component.create(); + // We have the expected results: + bool expectedResultOne = (object->property("avatarOne").isValid() == false); + bool expectedResultTwo = (object->property("avatarTwo").isValid() == false); + // Because although only avatarTwo was explicitly released, + // avatarOne and avatarTwo were referencing the same + // scarce resource. + delete object; //![5] + Q_ASSERT(expectedResultOne); + Q_ASSERT(expectedResultTwo); + } +}; + +int main(int argc, char *argv[]) +{ + QGuiApplication app(argc, argv); + Expectations expectations; + expectations.expectOne(); + expectations.expectTwo(); + expectations.expectThree(); + expectations.expectFour(); + expectations.expectFive(); } diff --git a/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.h b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.h index fb9e238512..1acc3a1c2f 100644 --- a/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.h +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.h @@ -53,6 +53,7 @@ #include <QObject> #include <QPixmap> +#include <qqml.h> //![0] // avatarExample.h @@ -60,6 +61,8 @@ class AvatarExample : public QObject { Q_OBJECT Q_PROPERTY(QPixmap avatar READ avatar WRITE setAvatar NOTIFY avatarChanged) + QML_ELEMENT + public: AvatarExample(QObject *parent = 0) : QObject(parent), m_value(100, 100) diff --git a/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/scarceresources.pro b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/scarceresources.pro new file mode 100644 index 0000000000..d88f8f574c --- /dev/null +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/scarceresources.pro @@ -0,0 +1,22 @@ +QT += qml gui + +#![0] +CONFIG += qmltypes +QML_IMPORT_NAME = Qt.example +QML_IMPORT_MAJOR_VERSION = 1 +#![0] + +RESOURCES += \ + exampleFive.qml \ + exampleFour.js \ + exampleFour.qml \ + exampleOne.qml \ + exampleThree.js \ + exampleThree.qml \ + exampleTwo.qml + +HEADERS += \ + avatarExample.h + +SOURCES += \ + avatarExample.cpp diff --git a/src/qml/doc/snippets/qml/qml-documents/A.qml b/src/qml/doc/snippets/qml/qml-documents/A.qml new file mode 100644 index 0000000000..83c59dc5d7 --- /dev/null +++ b/src/qml/doc/snippets/qml/qml-documents/A.qml @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +// A.qml +import QtQuick 2.15 + +Item { + id: root + property string message: "From A" + component MyInlineComponent : Item { + Component.onCompleted: console.log(root.message) + } +} +//! [document] diff --git a/src/qml/doc/snippets/qml/qml-documents/B.qml b/src/qml/doc/snippets/qml/qml-documents/B.qml new file mode 100644 index 0000000000..5e603d50e0 --- /dev/null +++ b/src/qml/doc/snippets/qml/qml-documents/B.qml @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +// B.qml +import QtQuick 2.15 + +Item { + A.MyInlineComponent {} +} +//! [document] diff --git a/src/qml/doc/snippets/qml/qml-documents/Images.qml b/src/qml/doc/snippets/qml/qml-documents/Images.qml new file mode 100644 index 0000000000..fc9fa60282 --- /dev/null +++ b/src/qml/doc/snippets/qml/qml-documents/Images.qml @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +// Images.qml +import QtQuick 2.15 + +Item { + component LabeledImage: Column { + property alias source: image.source + property alias caption: text.text + + Image { + id: image + width: 50 + height: 50 + } + Text { + id: text + font.bold: true + } + } + + Row { + LabeledImage { + id: before + source: "before.png" + caption: "Before" + } + LabeledImage { + id: after + source: "after.png" + caption: "After" + } + } + property LabeledImage selectedImage: before +} +//! [document] diff --git a/src/qml/doc/snippets/qml/qml-documents/LabeledImageBox.qml b/src/qml/doc/snippets/qml/qml-documents/LabeledImageBox.qml new file mode 100644 index 0000000000..5a259a0cc6 --- /dev/null +++ b/src/qml/doc/snippets/qml/qml-documents/LabeledImageBox.qml @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +// LabeledImageBox.qml +import QtQuick 2.15 + +Rectangle { + property alias caption: image.caption + property alias source: image.source + border.width: 2 + border.color: "black" + Images.LabeledImage { + id: image + } +} +//! [document] diff --git a/src/qml/doc/src/cppintegration/data.qdoc b/src/qml/doc/src/cppintegration/data.qdoc index 7c2693508c..9dfb7837e5 100644 --- a/src/qml/doc/src/cppintegration/data.qdoc +++ b/src/qml/doc/src/cppintegration/data.qdoc @@ -197,6 +197,25 @@ type or method parameter, the value can be created as a JavaScript array or object in QML, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++. +Mind that QVariantList and QVariantMap properties of C++ types are stored as +values and cannot be changed in place by QML code. You can only replace the +whole map or list, but not manipulate its contents. The following code does +not work if the property \c l is a QVariantList: + +\code +MyListExposingItem { + l: [1, 2, 3] + Component.onCompleted: l[0] = 10 +} +\endcode + +The following code does work: +\code +MyListExposingItem { + l: [1, 2, 3] + Component.onCompleted: l = [10, 2, 3] +} +\endcode \section2 QDateTime to JavaScript Date @@ -284,7 +303,7 @@ In particular, QML currently supports: \li \c {std::vector<bool>} \endlist -and all registered QList, QVector, QQueue, QStack, QSet, QLinkedList, std::list, +and all registered QList, QVector, QQueue, QStack, QSet, std::list, std::vector that contain a type marked with \l Q_DECLARE_METATYPE. These sequence types are implemented directly in terms of the underlying C++ diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc index 2e8102bd65..cbbbd9ba58 100644 --- a/src/qml/doc/src/cppintegration/definetypes.qdoc +++ b/src/qml/doc/src/cppintegration/definetypes.qdoc @@ -80,9 +80,17 @@ 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 and +\c {CONFIG += qmltypes}, a \c {QML_IMPORT_NAME}, and a +\c QML_IMPORT_MAJOR_VERSION to your project file. 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_MINOR_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,17 +101,20 @@ 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: \code -qmlRegisterType<Message>("com.mycompany.messaging", 1, 0, "Message"); +CONFIG += qmltypes +QML_IMPORT_NAME = com.mycompany.messaging +QML_IMPORT_MAJOR_VERSION = 1 \endcode The type can be used in an \l{qtqml-syntax-basics.html#object-declarations} @@ -135,23 +146,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,7 +208,7 @@ 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. \note Enum values for registered types in QML should start with a capital. @@ -245,30 +258,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: +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. -\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 - -\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_MINOR_VERSION macro. This feature of the language allows for behavioural changes to be made without breaking existing applications. Consequently QML module authors @@ -276,29 +279,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. @@ -323,21 +307,8 @@ merged with the original target class when used from within QML. For example: 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 - -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. +The QML_EXTENDED(extended) macro is for registering extended types. The +argument is the name of another class to be used as extension. 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 @@ -425,8 +396,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 +413,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 +445,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 +459,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 @@ -607,6 +582,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) @@ -690,6 +666,7 @@ class MessageBoard : public QObject Q_OBJECT Q_PROPERTY(QQmlListProperty<Message> messages READ messages) Q_CLASSINFO("DefaultProperty", "messages") + QML_ELEMENT public: QQmlListProperty<Message> messages(); @@ -766,6 +743,7 @@ class MyQmlType : public QObject, public QQmlParserStatus { Q_OBJECT Q_INTERFACES(QQmlParserStatus) + QML_ELEMENT public: virtual void componentComplete() { diff --git a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc index d587173e5a..458768bf18 100644 --- a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc +++ b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc @@ -103,11 +103,22 @@ functionality of an existing QObject-based class, it could inherit from that cla Alternatively, if we want to create a visual item that doesn't need to perform drawing operations with the QPainter API, we can just subclass QQuickItem. -The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro, -and overrides QQuickPaintedItem::paint(). The class implementation in \c piechart.cpp -simply sets and returns the \c m_name and \c m_color values as appropriate, and -implements \c paint() to draw a simple pie chart. It also turns off the -QGraphicsItem::ItemHasNoContents flag to enable painting: +The \c PieChart class defines the two properties, \c name and \c color, with the +Q_PROPERTY macro, and overrides QQuickPaintedItem::paint(). The \c PieChart +class is registered using the QML_ELEMENT macro, to allow it to be used from +QML. If you don't register the class, \c app.qml won't be able to create a +\c PieChart. + +For the registration to take effect, the \c qmltypes option is added to +\c CONFIG in the project file and a \c QML_IMPORT_NAME and +\c QML_IMPORT_MAJOR_VERSION are given: + +\snippet tutorials/extending-qml/chapter1-basics/chapter1-basics.pro 0 + +The class implementation in \c piechart.cpp simply sets and returns the +\c m_name and \c m_color values as appropriate, and implements \c paint() to +draw a simple pie chart. It also turns off the QGraphicsItem::ItemHasNoContents +flag to enable painting: \snippet tutorials/extending-qml/chapter1-basics/piechart.cpp 0 \dots 0 @@ -125,9 +136,7 @@ provided for various other \l {QML Basic Types}{basic types}; for example, a str like "640x480" can be automatically converted to a QSize value. We'll also create a C++ application that uses a QQuickView to run and -display \c app.qml. The application must register the \c PieChart type -using the qmlRegisterType() function, to allow it to be used from QML. If -you don't register the type, \c app.qml won't be able to create a \c PieChart. +display \c app.qml. Here is the application \c main.cpp: @@ -143,7 +152,7 @@ Now we can build and run the application: \image extending-tutorial-chapter1.png -\note You may see a warning \e {Expression ... depends on non-NOTIFYable properties: +\note You may see a warning \e {Expression ... depends on non-NOTIFYable properties: PieChart::name}. This happens because we add a binding to the writable \c name property, but haven't yet defined a notify signal for it. The QML engine therefore cannot update the binding if the \c name value changes. This is addressed in @@ -450,7 +459,7 @@ In this tutorial, we've shown the basic steps for creating a QML extension: \list \li Define new QML types by subclassing QObject and registering them with - qmlRegisterType() + QML_ELEMENT or QML_NAMED_ELEMENT() \li Add callable methods using \l Q_INVOKABLE or Qt slots, and connect to Qt signals with an \c onSignal syntax \li Add property bindings by defining \l{Qt's Property System}{NOTIFY} signals diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc index fbb654378d..bf4565a996 100644 --- a/src/qml/doc/src/cppintegration/topic.qdoc +++ b/src/qml/doc/src/cppintegration/topic.qdoc @@ -49,8 +49,16 @@ file contents with: \snippet code/backend/backend.h backend_header The \c Q_PROPERTY macro declares a property that could be accessed from QML. +The \c QML_ELEMENT macro makes the BackEnd class available in QML. -\li Replace its C++ file contents with: +\li Add the following lines to your project file: + +\snippet code/backend/backend.pro registration + +The BackEnd class is automatically registered as a type, which is accessible +from QML by importing the URL, "\c{io.qt.examples.backend 1.0}". + +\li Replace the contents of \c{backend.cpp} with: \snippet code/backend/backend.cpp backend_cpp @@ -58,14 +66,6 @@ The \c setUserName function emits the \c userNameChanged signal every time \c m_userName value changes. The signal can be handled from QML using the \c onUserNameChanged handler. -\li Include \c "backend.h" in \c main.cpp and register the class as a QML type -under a import URL as shown below: - -\snippet code/backend/main.cpp main_cpp - -The BackEnd class is registered as a type, which is accessible from QML by -importing the URL, "\c{io.qt.examples.backend 1.0}". - \li Replace the contents of \c main.qml with the following code: \snippet code/backend/main.qml main_qml diff --git a/src/qml/doc/src/javascript/expressions.qdoc b/src/qml/doc/src/javascript/expressions.qdoc index b83127389a..b27bde3cf9 100644 --- a/src/qml/doc/src/javascript/expressions.qdoc +++ b/src/qml/doc/src/javascript/expressions.qdoc @@ -147,7 +147,7 @@ Rectangle { TapHandler { id: inputHandler - onTapped: { + onTapped: { // arbitrary JavaScript expression console.log("Tapped!") } @@ -339,7 +339,7 @@ For the following examples, imagine that we have defined the following class: and that we have registered it with the QML type-system as follows: -\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 0 +\snippet qml/integrating-javascript/scarceresources/scarceresources.pro 0 The AvatarExample class has a property which is a pixmap. When the property is accessed in JavaScript scope, a copy of the resource will be created and diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc index 8e26c4aadd..9227f0e604 100644 --- a/src/qml/doc/src/javascript/imports.qdoc +++ b/src/qml/doc/src/javascript/imports.qdoc @@ -154,7 +154,7 @@ var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3 \endcode In particular, this may be useful in order to access functionality provided -via a singleton type; see qmlRegisterSingletonType() for more information. +via a singleton type; see QML_SINGLETON for more information. \note The .import syntax doesn't work for scripts used in the \l {WorkerScript} */ diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index 67c0f6bb25..04d907f168 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -26,6 +26,274 @@ ****************************************************************************/ /*! + \macro QML_ELEMENT + \relates QQmlEngine + + Declares the enclosing type or namespace to be available in QML, using its + class or namespace name as the QML element name. + + For example, this makes the C++ class \c Slider available as a QML type + named \c Slider. + + \code + class Slider : public QObject + { + Q_OBJECT + QML_ELEMENT + ... + } + \endcode + + You can use the build system to register the type in the type namespace + \e {com.mycompany.qmlcomponents} with major version \c 1 by specifying the + following in your project file: + + \badcode + CONFIG += qmltypes + QML_IMPORT_NAME = com.mycompany.qmlcomponents + QML_IMPORT_MAJOR_VERSION = 1 + \endcode + + Once registered, the type can be used in QML by importing the + same type namespace and version number: + + \qml + import com.mycompany.qmlcomponents 1.0 + + Slider { + // ... + } + \endqml + + You can also make namespaces tagged with Q_NAMESPACE available this way, in + order to expose any enums tagged with Q_ENUM_NS they contain. + + \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT(), + Q_REVISION(), QML_ADDED_IN_MINOR_VERSION() +*/ + +/*! + \macro QML_NAMED_ELEMENT(name) + \relates QQmlEngine + + Declares the enclosing type or namespace to be available in QML, using \a name + as the element name. Otherwise behaves the same as QML_ELEMENT. + + \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_ELEMENT +*/ + +/*! + \macro QML_ANONYMOUS + \relates QQmlEngine + + Declares the enclosing type to be available, but anonymous in QML. The type + cannot be created or used as property type, but when passed from C++, it is + recognized. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_INTERFACE +*/ + +/*! + \macro QML_INTERFACE + \relates QQmlEngine + + This macro registers the enclosing C++ type in the QML system as an interface. + + Types registered as an interface in QML should also declare themselves as an + interface with the \l {The Meta-Object System}{meta object system}. For + example: + + \code + struct FooInterface + { + QML_INTERFACE + public: + virtual ~FooInterface(); + virtual void doSomething() = 0; + }; + + Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface") + \endcode + + When registered with QML in this way, they can be used as property types: + + Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo) + + When you assign a \l QObject sub-class to this property, the QML engine does + the interface cast to \c FooInterface* automatically. + + Interface types are implicitly anonymous and uncreatable in QML. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_ANONYMOUS +*/ + +/*! + \macro QML_UNCREATABLE(reason) + \relates QQmlEngine + + Declares that the enclosing type shall not be creatable from QML. This takes + effect if the type is available in QML, by having a \l QML_ELEMENT or + \l QML_NAMED_ELEMENT() macro. The \a reason will be emitted as error message if an + attempt to create the type from QML is detected. + + Some QML types are implicitly uncreatable, in particular types exposed with + \l QML_ANONYMOUS or namespaces exposed with \l QML_ELEMENT or + \l QML_NAMED_ELEMENT(). For such types, \l QML_UNCREATABLE() can be used to + provide a custom error message. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS +*/ + +/*! + \macro QML_SINGLETON + \relates QQmlEngine + + Declares the enclosing type to be a singleton in QML. This only takes effect + if the type is available in QML, by having a \l QML_ELEMENT or + \l QML_NAMED_ELEMENT() macro. By default, each QQmlEngine will try to create a + singleton instance using the type's default constructor when the type is first + accessed. If there is no default constructor the singleton is initially + inaccessible. This behavior can be overridden by calling + \l qmlRegisterSingletonType() with a specific factory function or + \l qmlRegisterSingletonInstance() with a specific instance for the same class + and the same type namespace and version. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), qmlRegisterSingletonInstance(). +*/ + +/*! + \macro QML_ADDED_IN_MINOR_VERSION(VERSION) + \relates QQmlEngine + + Declares that the enclosing type or namespace was added in the specified minor + \a VERSION, relative to the module major version. The minor version is assumed + to be in line with any revisions given by \l Q_REVISION() macros on methods, + slots, or signals, and any REVISION tags on properties declared with + \l Q_PROPERTY(). + + \l QML_ADDED_IN_MINOR_VERSION() only takes effect if the type or namespace is + available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), + \l QML_ANONYMOUS, or \l QML_INTERFACE macro. + + If the QML module the type belongs to is imported with a lower version than + the one determined this way, the QML type is invisible. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT() +*/ + +/*! + \macro QML_REMOVED_IN_MINOR_VERSION(VERSION) + \relates QQmlEngine + + Declares that the enclosing type or namespace was removed in the specified + minor \a VERSION, relative to the module major version. This is primarily + useful when replacing the implementation of a QML type. If a corresponding + \l QML_ADDED_IN_MINOR_VERSION() is present on a different type or namespace of + the same QML name, then the removed type is used when importing versions of + the module lower than \a VERSION, and the added type is used when importing + versions of the module greater or equal \a VERSION. + + \l QML_REMOVED_IN_MINOR_VERSION() only takes effect if type or namespace is + available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), + \l QML_ANONYMOUS, or \l QML_INTERFACE macro. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT() +*/ + +/*! + \macro QML_ATTACHED(ATTACHED_TYPE) + \relates QQmlEngine + + Declares that the enclosing type attaches \a ATTACHED_TYPE as an + \l {Attached Properties and Attached Signal Handlers} + {attached property} to other types. This takes effect if the type + is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(), + {Providing Attached Properties} +*/ + +/*! + \macro QML_EXTENDED(EXTENDED_TYPE) + \relates QQmlEngine + + Declares that the enclosing type uses \a EXTENDED_TYPE as an extension to + provide further properties and methods in QML. This takes effect if the type + is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), {Registering Extension Objects} +*/ + +/*! + \macro QML_FOREIGN(FOREIGN_TYPE) + \relates QQmlEngine + + Declares that any \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), \l QML_ANONYMOUS, + \l QML_INTERFACE, \l QML_UNCREATABLE(), \l QML_SINGLETON, + \l QML_ADDED_IN_MINOR_VERSION(), \l QML_REMOVED_IN_MINOR_VERSION(), + \l QML_ATTACHED(), or \l QML_EXTENDED() macros in the enclosing C++ type do + not apply to the enclosing type but instead to \a FOREIGN_TYPE. The enclosing + type still needs to be registered with the + \l {The Meta-Object System}{meta object system} using a \l Q_GADGET or + \l Q_OBJECT macro. + + This is useful for registering types that cannot be amended to add the macros, + for example because they belong to 3rdparty libraries. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT() +*/ + +/*! + \macro QML_UNAVAILABLE + \relates QQmlEngine + + This macro declares the enclosing type to be unavailable in QML. It registers + an internal dummy type called \c QQmlTypeNotAvailable as \l QML_FOREIGN() + type, using any further QML macros you specify. + + Normally, the types exported by a module should be fixed. However, if a C++ + type is not available, you should at least "reserve" the QML type name, and + give the user of the unavailable type a meaningful error message. + + Example: + + \code + #ifdef NO_GAMES_ALLOWED + struct MinehuntGame + { + Q_GADGET + QML_NAMED_ELEMENT(Game) + QML_UNAVAILABLE + QML_UNCREATABLE("Get back to work, slacker!"); + }; + #else + class MinehuntGame : public QObject + { + Q_OBJECT + QML_NAMED_ELEMENT(Game) + // ... + }; + #endif + \endcode + + This will cause any QML which attempts to use the "Game" type to produce an + error message: + + \badcode + fun.qml: Get back to work, slacker! + Game { + ^ + \endcode + + Using this technique, you only need a \l Q_GADGET struct to customize the error + message, not a full-blown \l QObject. Without \l QML_UNCREATABLE(), + \l QML_UNAVAILABLE still results in a more specific error message than the usual + "is not a type" for completely unknown types. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_FOREIGN() +*/ + +/*! \macro QML_DECLARE_TYPE() \relates QQmlEngine @@ -41,7 +309,8 @@ Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which declares that the \a Type supports \l {Attached Properties and Attached Signal Handlers} - {attached properties}. + {attached properties}. QML_DECLARE_TYPEINFO() is not necessary if \a Type contains the + QML_ATTACHED macro. */ /*! @@ -106,7 +375,8 @@ QML written to previous versions to continue to work, even if more advanced versions of some of its types are available. - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), + {Choosing the Correct Integration Method Between C++ and QML} */ /*! @@ -143,7 +413,7 @@ Returns the QML type id. - \sa qmlRegisterTypeNotAvailable(), + \sa QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(), {Choosing the Correct Integration Method Between C++ and QML} */ @@ -158,7 +428,7 @@ Returns the QML type id. - \sa qmlRegisterType(), {Registering Extension Objects} + \sa QML_EXTENDED(), qmlRegisterType(), {Registering Extension Objects} */ @@ -180,7 +450,7 @@ Returns the QML type id. - \sa qmlRegisterUncreatableType() + \sa QML_EXTENDED(), QML_UNCREATABLE(), qmlRegisterUncreatableType() */ /*! @@ -220,6 +490,8 @@ \code Component.onCompleted: console.log(MyNamespace.Key2) \endcode + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE() */ /*! @@ -235,6 +507,8 @@ the \a parser provided. Returns the QML type id. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED() */ /*! @@ -269,7 +543,7 @@ Without this, a generic "Game is not a type" message would be given. - \sa qmlRegisterUncreatableType(), + \sa QML_UNAVAILABLE, qmlRegisterUncreatableType(), {Choosing the Correct Integration Method Between C++ and QML} */ @@ -353,7 +627,7 @@ Returns the QML type id. \since 5.14 - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_ANONYMOUS, {Choosing the Correct Integration Method Between C++ and QML} */ /*! @@ -397,6 +671,8 @@ the interface cast to \c FooInterface* automatically. Returns the QML type id. + + \sa QML_INTERFACE */ /*! @@ -455,7 +731,7 @@ } \endqml - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML} */ /*! @@ -477,8 +753,7 @@ Returns 0 if type \e T is not a valid attaching type, or if \a create is false and no attachment object instance has previously been created for \a attachee. - \sa {Providing Attached Properties} - + \sa QML_ATTACHED(), {Providing Attached Properties} */ /*! @@ -571,7 +846,7 @@ } \endqml - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML} */ @@ -626,10 +901,12 @@ That can be done by adding a pragma Singleton statement among the imports of the type's QML file. In addition the type must be defined in a qmldir file with a singleton keyword and the qmldir must be imported by the QML files using the singleton. + + \sa QML_SINGLETON */ /*! - \fn int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject* cppObject) + \fn template<typename T> auto qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, T *cppObject) \relates QQmlEngine \since 5.14 @@ -718,7 +995,7 @@ } \endqml - \sa qmlRegisterSingletonType + \sa QML_SINGLETON, qmlRegisterSingletonType */ /*! @@ -792,5 +1069,5 @@ Returns -1 if no matching type was found or one of the given parameters was invalid. - \sa qmlRegisterType(), qmlRegisterSingletonType() + \sa QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), qmlRegisterSingletonType() */ diff --git a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc index 2de4eb0c18..a4119ff793 100644 --- a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc @@ -29,25 +29,37 @@ \title Defining Object Types through QML Documents \brief Description of how a QML document is a reusable type definition -One of the core features of QML is that it enables QML object types to be easily defined in a lightweight manner through QML documents to suit the needs of individual QML applications. The standard \l {Qt Quick} module provides various types like \l Rectangle, \l Text and \l Image for building a QML application; beyond these, you can easily define your own QML types to be reused within your application. This ability to create your own types forms the building blocks of any QML application. +One of the core features of QML is that it enables QML object types to be +easily defined in a lightweight manner through QML documents to suit the needs +of individual QML applications. The standard \l {Qt Quick} module provides +various types like \l Rectangle, \l Text and \l Image for building a QML +application; beyond these, you can easily define your own QML types to be +reused within your application. This ability to create your own types forms the +building blocks of any QML application. \section1 Defining an Object Type with a QML File \section2 Naming Custom QML Object Types -To create an object type, a QML document should be placed into a text file named as \e <TypeName>.qml where \e <TypeName> is the desired name of the type. The type name has the following requirements: +To create an object type, a QML document should be placed into a text file +named as \e <TypeName>.qml where \e <TypeName> is the desired name of the type. +The type name has the following requirements: \list \li It must be comprised of alphanumeric characters or underscores. \li It must begin with an uppercase letter. \endlist -This document is then automatically recognized by the engine as a definition of a QML type. Additionally, a type defined in this manner is automatically made available to other QML files within the same directory as the engine searches within the immediate directory when resolving QML type names. +This document is then automatically recognized by the engine as a definition of +a QML type. Additionally, a type defined in this manner is automatically made +available to other QML files within the same directory as the engine searches +within the immediate directory when resolving QML type names. \section2 Custom QML Type Definition -For example, below is a document that declares a \l Rectangle with a child \l MouseArea. The document has been saved to file named \c SquareButton.qml: +For example, below is a document that declares a \l Rectangle with a child \l +MouseArea. The document has been saved to file named \c SquareButton.qml: \qml // SquareButton.qml @@ -65,7 +77,10 @@ Rectangle { } \endqml -Since the file is named \c SquareButton.qml, \b {this can now be used as a type named \c SquareButton by any other QML file within the same directory}. For example, if there was a \c myapplication.qml file in the same directory, it could refer to the \c SquareButton type: +Since the file is named \c SquareButton.qml, \b {this can now be used as a type +named \c SquareButton by any other QML file within the same directory}. For +example, if there was a \c myapplication.qml file in the same directory, it +could refer to the \c SquareButton type: \qml // myapplication.qml @@ -76,23 +91,80 @@ SquareButton {} \image documents-definetypes-simple.png -This creates a 100 x 100 red \l Rectangle with an inner \l MouseArea, as defined in \c SquareButton.qml. When this \c myapplication.qml document is loaded by the engine, it loads the SquareButton.qml document as a component and instantiates it to create a \c SquareButton object. +This creates a 100 x 100 red \l Rectangle with an inner \l MouseArea, as +defined in \c SquareButton.qml. When this \c myapplication.qml document is +loaded by the engine, it loads the SquareButton.qml document as a component and +instantiates it to create a \c SquareButton object. + +The \c SquareButton type encapsulates the tree of QML objects declared in \c +SquareButton.qml. When the QML engine instantiates a \c SquareButton object +from this type, it is instantiating an object from the \l Rectangle tree +declared in \c SquareButton.qml. + +\note the letter case of the file name is significant on some (notably UNIX) +filesystems. It is recommended the file name case matches the case of the +desired QML type name exactly - for example, \c Box.qml and not \c BoX.qml - +regardless of the platform to which the QML type will be deployed. + +\section2 Inline Components + +Sometimes, it can be inconvenient to create a new file for a type, for +instance when reusing a small delegate in multiple views. If you don't actually +need to expose the type, but only need to create an instance, +\l{QtQml::Component}{Component} is an option. +But if you want to declare properties with the component types, or if you +want to use it in multiple files, \c Component is not an option. In that case, +you can use \e {inline components}. Inline components declare a new component +inside of a file. The syntax for that is +\code +component <component name> : BaseType { + // declare properties and bindings here +} +\endcode + +Inside the file which declares the inline component, the type can be referenced +simply by its name. + +\snippet qml/qml-documents/Images.qml document + +In other files, it has to be prefixed with the name of its containing component. + +\snippet qml/qml-documents/LabeledImageBox.qml document + +\note Inline components don't share their scope with the component they are +declared in. In the following example, when \c A.MyInlineComponent in file +B.qml gets created, a ReferenceError will occur, as \c root does not exist as +an id in B.qml. +It is therefore advisable not to reference objects in an inline component +which are not part of it. -The \c SquareButton type encapsulates the tree of QML objects declared in \c SquareButton.qml. When the QML engine instantiates a \c SquareButton object from this type, it is instantiating an object from the \l Rectangle tree declared in \c SquareButton.qml. +\snippet qml/qml-documents/A.qml document +\snippet qml/qml-documents/B.qml document -\note the letter case of the file name is significant on some (notably UNIX) filesystems. It is recommended the file name case matches the case of the desired QML type name exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the QML type will be deployed. +\note Inline components cannot be nested. \section2 Importing Types Defined Outside the Current Directory If \c SquareButton.qml was not in the same directory as \c myapplication.qml, -the \c SquareButton type would need to be specifically made available through an \e import statement in \c myapplication.qml. It could be imported from a relative path on the file system, or as an installed module; see \l {QML Modules}{module} for more details. +the \c SquareButton type would need to be specifically made available through +an \e import statement in \c myapplication.qml. It could be imported from a +relative path on the file system, or as an installed module; see \l {QML +Modules}{module} for more details. \section1 Accessible Attributes of Custom Types -The \b {root object} definition in a .qml file \b {defines the attributes that are available for a QML type}. All properties, signals and methods that belong to this root object - whether they are custom declared, or come from the QML type of the root object - are externally accessible and can be read and modified for objects of this type. +The \b {root object} definition in a .qml file \b {defines the attributes that +are available for a QML type}. All properties, signals and methods that belong +to this root object - whether they are custom declared, or come from the QML +type of the root object - are externally accessible and can be read and +modified for objects of this type. -For example, the root object type in the \c SquareButton.qml file above is \l Rectangle. This means any properties defined by the \l Rectangle type can be modified for a \c SquareButton object. The code below defines three \c SquareButton objects with customized values for some of the properties of the root \l Rectangle object of the \c SquareButton type: +For example, the root object type in the \c SquareButton.qml file above is \l +Rectangle. This means any properties defined by the \l Rectangle type can be +modified for a \c SquareButton object. The code below defines three \c +SquareButton objects with customized values for some of the properties of the +root \l Rectangle object of the \c SquareButton type: \qml // application.qml @@ -107,7 +179,12 @@ Column { \image documents-definetypes-attributes.png -The attributes that are accessible to objects of the custom QML type include any \l{Defining Property Attributes}{custom properties}, \l{Defining Method Attributes}{methods} and \l{Defining Signal Attributes}{signals} that have additionally been defined for an object. For example, suppose the \l Rectangle in \c SquareButton.qml had been defined as follows, with additional properties, methods and signals: +The attributes that are accessible to objects of the custom QML type include +any \l{Defining Property Attributes}{custom properties}, \l{Defining Method +Attributes}{methods} and \l{Defining Signal Attributes}{signals} that have +additionally been defined for an object. For example, suppose the \l Rectangle +in \c SquareButton.qml had been defined as follows, with additional properties, +methods and signals: \qml // SquareButton.qml @@ -136,7 +213,9 @@ Rectangle { } \endqml -Any \c SquareButton object could make use of the \c pressed property, \c buttonClicked signal and \c randomizeColor() method that have been added to the root \l Rectangle: +Any \c SquareButton object could make use of the \c pressed property, \c +buttonClicked signal and \c randomizeColor() method that have been added to the +root \l Rectangle: \qml // application.qml @@ -154,7 +233,14 @@ SquareButton { } \endqml -Note that any of the \c id values defined in \c SquareButton.qml are not accessible to \c SquareButton objects, as id values are only accessible from within the component scope in which a component is declared. The \c SquareButton object definition above cannot refer to \c mouseArea in order to refer to the \l MouseArea child, and if it had an \c id of \c root rather than \c squareButton, this would not conflict with the \c id of the same value for the root object defined in \c SquareButton.qml as the two would be declared within separate scopes. +Note that any of the \c id values defined in \c SquareButton.qml are not +accessible to \c SquareButton objects, as id values are only accessible from +within the component scope in which a component is declared. The \c +SquareButton object definition above cannot refer to \c mouseArea in order to +refer to the \l MouseArea child, and if it had an \c id of \c root rather than +\c squareButton, this would not conflict with the \c id of the same value for +the root object defined in \c SquareButton.qml as the two would be declared +within separate scopes. */ diff --git a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc index f7d71030b5..99c7fa5621 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc @@ -422,7 +422,7 @@ import QtQuick.tooling 1.1 // Component objects. Module { // A Component object directly corresponds to a type exported - // in a plugin with a call to qmlRegisterType. + // using the QML_ELEMENT or QML_NAMED_ELEMENT macros. Component { // The name is a unique identifier used to refer to this type. @@ -440,25 +440,34 @@ Module { attachedType: "QQuickAnimationAttached" // The list of exports determines how a type can be imported. - // Each string has the format "URI/Name version" and matches the - // arguments to qmlRegisterType. Usually types are only exported - // once, if at all. - // If the "URI/" part of the string is missing that means the - // type should be put into the package defined by the URI the - // module was imported with. - // For example if this module was imported with 'import Foo 4.8' - // the Animation object would be found in the package Foo and - // QtQuick. + // Each string has the format "URI/Name version". The URI is + // the import name given via the build system, for example as + // QML_IMPORT_NAME in qmake. The name is either the C++ class + // name or, in case of QML_NAMED_ELEMENT(), an explicitly given + // name. The version is constructed from the major version + // given via the build system, as QML_IMPORT_MAJOR_VERSION in + // qmake, and any revisions given in the class or its base + // classes by Q_REVISION(), the REVISION argument to Q_PROPERTY, + // or QML_ADDED_IN_MINOR_VERSION(). Usually types are only + // exported once, if at all. The following tells us that there + // are two variants of Animation, and that 'import QtQuick 2.0' + // will expose a different revision than imports of later + // versions. exports: [ - "Animation 4.7", - "QtQuick/Animation 1.0" + "QtQuick/Animation 2.0", + "QtQuick/Animation 2.1" ] // The meta object revisions for the exports specified in 'exports'. - // Describes with revisioned properties will be visible in an export. - // The list must have exactly the same length as the 'exports' list. - // For example the 'animations' propery described below will only be - // available through the QtQuick/Animation 1.0 export. + // Each meta object revision may add additional properties or methods, + // relative to the previous one. Those will only be visible when the + // module is imported with at least the corresponding version as + // specified in the 'exports' list. + // The exportMetaObjectRevisions list must have exactly the same + // length as the 'exports' list. For example, the 'animations' property + // described below will only be available through the QtQuick/Animation + // 2.1 export. Usually the revisions will match the versions in the + // 'exports' list. exportMetaObjectRevisions: [0, 1] Property { @@ -486,7 +495,7 @@ Module { // declarations also support the isReadonly, isPointer and isList // attributes which mean the same as for Property Method { name: "restart" } - Signal { name: "started"; revision: 2 } + Signal { name: "started"; revision: 1 } Signal { name: "runningChanged" Parameter { type: "bool" } diff --git a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc index 05447db627..496245820a 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc +++ b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc @@ -1,19 +1,22 @@ -QQmlExtensionPlugin is a plugin interface that makes it possible to +\l QQmlEngineExtensionPlugin is a plugin interface that makes it possible to create QML extensions that can be loaded dynamically into QML applications. These extensions allow custom QML types to be made available to the QML engine. To write a QML extension plugin: \list 1 -\li Subclass QQmlExtensionPlugin +\li Subclass \l QQmlEngineExtensionPlugin and use the Q_PLUGIN_METADATA() macro + to register the plugin with the Qt meta object system. +\li Use the \l QML_ELEMENT and \l QML_NAMED_ELEMENT() macros to declare + QML types. +\li Write a project file for the plugin. Add: \list - \li Use the Q_PLUGIN_METADATA() macro to register the plugin with - the Qt meta object system - \li Override the \l{QQmlExtensionPlugin::}{registerTypes()} method - and call qmlRegisterType() to register the types to be exported - by the plugin + \li \c {CONFIG += qmltypes} to instruct the build system to generate + QML types. + \li \c {QML_IMPORT_NAME = <my.import.name>} to specify the import name. + \li \c {QML_IMPORT_MAJOR_VERSION = <version>} to specify the import + major version. \endlist -\li Write a project file for the plugin \li Create a \l{Module Definition qmldir Files}{qmldir file} to describe the plugin \endlist @@ -27,26 +30,18 @@ issues in the library user's code. Suppose there is a new \c TimeModel C++ class that should be made available as a new QML type. It provides the current time through \c hour and \c minute -properties. +properties. It declares a QML type called \c Time via \l QML_NAMED_ELEMENT(). \snippet qmlextensionplugins/timemodel.h 0 \dots To make this type available, we create a plugin class named \c QExampleQmlPlugin -which is a subclass of \l QQmlExtensionPlugin. It overrides the -\l{QQmlExtensionPlugin::}{registerTypes()} method in order to register the \c TimeModel -type using qmlRegisterType(). It also uses the Q_PLUGIN_METADATA() macro in the class -definition to register the plugin with the Qt meta object system using a unique -identifier for the plugin. +which is a subclass of \l QQmlEngineExtensionPlugin. It uses the +Q_PLUGIN_METADATA() macro in the class definition to register the plugin with the +Qt meta object system using a unique identifier for the plugin. \snippet qmlextensionplugins/plugin.cpp plugin -This registers the \c TimeModel class with version \c{1.0} of this plugin library, as -a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is -imported correctly by any QML components that use this plugin. The -\l{Defining QML Types from C++} article has more information about registering C++ -types into the runtime. - \section1 Project settings for the plugin Additionally, the project file (\c .pro) defines the project as a plugin library, @@ -55,14 +50,22 @@ the plugin target name and various other details: \code TEMPLATE = lib -CONFIG += qt plugin +CONFIG += qt plugin qmltypes QT += qml -DESTDIR = imports/TimeExample -TARGET = qmlqtimeexampleplugin +QML_IMPORT_NAME = TimeExample +QML_IMPORT_MAJOR_VERSION = 1 + +DESTDIR = imports/$$QML_IMPORT_NAME +TARGET = qmlqtimeexampleplugin + SOURCES += qexampleqmlplugin.cpp \endcode +This registers the \c TimeModel class with the import \c{TimeExample 1.0}, as +a QML type called \c Time. The \l{Defining QML Types from C++} article has more +information about registering C++ types for usage in QML. + \section1 Plugin definition in the qmldir Finally, a \l{Module Definition qmldir Files}{qmldir file} is required diff --git a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc index 32106d5bb8..fdba452271 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc @@ -127,15 +127,15 @@ Rectangle { In this case, the engine will emit an error and refuse to load the file. -\section4 Non-module Namespace Imports +\section4 C++ Module Imports -Types can also be registered into namespaces directly via the various -registration functions in C++ (such as qmlRegisterType()). The types which -have been registered into a namespace in this way may be imported by importing -the namespace, as if the namespace was a module identifier. +Usually, C++ types are declared using the QML_ELEMENT and QML_NAMED_ELEMENT() +macros and registered via the build system using QML_IMPORT_NAME and +QML_IMPORT_MAJOR_VERSION. The import name and version given this way form a +module that can be imported to access the types. This is most common in client applications which define their own QML object -types in C++ and register them with the QML type system manually. +types in C++. \section4 Importing into a Qualified Local Namespace diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc index 401e099ebf..ecfef2e04f 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc @@ -112,7 +112,7 @@ Alternatively, a custom property of an object type may be defined in an object declaration in a QML document with the following syntax: \code - [default] property <propertyType> <propertyName> + [default] [required] [readonly] property <propertyType> <propertyName> \endcode In this way an object declaration may \l {Defining Object Types from QML} @@ -121,10 +121,13 @@ state more easily. Property names must begin with a lower case letter and can only contain letters, numbers and underscores. \l {JavaScript Reserved Words} -{JavaScript reserved words} are not valid property names. The \c default -keyword is optional, and modifies the semantics of the property being declared. -See the upcoming section on \l {Default Properties}{default properties} for -more information about the \c default property modifier. +{JavaScript reserved words} are not valid property names. The \c default, +\c required, and \c readonly keywords are optional, and modify the semantics +of the property being declared. +See the upcoming sections on \l {Default Properties}{default properties}, +\l {Required Properties}{required properties} and, +\l {Read-Only Properties}{read-only properties} for more information +about their respective meaning. Declaring a custom property implicitly creates a value-change \l{Signal attributes}{signal} for that property, as well as an associated @@ -647,6 +650,45 @@ the \l{TabWidget Example}, which uses a default property to automatically reassign children of the TabWidget as children of an inner ListView. See also \l {Extending QML}. +\section3 Required Properties + +An object declaration may define a property as required, using the \c required +keyword. The syntax is +\code + required property <propertyType> <propertyName> +\endcode + +As the name suggests, required properties must be set when an instance of the object +is created. Violation of this rule will result in QML applications not starting if it can be +detected statically. In case of dynamically instantiated QML components (for instance via +\l {QtQml::Qt::createComponent()}{Qt.createComponent()}), violating this rule results in a +warning and a null return value. + +It's possible to make an existing property required with +\code + required <propertyName> +\endcode +The following example shows how to create a custom Rectangle component, in which the color +property always needs to be specified. +\qml +// ColorRectangle.qml +Rectangle { + required color +} +\endqml + +\note You can't assign an initial value to a required property from QML, as that would go +directly against the intended usage of required properties. + +Required properties play a special role in model-view-delegate code: +If the delegate of a view has required properties whose names match with +the role names of the view's model, then those properties will be initialized +with the model's corresponding values. +For more information, visit the \l{Models and Views in Qt Quick} page. + +\sa {QQmlComponent::createWithInitialProperties}, {QQmlApplicationEngine::setInitialProperties} +and {QQuickView::setInitialProperties} for ways to initialize required properties from C++. + \section3 Read-Only Properties An object declaration may define a read-only property using the \c readonly diff --git a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc index 5144fe219e..53984a440d 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc @@ -582,34 +582,15 @@ property is only invoked when the property is reassigned to a different object v QML objects (and certainly not JavaScript object either) and the key-value pairs in \c attributes are \e not QML properties. Rather, the \c items property holds an array of values, and \c attributes holds a set of key-value - pairs. Since they are stored as a set of values, instead of as an object, - their contents \e cannot be modified individually: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - items[0] = 10 - console.log(items[0]) // This will still be '1'! - attributes.color = 'blue' - console.log(attributes.color) // This will still be 'red'! - } - } - \endqml - - Since it is not possible to individually add or remove items from a list or - object stored in a \c variant, the only way to modify its contents is to - reassign a new value. However, this is not efficient, as it causes the value - to be serialized and deserialized. + pairs. Additionally, since \c items and \c attributes are not QML objects, changing - their individual values do not trigger property change notifications. If - the above example had \c onNumberChanged or \c onAnimalChanged signal - handlers, they would not have been called. If, however, the \c items or - \c attributes properties themselves were reassigned to different values, then - such handlers would be called. + the values they contain does not trigger property change notifications. If + the above example had \c onItemsChanged or \c onAttributesChanged signal + handlers, they would not be called when assigning individual entries in + either property. If, however, the \c items or \c attributes properties + themselves were reassigned to different values, then such handlers would be + called. JavaScript programmers should also note that when a JavaScript object is copied to an array or map property, the \e contents of the object (that is, |