diff options
Diffstat (limited to 'src/qml/doc')
45 files changed, 2103 insertions, 466 deletions
diff --git a/src/qml/doc/qtqml.qdocconf b/src/qml/doc/qtqml.qdocconf index b2f2c0cb77..820e7c67d2 100644 --- a/src/qml/doc/qtqml.qdocconf +++ b/src/qml/doc/qtqml.qdocconf @@ -65,5 +65,3 @@ manifestmeta.thumbnail.names += "QtQml/Chapter 4*" \ navigation.landingpage = "Qt QML" navigation.cppclassespage = "Qt QML C++ Classes" navigation.qmltypespage = "Qt QML QML Types" - -macro.versionlessNote = "If \\l{Versionless commands}{versionless commands} are disabled, use \\c{\1} instead. It supports the same set of arguments as this command." diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/CMakeLists.txt b/src/qml/doc/snippets/cmake/qt_target_qml_sources/CMakeLists.txt new file mode 100644 index 0000000000..d33f009e38 --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/CMakeLists.txt @@ -0,0 +1,43 @@ +cmake_minimum_required(VERSION 3.19) +project(qt_target_qml_sources_snippet) + +set(CMAKE_AUTOMOC TRUE) +set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}) + +# ![0] +set_source_files_properties(nested/way/down/File.qml PROPERTIES + QT_RESOURCE_ALIAS File.qml +) +set_source_files_properties(TemplateFile.qml PROPERTIES + QT_RESOURCE_ALIAS templates/File.qml + QT_QML_SKIP_QMLDIR_ENTRY TRUE + QT_QML_SKIP_QMLLINT TRUE + QT_QML_SKIP_CACHEGEN TRUE +) +set_source_files_properties(FunnySingleton.qml PROPERTIES + QT_QML_SINGLETON_TYPE TRUE +) +qt_add_qml_module(qt_target_qml_sources_example + URI Example + VERSION 2.3 + RESOURCE_PREFIX /my.company.com/imports + QML_FILES + nested/way/down/File.qml + TemplateFile.qml + FunnySingleton.qml +) + +set_source_files_properties(some_old_thing.qml PROPERTIES + QT_QML_SOURCE_VERSIONS "1.1;2.0" + QT_QML_SOURCE_TYPENAME OldThing +) +set_source_files_properties(../../../images/button-types.png PROPERTIES + QT_RESOURCE_ALIAS button-types.png +) +qt_target_qml_sources(qt_target_qml_sources_example + QML_FILES some_old_thing.qml + RESOURCES + ../../../images/button-types.png + doc/README.txt +) +# ![0] diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/FunnySingleton.qml b/src/qml/doc/snippets/cmake/qt_target_qml_sources/FunnySingleton.qml new file mode 100644 index 0000000000..4aec01c32d --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/FunnySingleton.qml @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** Copyright (C) 2021 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$ +** +****************************************************************************/ + +//! [0] +pragma Singleton +import QtQml + +QtObject {} +//! [0] diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/TemplateFile.qml b/src/qml/doc/snippets/cmake/qt_target_qml_sources/TemplateFile.qml new file mode 100644 index 0000000000..8fc36a40da --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/TemplateFile.qml @@ -0,0 +1,3 @@ +import QtQml + +QtObject {} diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/doc/README.txt b/src/qml/doc/snippets/cmake/qt_target_qml_sources/doc/README.txt new file mode 100644 index 0000000000..52d51e034d --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/doc/README.txt @@ -0,0 +1 @@ +Dummy file, contents not important. diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/nested/way/down/File.qml b/src/qml/doc/snippets/cmake/qt_target_qml_sources/nested/way/down/File.qml new file mode 100644 index 0000000000..8fc36a40da --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/nested/way/down/File.qml @@ -0,0 +1,3 @@ +import QtQml + +QtObject {} diff --git a/src/qml/doc/snippets/cmake/qt_target_qml_sources/some_old_thing.qml b/src/qml/doc/snippets/cmake/qt_target_qml_sources/some_old_thing.qml new file mode 100644 index 0000000000..8fc36a40da --- /dev/null +++ b/src/qml/doc/snippets/cmake/qt_target_qml_sources/some_old_thing.qml @@ -0,0 +1,3 @@ +import QtQml + +QtObject {} diff --git a/src/qml/doc/snippets/code/doc_src_qtqml.cmake b/src/qml/doc/snippets/code/doc_src_qtqml.cmake index c2e5d3d9d2..c312201ff8 100644 --- a/src/qml/doc/snippets/code/doc_src_qtqml.cmake +++ b/src/qml/doc/snippets/code/doc_src_qtqml.cmake @@ -1,4 +1,4 @@ #! [0] -find_package(Qt6 COMPONENTS Qml REQUIRED) +find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) #! [0] diff --git a/src/qml/doc/snippets/qml/CMakeLists.txt b/src/qml/doc/snippets/qml/CMakeLists.txt new file mode 100644 index 0000000000..24e775341f --- /dev/null +++ b/src/qml/doc/snippets/qml/CMakeLists.txt @@ -0,0 +1,11 @@ +qt_add_library(extra_module STATIC) +qt_add_qml_module(extra_module + URI "ExtraModule" + VERSION 1.0 + QML_FILES + Extra.qml + SOURCES + extrathing.cpp extrathing.h +) + +add_subdirectory(ExtraModule) diff --git a/src/qml/doc/snippets/qml/MajorProject-CMakeLists.txt b/src/qml/doc/snippets/qml/MajorProject-CMakeLists.txt new file mode 100644 index 0000000000..3e5cbd4565 --- /dev/null +++ b/src/qml/doc/snippets/qml/MajorProject-CMakeLists.txt @@ -0,0 +1,23 @@ + +set_source_files_properties(Thing.qml + PROPERTIES + QT_QML_SOURCE_VERSIONS "1.4;2.0;3.0" +) + +set_source_files_properties(OtherThing.qml + PROPERTIES + QT_QML_SOURCE_VERSIONS "2.2;3.0" +) + +qt_add_qml_module(my_module + URI MyModule + VERSION 3.2 + PAST_MAJOR_VERSIONS + 1 2 + QML_FILES + Thing.qml + OtherThing.qml + OneMoreThing.qml + SOURCES + everything.cpp everything.h +) diff --git a/src/qml/doc/snippets/qml/createQmlObject.qml b/src/qml/doc/snippets/qml/createQmlObject.qml index 8a082a71de..bfb1d98ca8 100644 --- a/src/qml/doc/snippets/qml/createQmlObject.qml +++ b/src/qml/doc/snippets/qml/createQmlObject.qml @@ -58,9 +58,18 @@ Rectangle { function createIt() { //![0] -var newObject = Qt.createQmlObject('import QtQuick 2.0; Rectangle {color: "red"; width: 20; height: 20}', - parentItem, - "dynamicSnippet1"); +const newObject = Qt.createQmlObject(` + import QtQuick 2.0 + + Rectangle { + color: "red" + width: 20 + height: 20 + } + `, + parentItem, + "myDynamicSnippet" +); //![0] //![destroy] diff --git a/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs b/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs index 86c3e078c8..1326b8c87a 100644 --- a/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs +++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs @@ -50,8 +50,9 @@ //![0] // script.mjs import { factorial } from "factorial.mjs" +export { factorial } -function showCalculations(value) { +export function showCalculations(value) { console.log( "Call factorial() from script.js:", factorial(value)); diff --git a/src/qml/doc/snippets/qml/myProject-CMakeLists.txt b/src/qml/doc/snippets/qml/myProject-CMakeLists.txt new file mode 100644 index 0000000000..49c63a1513 --- /dev/null +++ b/src/qml/doc/snippets/qml/myProject-CMakeLists.txt @@ -0,0 +1,13 @@ +qt_add_executable(main_program main.cpp) + +qt_add_qml_module(main_program + VERSION 1.0 + URI myProject + QML_FILES + main.qml + SOURCES + onething.cpp onething.h + +) + +target_link_libraries(main_program PRIVATE extra_moduleplugin) diff --git a/src/qml/doc/snippets/qml/myimageprovider.txt b/src/qml/doc/snippets/qml/myimageprovider.txt new file mode 100644 index 0000000000..4605734398 --- /dev/null +++ b/src/qml/doc/snippets/qml/myimageprovider.txt @@ -0,0 +1,15 @@ +qt_add_qml_module(imageproviderplugin + VERSION 1.0 + URI "ImageProvider" + PLUGIN_TARGET imageproviderplugin + NO_PLUGIN_OPTIONAL + NO_GENERATE_PLUGIN_SOURCE + CLASS_NAME ImageProviderExtensionPlugin + QML_FILES + AAA.qml + BBB.qml + SOURCES + moretypes.cpp moretypes.h + myimageprovider.cpp myimageprovider.h + plugin.cpp +) diff --git a/src/qml/doc/snippets/qml/plugin.cpp.txt b/src/qml/doc/snippets/qml/plugin.cpp.txt new file mode 100644 index 0000000000..02d1112a4a --- /dev/null +++ b/src/qml/doc/snippets/qml/plugin.cpp.txt @@ -0,0 +1,14 @@ +#include <myimageprovider.h> +#include <QtQml/qqmlextensionplugin.h> + +class ImageProviderExtensionPlugin : public QQmlEngineExtensionPlugin +{ + Q_OBJECT + Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid) +public: + void initializeEngine(QQmlEngine *engine, const char *uri) final + { + Q_UNUSED(uri); + engine->addImageProvider("myimg", new MyImageProvider); + } +}; diff --git a/src/qml/doc/snippets/qtjavascript/integratingjswithcpp/exampleqjsascontainer.cpp b/src/qml/doc/snippets/qtjavascript/integratingjswithcpp/exampleqjsascontainer.cpp new file mode 100644 index 0000000000..0064d66a5c --- /dev/null +++ b/src/qml/doc/snippets/qtjavascript/integratingjswithcpp/exampleqjsascontainer.cpp @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2022 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$ +** +****************************************************************************/ + + +//! [qjs-as-container] + + class Cache : public QObject + { + Q_OBJECT + QML_ELEMENT + + public: + Q_INVOKABLE QJSValue lookup(const QString &key) { + if (auto it = m_cache.constFind(key); it != m_cache.constEnd()) { + return *it; // impicit conversion + } else { + return QJSValue::UndefinedValue; // implicit conversion + } + } + + QHash<QString, QString> m_cache; + } + +//! [qjs-as-container] diff --git a/src/qml/doc/snippets/qtjavascript/integratingjswithcpp/exampleqjsengine.cpp b/src/qml/doc/snippets/qtjavascript/integratingjswithcpp/exampleqjsengine.cpp new file mode 100644 index 0000000000..59ee30c25f --- /dev/null +++ b/src/qml/doc/snippets/qtjavascript/integratingjswithcpp/exampleqjsengine.cpp @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** Copyright (C) 2022 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$ +** +****************************************************************************/ + +//![qjs-engine-example] + + QJSEngine engine; + // We create an object with a read-only property whose getter throws an exception + auto val = engine.evaluate("let o = { get f() {throw 42;} }; o"); + val.property("f"); + qDebug() << engine.hasError(); // prints false + + // This time, we construct a QJSManagedValue before accessing the property + val = engine.evaluate("let o = { get f() {throw 42;} }; o"); + QJSManagedValue managed(std::move(val), &engine); + managed.property("f"); + qDebug() << engine.hasError(); // prints true + + QJSValue error = engine.catchError(); + Q_ASSERT(error.toInt(), 42); + +//![qjs-engine-example] diff --git a/src/qml/doc/snippets/qtjavascript/integratingjswithcpp/qjsengine.cpp b/src/qml/doc/snippets/qtjavascript/integratingjswithcpp/qjsengine.cpp new file mode 100644 index 0000000000..e8622b2c50 --- /dev/null +++ b/src/qml/doc/snippets/qtjavascript/integratingjswithcpp/qjsengine.cpp @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2022 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$ +** +****************************************************************************/ + +//![qjs-engine] + + QJSEngine engine; + QJSValue object = engine.newObject(); + object.setProperty("num", 42); + QJSValue function = engine.evaluate("(o) => o.num *= 2 "); + QJSValueList args = { object }; + QJSValue result = function.call(args); + QJSValue expected = "84"; + Q_ASSERT(result.equals(expected) && !result.strictlyEquals(expected)); + +//![qjs-engine] + diff --git a/src/qml/doc/src/cmake/cmake-properties.qdoc b/src/qml/doc/src/cmake/cmake-properties.qdoc new file mode 100644 index 0000000000..eccc815eca --- /dev/null +++ b/src/qml/doc/src/cmake/cmake-properties.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** Copyright (C) 2022 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$ +** +****************************************************************************/ + +/*! +\group cmake-source-file-properties-qtqml +\title CMake Source File Properties in Qt6 Qml + +\l{CMake Commands in Qt6 Qml}{CMake Commands} know about the following CMake +source file properties: + +\sa{CMake Property Reference} +*/ + + +/*! +\page cmake-source-file-property-QT_QML_INTERNAL_TYPE.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_INTERNAL_TYPE +\target cmake-source-file-property-QT_QML_INTERNAL_TYPE + +\summary {Marks a QML file as providing an internal type.} + +\cmakepropertysince 6.2 + +Set this property to \c TRUE to indicate that the \c{.qml} file provides an internal type. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-QT_QML_SINGLETON_TYPE.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SINGLETON_TYPE +\target cmake-source-file-property-QT_QML_SINGLETON_TYPE + +\summary {Marks a QML file as providing a singleton type.} + +\cmakepropertysince 6.2 + +A \c{.qml} file that provides a singleton type needs to have its \c QT_QML_SINGLETON_TYPE source +property set to \c TRUE to ensure that the singleton command is written into the +\l{Module Definition qmldir Files}{qmldir} file. +This must be done in addition to the QML file containing the \c {pragma Singleton} statement. + +See \l{qt_target_qml_sources_example}{qt_target_qml_sources()} for an example on +how to set the \c QT_QML_SINGLETON_TYPE property. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-QT_QML_SKIP_CACHEGEN.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SKIP_CACHEGEN +\target cmake-source-file-property-QT_QML_SKIP_CACHEGEN + +\summary {Excludes a file from being compiled to byte code.} + +\cmakepropertysince 6.2 + +Set this property to \c TRUE to prevent the \c{.qml} file from being compiled to byte code. +The file will still be added to the \c target as a resource in uncompiled form +(see \l{qmlcachegen-auto}{Caching compiled QML sources}). + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-QT_QML_SKIP_QMLDIR_ENTRY.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SKIP_QMLDIR_ENTRY +\target cmake-source-file-property-QT_QML_SKIP_QMLDIR_ENTRY + +\summary {Excludes a file from being added as a type to the QML module's typeinfo file.} + +\cmakepropertysince 6.2 + +Set this property to \c TRUE to prevent +the \c{.qml} file from being added as a type to the QML module's typeinfo file +(see \l{qmldir-autogeneration}{Auto-generating \c{qmldir} and typeinfo files}). + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-QT_QML_SKIP_QMLLINT.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SKIP_QMLLINT +\target cmake-source-file-property-QT_QML_SKIP_QMLLINT + +\summary {Prevents a file from being included in automatic qmllint processing.} + +\cmakepropertysince 6.2 + +Set this property to \c TRUE to prevent the file from being included in +\l{qmllint-auto}{automatic qmllint processing}. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-QT_QML_SOURCE_TYPENAME.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SOURCE_TYPENAME +\target cmake-source-file-property-QT_QML_SOURCE_TYPENAME + +\summary {Overrides the type name provided by the file.} + +\cmakepropertysince 6.2 + +Use this property to override the \c QML type name provided by this file. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-QT_QML_SOURCE_VERSIONS.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SOURCE_VERSIONS +\target cmake-source-file-property-QT_QML_SOURCE_VERSIONS + +\summary {Specifies a custom set of versions for a type.} + +\cmakepropertysince 6.2 + +When the file needs to provide type entries for a custom set of versions, +for example when the QML types were first introduced in a minor patch +version after the \c{.0} release, specify those versions using this property. + +\sa{qml-source-file-properties}{qt_target_qml_sources} +*/ + + +/*! +\page cmake-source-file-property-QT_QMLTC_FILE_BASENAME.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QMLTC_FILE_BASENAME +\target cmake-source-file-property-QT_QMLTC_FILE_BASENAME + +\summary {Specifies a non-default .h and .cpp file name.} + +\cmakepropertysince 6.3 +\preliminarycmakeproperty + +Use this property to specify a non-default \c .h and \c .cpp file name, which helps to resolve +conflicting file names. + +\sa{qt_target_compile_qml_to_cpp} +*/ diff --git a/src/qml/doc/src/cmake/cmake-variables.qdoc b/src/qml/doc/src/cmake/cmake-variables.qdoc index 901ce26e91..8f5b87b1cb 100644 --- a/src/qml/doc/src/cmake/cmake-variables.qdoc +++ b/src/qml/doc/src/cmake/cmake-variables.qdoc @@ -37,18 +37,34 @@ The \l{qt6_add_qml_module}{qt6_add_qml_module()} command accepts an \c OUTPUT_DIRECTORY argument which specifies where the QML module's \c qmldir -file, typeinfo file and plugin library will be created. By default, the current -binary directory (\c CMAKE_CURRENT_BINARY_DIR) is used if that argument is not -provided. When a set of QML modules are being defined, it may be convenient to -have them all generated under a common point in the build directory. If the -source directory structure doesn't match the URI structure of the QML modules, -or if you just want your QML modules to be collected under a different -location, the \c QT_QML_OUTPUT_DIRECTORY can be used. When set, the default -changes to the concatenation of \c QT_QML_OUTPUT_DIRECTORY and the QML module's -\e{target path}, which is based on the module URI. \c QT_QML_OUTPUT_DIRECTORY -will also be added to the import path of the \c qmllint and \c qmlcachegen -tooling targets, allowing them to find other QML modules under the same base -location. +file, typeinfo file and plugin library will be created. When that argument is +not used, the default value is based on the \c QT_QML_OUTPUT_DIRECTORY variable, +if it is set. If \c QT_QML_OUTPUT_DIRECTORY is not set, the default value +depends on the type of backing target (see the +\l{qt6_add_qml_module#OUTPUT_DIRECTORY}{OUTPUT_DIRECTORY} documentation for +details). + +When \c QT_QML_OUTPUT_DIRECTORY is set, the default output directory will be +formed by appending the QML module's \e{target path} (which is based on the +module URI) to \c QT_QML_OUTPUT_DIRECTORY. +The \c QT_QML_OUTPUT_DIRECTORY will also be added to the import path of the +\c qmllint and \c qmlcachegen tooling targets, allowing them to find other QML +modules under the same base location. This allows the project to use a source +directory structure that doesn't exactly match the URI structure of the QML +modules, or to merge sets of QML modules under a common base point. + +When building QML modules for Android, \c QT_QML_OUTPUT_DIRECTORY is set to +\c{${CMAKE_BINARY_DIR}/android-qml} by default. The Android deployment routine +uses this directory to locate the required QML modules in the build tree. +The output directory of a QML module can also be set for a project or for each +QML module target by the user and it can therefore differ from the Android +default directory. In this case, to successfully deploy the executable on +Android, the \e{target path} of the QML module must be based on the module URI. +Also, the \l{cmake-target-property-QT_QML_IMPORT_PATH}{QT_QML_IMPORT_PATH} +property of the executable target must contain the import paths of all QML +modules that are built in the project tree, have a custom output directory, +and are used by the executable target. This behavior will likely change in +a future Qt version due to improvements in the build system implementation. */ diff --git a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc index 4c3655651b..b81a0c80ea 100644 --- a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc +++ b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc @@ -34,6 +34,8 @@ \brief Defines a QML module. +\cmakecommandsince 6.2 + \section1 Synopsis \badcode @@ -54,8 +56,10 @@ qt_add_qml_module( [IMPORT_PATH ...] [SOURCES ...] [QML_FILES ...] + [RESOURCES ...] [OUTPUT_TARGETS out_targets_var] [DESIGNER_SUPPORTED] + [NO_PLUGIN] [NO_PLUGIN_OPTIONAL] [NO_CREATE_PLUGIN_TARGET] [NO_GENERATE_PLUGIN_SOURCE] @@ -63,11 +67,15 @@ qt_add_qml_module( [NO_GENERATE_QMLDIR] [NO_LINT] [NO_CACHEGEN] + [NO_RESOURCE_TARGET_PATH] ) \endcode -\versionlessNote qt6_add_qml_module() +\versionlessCMakeCommandsNote qt6_add_qml_module() + +See \l {Building a QML application} and \l {Building a reusable QML module} +for examples that define QML modules. \section1 Description @@ -90,6 +98,22 @@ first command argument. C++ sources, \c{.qml} files, and resources should all be added to the backing target. The backing target is a library that should be installed in the same location as any other library defined by the project. +The source directory structure under which the backing target is created should +match the target path of the QML module (the target path is the module's URI +with dots replaced by forward slashes). If the source directory structure +doesn't match the target path, \c{qt_add_qml_module()} will issue a warning. + +The following example shows a suitable source directory structure for a QML +module with a URI of \c{MyThings.Panels}. The call to \c{qt_add_qml_module()} +would be in the \c{CMakeLists.txt} file shown. + +\badcode +src + +-- MyThings + +-- Panels + +-- CMakeLists.txt +\endcode + A separate \e plugin target is associated with the QML module. It is used at runtime to load the module dynamically when the application doesn't already link to the backing target. The plugin target will also be a library and is @@ -106,6 +130,10 @@ For cases where the QML module needs a custom plugin class implementation, the \l{NO_GENERATE_PLUGIN_SOURCE} and usually the \l{NO_PLUGIN_OPTIONAL} options will be needed. +\note +When using static linking, it migt be necessary to use +\c Q_IMPORT_QML_PLUGIN to ensure that the QML plugin is correctly linked. + \section3 Plugin target with no backing target A QML module can be defined with the plugin target serving as its own backing @@ -128,11 +156,16 @@ load-time performance. \section3 Executable as a QML module An executable target can act as a backing target for a QML module. In this case, -there should be no need for a plugin library, since the QML module will always -be loaded directly as part of the application. The \c{qt_add_qml_module()} -command will detect when an executable is used as the backing target and will -automatically disable the creation of a separate plugin. Do not use any of the -options with \c{PLUGIN} in their name when using this arrangement. +there will be no plugin library, since the QML module will always be loaded +directly as part of the application. The \c{qt_add_qml_module()} command will +detect when an executable is used as the backing target and will automatically +disable the creation of a separate plugin. Do not use any of the options with +\c{PLUGIN} in their name when using this arrangement. + +When an executable is used as the backing target, the source directory structure +is not expected to match the QML module's target path. +See \l{qmlcachegen-auto}{Caching compiled QML sources} for additional target +path differences for compiled-in resources. \target qmldir-autogeneration @@ -146,19 +179,27 @@ The \l OUTPUT_DIRECTORY argument determines where the \c qmldir and typeinfo files will be written to. If the QML module has a plugin, that plugin will also be created in the same directory as the \c qmldir file. -In static builds, the backing target's \c{.qml} files will be scanned during -the CMake configure run to determine the imports used by the module and set up -linking relationships. When a \c{.qml} file is added to or removed from the -module, CMake will normally re-run automatically and the relevant files will be -re-scanned, since a \c{CMakeLists.txt} file will have been modified. During the -course of development, an existing \c{.qml} file may add or remove an import or -a type. On its own, this would not cause CMake to re-run automatically, so you -should explicitly re-run CMake to force the \c qmldir file to be regenerated -and any linking relationships to be updated. +If using a statically built Qt, the backing target's \c{.qml} files will be +scanned during the CMake configure run to determine the imports used by the +module and set up linking relationships. When a \c{.qml} file is added to or +removed from the module, CMake will normally re-run automatically and the +relevant files will be re-scanned, since a \c{CMakeLists.txt} file will have +been modified. During the course of development, an existing \c{.qml} file may +add or remove an import or a type. On its own, this would not cause CMake to +re-run automatically, so you should explicitly re-run CMake to force the +\c qmldir file to be regenerated and any linking relationships to be updated. The backing target's C++ sources are scanned at build time to generate a typeinfo file and a C++ file to register the associated types. The generated C++ file is automatically added to the backing target as a source. +This requires \c AUTOMOC to be enabled on the target. The project is +responsible for ensuring this, usually by setting the \c CMAKE_AUTOMOC variable +to \c TRUE before calling \c qt_add_qml_module(), or by passing in an existing +target with the \c AUTOMOC target property already set to \c TRUE. It isn't an +error to have \c AUTOMOC disabled on the target, but the project is then +responsible for handling the consequences. This may include having to manually +generate the typeinfo file instead of allowing it to be auto-generated with +missing details, and adding C++ code to register the types. Projects should prefer to use the auto-generated typeinfo and \c qmldir files where possible. They are easier to maintain and they don't suffer from the same @@ -183,7 +224,7 @@ may still be needed in certain situations by the QML engine. The resource path of each file is determined by its path relative to the current source directory (\c CMAKE_CURRENT_SOURCE_DIR). This resource path is appended to a prefix formed by concatenating the \l{RESOURCE_PREFIX} and -the target path (which is the URI with dots replaced with forward slashes). +the target path (but see \l NO_RESOURCE_TARGET_PATH for an exception to this). Ordinarily, the project should aim to place \c{.qml} files in the same relative location as they would have in the resources. If the \c{.qml} file is in a different relative directory to its desired resource path, its @@ -220,17 +261,39 @@ found at the following resource paths: A separate linting target will be automatically created if any \c{.qml} files are added to the module via the \c QML_FILES keyword, or by a later call to \l{qt6_target_qml_sources}{qt_target_qml_sources()}. The name of the linting -target will be the \c target followed by \c{_qmllint}. The linting target is -not part of the default CMake \c ALL target, it is intended for developers to -execute manually on demand. +target will be the \c target followed by \c{_qmllint}. An \c{all_qmllint} +target which depends on all the individual \c{*_qmllint} targets is also +provided as a convenience. + +\target qml-naming-js-files +\section2 Naming conventions for \c{.js} files + +JavaScript file names that are intended to be addressed as components should +start with an uppercase letter. + +Alternatively, you may use lowercase file names and set the source file +property +\l{cmake-source-file-property-QT_QML_SOURCE_TYPENAME}{QT_QML_SOURCE_TYPE_NAME} +to the desired type name. + +\target qml-cmake-singletons +\section2 Singletons + +If a QML module has \c{.qml} files which provide singleton types, these files +need to have their \c QT_QML_SINGLETON_TYPE source property set to \c TRUE, to +ensure that the \singleton command is written into the +\l{Module Definition qmldir Files}{qmldir} file. This must be done in addition +to the QML file containing the \c {pragma Singleton} statement. + +See \l{qt_target_qml_sources_example}{qt_target_qml_sources()} for an example on +how to set the \c QT_QML_SINGLETON_TYPE property. \section1 Arguments The \c target specifies the name of the backing target for the QML module. -By default, it will be created as a shared library if CMake's -\c BUILD_SHARED_LIBS variable is set to true, or as a static library otherwise. -This choice can be explicitly overridden with the \c STATIC or \c SHARED -options. +By default, it is created as a shared library if Qt was built as shared +libraries, or as a static library otherwise. This choice can be explicitly +overridden with the \c STATIC or \c SHARED options. The plugin target associated with the QML module can be specified using the \c PLUGIN_TARGET argument. The \c PLUGIN_TARGET can be the same as the backing @@ -246,18 +309,28 @@ change the plugin's output name by setting target properties like The backing \c target and the plugin target (if different) will be created by the command, unless they already exist. Projects should generally let them be created by the command so that they are created as the appropriate target type. -If an existing \c target is passed in and it is an executable target, then no -plugin target will be created or used. +If the backing \c target is a static library, the plugin will also be created +as a static library. If the backing \c target is a shared library, the plugin +will be created as a module library. If an existing \c target is passed in and +it is an executable target, there will be no plugin. If you intend to always +link directly to the backing target and do not need a plugin, it can be +disabled by adding the \c NO_PLUGIN option. Specifying both \c NO_PLUGIN and +\c PLUGIN_TARGET is an error. In certain situations, the project may want to delay creating the plugin target until after the call. The \c NO_CREATE_PLUGIN_TARGET option can be given in that situation. The project is then expected to call \l{qt6_add_qml_plugin}{qt_add_qml_plugin()} on the plugin target once it has -been created. +been created. When \c NO_CREATE_PLUGIN_TARGET is given, \c PLUGIN_TARGET must +also be provided to explicitly name the plugin target. Every QML module must define a \c URI. It should be specified in dotted URI -notation, such as \c{QtQuick.Layouts}. It must not contain anything other than -alphanumeric or dot characters. Other QML modules may use this name in +notation, such as \c{QtQuick.Layouts}. Each segment must be a well-formed +ECMAScript Identifier Name. This means, for example, the segments +must not start with a number and they must not contain \e{-} (minus) +characters. As the \c URI will be translated into directory names, you +should restrict it to alphanumeric characters of the latin alphabet, +underscores, and dots. Other QML modules may use this name in \l{qtqml-syntax-imports.html}{import statements} to import the module. The \c URI will be used in the \c module line of the generated \l{Module Definition qmldir Files}{qmldir} file. The \c URI is also used to @@ -267,10 +340,26 @@ A QML module must also define a \c VERSION in the form \c{Major.Minor}, where both \c Major and \c Minor must be integers. An additional \c{.Patch} component may be appended, but will be ignored. A list of earlier major versions the module provides types for can also optionally be given after the -\c PAST_MAJOR_VERSIONS keyword. +\c PAST_MAJOR_VERSIONS keyword (see below). See \l{qtqml-modules-identifiedmodules.html}{Identified Modules} for further in-depth discussion of the module URI and version numbering. +A list of additional major versions the module provides may be given using the +\c PAST_MAJOR_VERSIONS keyword. For each of those versions and each QML file +without a \c QT_QML_SOURCE_VERSIONS setting an additional entry in the +\l{Module Definition qmldir Files}{qmldir} file will be generated to specify +the extra version. Furthermore, the generated module registration code will +register the past major versions using \l{qmlRegisterModule()} on the C++ side. +The module registration code is automatically generated for your QML module, +unless you specify \c{NO_GENERATE_QMLTYPES} (but use of this option is strongly +discouraged). Usage of \c PAST_MAJOR_VERSIONS adds some overhead when your +module is imported. You should increment the major version of your module as +rarely as possible. Once you can rely on all QML files importing this module to +omit the version in their imports, you can safely omit \c{PAST_MAJOR_VERSIONS}. +All the QML files will then import the latest version of your module. If you +have to support versioned imports, consider supporting only a limited number of +past major versions. + \target RESOURCE_PREFIX \c RESOURCE_PREFIX is intended to encapsulate a namespace for the project and will often be the same for all QML modules that the project defines. It should @@ -287,20 +376,37 @@ qt_add_qml_module(someTarget ) \endcode +\target NO_RESOURCE_TARGET_PATH +When various files are added to the compiled-in resources, they are placed +under a path formed by concatenating the \c RESOURCE_PREFIX and the target path. +For the special case where the backing target is an executable, it may be +desirable to place the module's \c{.qml} files and other resources directly +under the \c RESOURCE_PREFIX instead. This can be achieved by specifying the +\c NO_RESOURCE_TARGET_PATH option, which may only be used if the backing target +is an executable. + \target OUTPUT_DIRECTORY \c OUTPUT_DIRECTORY specifies where the plugin library, \c qmldir and typeinfo files are generated. When this keyword is not given, the default value will be the target path (formed from the \c URI) appended to the value of the \l QT_QML_OUTPUT_DIRECTORY variable. -If that variable is not defined, then the output directory will be -set to \c{${CMAKE_CURRENT_BINARY_DIR}}. When the structure of the source tree +If that variable is not defined, the default depends on the type of backing +target. For executables, the value will be the target path appended to +\c{${CMAKE_CURRENT_BINARY_DIR}}, whereas for other targets it will be just +\c{${CMAKE_CURRENT_BINARY_DIR}}. When the structure of the source tree matches the structure of QML module target paths (which is highly recommended), -\l QT_QML_OUTPUT_DIRECTORY often isn't needed. The need for specifying the -\c OUTPUT_DIRECTORY keyword should be rare, but if it is used, it is likely -that the caller will also need to add to the \l IMPORT_PATH to ensure that -\l{qmllint-auto}{linting}, \l{qmlcachegen-auto}{cached compilation} of qml -sources and \l{qt6_import_qml_plugins}{automatic importing} of plugins in -static builds all work correctly. +\l QT_QML_OUTPUT_DIRECTORY often isn't needed. In order to match the structure +of the target paths, you have to call your directories \e exactly like the +segments of your module URI. For example, if your module URI is +\c{MyUpperCaseThing.mylowercasething}, you need to put this in a directory +called \c{MyUpperCaseThing/mylowercasething/}. + +The need for specifying the \c OUTPUT_DIRECTORY keyword should be rare, but if +it is used, it is likely that the caller will also need to add to the +\l IMPORT_PATH to ensure that \l{qmllint-auto}{linting}, +\l{qmlcachegen-auto}{cached compilation} of qml sources and +\l{qt6_import_qml_plugins}{automatic importing} of plugins in static builds all +work correctly. \target NO_GENERATE_PLUGIN_SOURCE By default, \c{qt_add_qml_module()} will auto-generate a \c{.cpp} file that @@ -311,7 +417,21 @@ plugin class, the \c NO_GENERATE_PLUGIN_SOURCE option should be given. Where no \c CLASS_NAME is provided, it defaults to the \c URI with dots replaced by underscores, then \c Plugin appended. Unless the QML module has no plugin, the class name will be recorded as a \c classname line in the generated -\l{Module Definition qmldir Files}{qmldir} file. +\l{Module Definition qmldir Files}{qmldir} file. You need to add any C++ files +with custom plugin code to the plugin target. Since the plugin then likely +contains functionality that goes beyond simply loading the backing library, you +will probably want to add \l{NO_PLUGIN_OPTIONAL}, too. Otherwise the QML engine +may skip loading the plugin if it detects that the backing library is already +linked. + +\target NO_PLUGIN +If the \c NO_PLUGIN keyword is given, then no plugin will be built. This +keyword is thus incompatible with all the options that customize the plugin +target, in particular \l{NO_GENERATE_PLUGIN_SOURCE}, \l{NO_PLUGIN_OPTIONAL}, +\l{PLUGIN_TARGET}, \l{NO_CREATE_PLUGIN_TARGET}, and \l{CLASS_NAME}. If you do +not provide a plugin for your module, it will only be fully usable if its +backing library has been linked into the executable. It is generally hard to +guarantee that a linker preserves the linkage to a library it considers unused. \target NO_PLUGIN_OPTIONAL If the \c NO_PLUGIN_OPTIONAL keyword is given, then the plugin is recorded in @@ -336,13 +456,20 @@ typeinfo file will be generated, but the project will still be expected to generate a typeinfo file and place it in the same directory as the generated \c qmldir file. -\c IMPORTS provides a list of other QML modules that this module imports. -A version can be specified by appending it after a slash, such as -\c{QtQuick/2.0}. The minor version may be omitted, as in \c{QtQuick/2}. -Alternatively, \c auto may be given for the version (\c{QtQuick/auto}), which -would result in the version that the current module is being imported with -being used. Each module listed here will be added as an \c{import} entry in the -generated \l{Module Definition qmldir Files}{qmldir} file. +\c IMPORTS provides a list of other QML modules that this module imports. Each +module listed here will be added as an \c{import} entry in the generated +\l{Module Definition qmldir Files}{qmldir} file. If a QML file imports the +this module, it also imports all the modules listed under \c{IMPORTS}. +Optionally, a version can be specified by appending it after a slash, such as +\c{QtQuick/2.0}. Omitting the version will cause the greatest version available +to be imported. You may only specify the major version, as in \c{QtQuick/2}. In +that case the greatest minor version available with the given major version will +be imported. Finally, \c{auto} may be given as version (\c{QtQuick/auto}). If +\c{auto} is given, the version that the current module is being imported with is +propagated to the module to be imported. Given an entry \c{QtQuick/auto} in a +module \c{YourModule}, if a QML file specifies \c{import YourModule 3.14}, this +results in importing version \c{3.14} of \c{QtQuick}. For related modules that +follow a common versioning scheme, you should use \c{auto}. \c OPTIONAL_IMPORTS provides a list of other QML modules that this module \e may import at run-time. These are not automatically imported by the QML @@ -384,7 +511,8 @@ be added to the backing target after this command has been called. \c RESOURCES lists any other files needed by the module, such as images referenced from the QML code. These files will be added as compiled-in -resources under the \l RESOURCE_PREFIX. If needed, their relative location can +resources (see \l RESOURCE_PREFIX for an explanation of the base point they +will be located under). If needed, their relative location can be controlled by setting the \c QT_RESOURCE_ALIAS source property, just as for \c{.qml} files (see \l{qmlcachegen-auto}{Caching compiled QML sources}). @@ -400,8 +528,8 @@ and are referenced by the backing target's linking requirements as part of ensuring that resources are set up and loaded correctly. The \c DESIGNER_SUPPORTED keyword should be given if the QML module supports -\l{Qt Quick Designer}. When present, the generated \c qmldir file will contain +Qt Quick Designer. When present, the generated \c qmldir file will contain a \c designersupported line. See \l{Module Definition qmldir Files} for how -this affects the way Quick Designer handles the plugin. +this affects the way Qt Quick Designer handles the plugin. */ diff --git a/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc index 01dfc3eb16..fe63d678c7 100644 --- a/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc +++ b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc @@ -37,17 +37,104 @@ \section1 Synopsis \badcode -qt_add_qml_plugin(...) +qt_add_qml_plugin( + target + [BACKING_TARGET backing_target] + [STATIC | SHARED] + [OUTPUT_DIRECTORY] + [URI] + [CLASS_NAME] + [NO_GENERATE_PLUGIN_SOURCE] +) \endcode -\versionlessNote qt6_add_qml_plugin() +\versionlessCMakeCommandsNote qt6_add_qml_plugin() \section1 Description -TBD +This command creates the plugin target associated with a QML module. It would +normally be called internally by \l{qt6_add_qml_module}{qt_add_qml_module()} to +create or update the plugin associated with its backing target. You should not +call this function directly unless you have special circumstances that require +you to create the target in a special way. + +The documentation for \l{qt6_add_qml_module}{qt_add_qml_module()} describes +different structural patterns for how the CMake targets associated with a QML +module can be arranged. Note that even if the QML module has no separate backing +target and all functionality is implemented directly in the plugin (not the +recommended arrangement), you should still call +\l{qt6_add_qml_module}{qt_add_qml_module()} rather than \c{qt_add_qml_plugin()}. + \section1 Arguments -TBD +The \c target specifies the name of the target to use for the QML plugin. If it +does not already exist, it will be created. + +\c BACKING_TARGET specifies the name of the backing target that the plugin is +associated with. The backing target can be the same as the plugin \c target, in +which case there is only the one merged target, but this is not typically +recommended (see \l{qt6_add_qml_module}{qt_add_qml_module()} for more +information). \c BACKING_TARGET should always be provided unless there are +special circumstances that require the plugin target to be created before the +backing target. If \c BACKING_TARGET is not provided, a \c URI option must be +given. + +By default, the plugin is created with a type that is compatible with the +backing target. If the backing target is a static library, the plugin will also +be created as a static library. If the backing target is a shared library, the +plugin will be created as a module library. Where no backing target is +provided or the plugin has no separate backing target, the plugin type can be +specified with either the \c STATIC or \c SHARED keywords. If the plugin type +is not determined by any of the preceding conditions, a static plugin will be +created if Qt was built as static libraries, or a module library plugin +otherwise. + +\c OUTPUT_DIRECTORY specifies the directory where the plugin library will be +created. It should always be the same location as the QML module's +\l{Module Definition qmldir Files}{qmldir} file. When \c OUTPUT_DIRECTORY is +not given, it will be obtained from information stored on the +\c BACKING_TARGET, where available. Note that this could be different to the +directory of the backing target's own library. If an output directory cannot be +obtained from the backing target, the \c CMAKE_CURRENT_BINARY_DIR is used by +default. + +\c URI declares the module identifier of the QML module this plugin is +associated with. The module identifier is the (dotted URI notation) identifier +for the QML module. If \c URI is not given, a \c BACKING_TARGET must be +provided and the backing target must have its URI recorded on it (typically by +an earlier call to \l{qt6_add_qml_module}{qt_add_qml_module()}). + +Each plugin should have a C++ class that registers the module with the QML +engine. By default, \c{qt_add_qml_plugin()} auto-generates the sources for this +C++ class, and adds them to the \c{target}'s list of sources. The generated +plugin class satisfies the requirements of the plugin being optional (see +\l{Module Definition qmldir Files}). The class name is determined as follows: + +\list + \li If \c CLASS_NAME has been given, it will be used. It must match the name + used in the QML module's \c qmldir file. + \li If \c CLASS_NAME has not been given, but \c BACKING_TARGET has, the C++ + class name will be taken from details recorded on that backing target. + Those details are usually recorded by an earlier call to + \l{qt_add_qml_module}{qt_add_qml_module()}, and they will match the name + used in the generated \c qmldir file. This is the recommended way to + provide the class name in most scenarios. + \li If the class name still cannot be determined, it is set to the module's + URI with dots replaced by underscores, and \c Plugin appended. +\endlist + +Some plugins may require the plugin class to be written manually. For example, +the plugin may need to perform additional initialization or register things +not implemented by the default plugin class. In such cases, the +\c NO_GENERATE_PLUGIN_SOURCE option can be given. You are then responsible for +writing your own C++ plugin class and adding it to the \c target. Note that if +you need to write your own plugin class, it is very unlikely that the plugin +can be optional. This in turn means that the \c NO_PLUGIN_OPTIONAL keyword +should be included in the call to \l{qt_add_qml_module}{qt_add_qml_module()} +when defining the QML module, or else the generated \c qmldir file will be +incorrect. Make sure your plugin class uses the same class name as determined +from the logic just above. + */ diff --git a/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc index b2c31123fe..249ae57d79 100644 --- a/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc +++ b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc @@ -34,20 +34,44 @@ \brief Ensures QML plugins needed by a target are imported for static builds. +\cmakecommandsince 6.0 + \section1 Synopsis \badcode -qt_import_qml_plugins(...) - +qt_import_qml_plugins(target) \endcode -\versionlessNote qt6_import_qml_plugins() +\versionlessCMakeCommandsNote qt6_import_qml_plugins() \section1 Description -TBD +\note This command only has any effect if Qt was built statically. If called + using a non-static Qt, it will do nothing and return immediately. + +\c{qt_import_qml_plugins()} runs \c{qmlimportscanner} on the \c target +immediately as part of the call. It finds the static QML plugins used by the +\c target and links it to those plugins so that they are part of the executable +or shared library that \c target represents. The search follows QML module +imports recursively. + +Because the call to \c{qmlimportscanner} runs at configure time rather than +generation or build time, \c{qt_import_qml_plugins()} only knows about the +information recorded on the \c target (or other targets it links or imports) +at the time \c{qt_import_qml_plugins()} is called. Any linking or import +relationships added after this call will not be considered. Therefore, this +command should be called as late as possible in the \c{target}'s directory +scope so that all the linking and import relationships are known. + +If \c target was created using \l{qt6_add_executable}{qt_add_executable()}, +projects would not normally need to call \c{qt_import_qml_plugins()} directly. +When Qt is built statically, the command is called automatically as part of +\l{qt6_add_executable#Finalization}{target finalization} if \c target links to +the Qml library. By default, this finalization occurs at the end of the same +directory scope in which the \c target was created. If the \c target was +created using the standard CMake \c{add_executable()} command instead, the +project needs to call \c{qt_import_qml_plugins()} itself. -\section1 Arguments +\sa Q_IMPORT_QML_PLUGIN -TBD */ diff --git a/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc index 05770b30e0..dc1178be29 100644 --- a/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc +++ b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc @@ -32,22 +32,197 @@ \title qt_target_qml_sources \target qt6_target_qml_sources -\brief Add qml sources to an existing QML module target. +\brief Add qml files and resources to an existing QML module target. + +\cmakecommandsince 6.2 \section1 Synopsis \badcode -qt_target_qml_sources(...) +qt_target_qml_sources( + target + [QML_FILES ...] + [RESOURCES ...] + [PREFIX resource_path] + [OUTPUT_TARGETS out_targets_var] + [NO_LINT] + [NO_CACHEGEN] + [NO_QMLDIR_TYPES] +) \endcode -\versionlessNote qt6_target_qml_sources() +\versionlessCMakeCommandsNote qt6_target_qml_sources() \section1 Description -TBD +\note This command requires CMake 3.19 or later. + +\c{qt_target_qml_sources()} provides the ability to add more files to a QML +module after \l{qt6_add_qml_module}{qt_add_qml_module()} has been called. +Typically, you pass the set of \c{.qml} files and resources to +\l{qt6_add_qml_module}{qt_add_qml_module()} directly, but in some cases, it may +be desirable, or even necessary, to add files after +\l{qt6_add_qml_module}{qt_add_qml_module()} has been called. For example, you +may wish to add files conditionally based on an \c{if} statement expression, +or from subdirectories that will only be added if certain criteria are met. +You might want to add a set of files with different characteristics to the +others, such as a different resource prefix, or with linting and bytecode +compilation disabled. The \c{qt_target_qml_sources()} command enables these +scenarios. \section1 Arguments -TBD +The \c target must be the backing target of a QML module, or if the QML module +has no separate backing target, it must be the module's plugin target. + +\c QML_FILES is a list of \c{.qml}, \c{.js} and \c{.mjs} files to be added to +the QML module. This option has exactly the same effect as the \c QML_FILES +option of the \l{qt6_add_qml_module}{qt_add_qml_module()} command, including +the automatic compilation to bytecode and lint processing. + +The \c NO_CACHEGEN and \c NO_LINT options also have the same effect as they do +for \l{qt6_add_qml_module}{qt_add_qml_module()}. They disable the bytecode +compilation and lint processing for the files listed with \c QML_FILES. This +behavior can also be specified just for individual files using +\l{qml-source-file-properties}{source file properties}. + +\c NO_QMLDIR_TYPES prevents the \c QML_FILES from being added as types to the +generated \l{qmldir-autogeneration}{qmldir} file. + +\c RESOURCES has exactly the same effect as the \c RESOURCES option of the +\l{qt6_add_qml_module}{qt_add_qml_module()} command. It provides a list of +files to be added to the \c target as ordinary resources. These files are +typically things like images, shaders, etc. that the QML code refers to in some +way. + +\target PREFIX +Files added to the module via \c QML_FILES or \c RESOURCES will be placed under +the same resource prefix and target path as they would if they were added by the +\l{qt6_add_qml_module}{qt_add_qml_module()} command. This can be overridden by +providing a different location with the \c PREFIX option. The value following +the \c PREFIX keyword will be used directly, without appending any target path. +The final resource path of each file will be the prefix, plus the path of the +file below the \c CMAKE_CURRENT_SOURCE_DIR. The \l{QT_RESOURCE_ALIAS} source +file property can also be used to override that relative path. + +\badcode +qt_add_qml_module(backing + URI Example + VERSION 1.0 + RESOURCE_PREFIX /my.company.com/imports +) + +qt_target_qml_sources(backing + QML_FILES special/First.qml + RESOURCES icons/logo.png +) + +qt_target_qml_sources(backing + PREFIX /other.company.com/debugging + QML_FILES Inspector.qml +) +\endcode + +In the above example, the \c backing target's resources will end up with the +following contents: + +\list +\li \c{/my.company.com/imports/Example/special/First.qml} +\li \c{/my.company.com/imports/Example/icons/logo.png} +\li \c{/other.company.com/debugging/Inspector.qml} +\endlist + +\c OUTPUT_TARGETS is also analogous to the same option for +\l{qt6_add_qml_module}{qt_add_qml_module()}. Use it to specify the name of a +variable in which to store any additional targets created for static builds. +If the \c target will be installed, these additional targets will also need to +be installed to satisfy linking requirements. + +\target qml-source-file-properties +\section1 Source File Properties + +A number of source file properties can be used to influence how each individual +\c{.qml} file is treated at various points in the QML module processing. These +override any higher level options specified in calls to +\c{qt_target_qml_sources()} or \l{qt6_add_qml_module}{qt_add_qml_module()}. +All of these properties need to be set before the files are added with either +of those two commands. + +\c QT_QML_SKIP_QMLLINT can be set to \c TRUE on a source file to prevent it +from being included in the \l{qmllint-auto}{automatic qmllint processing}. +By default, all \c{.qml} files will be included in the target's lint run, but +this option can be used to exclude specific files. + +\c QT_QML_SKIP_CACHEGEN does a similar thing, preventing a source file from +being compiled to byte code when this property is set to \c TRUE. Note that the +file will still be added to the \c target as a resource in uncompiled form +(see \l{qmlcachegen-auto}{Caching compiled QML sources}). + +Set the \c QT_QML_SKIP_QMLDIR_ENTRY source file property to \c TRUE to prevent +that \c{.qml} file from being added as a type to the QML module's typeinfo file +(see \l{qmldir-autogeneration}{Auto-generating \c{qmldir} and typeinfo files}). +This would normally only be used for a file that does not expose a public type, +such as a private JS file. + +By default, when \l{qmldir-autogeneration}{generating the \c qmldir file}, a +single type entry will be generated for each \c{.qml} file that provides a type. +It will be given a version number \c{X.0} where \c{X} is the major version of +the QML module. If the QML module has any \c PAST_MAJOR_VERSIONS set, the same +pattern will be applied to those too, appending \c{X.0} for each past major +version \c{X}. For situations where a file needs to provide type entries for +a different set of versions instead (e.g. it was first added in a minor patch +version after the \c{.0} release), specify those versions in the source file's +\c QT_QML_SOURCE_VERSIONS property. One type entry will be created for each +version. + +If the type that a \c{.qml} file provides is a singleton, set its +\c QT_QML_SINGLETON_TYPE property to \c TRUE. Similarly, the file's +\c QT_QML_INTERNAL_TYPE source property can be set to \c TRUE to indicate that +the type it provides is an internal one. The name of the type itself can also +be overridden using the \c QT_QML_SOURCE_TYPENAME property. All three of these +will be reflected in the file's type entries in the +\l{qmldir-autogeneration}{generated \c qmldir file}. + +\target QT_RESOURCE_ALIAS +All files listed with \c QML_FILES or \c RESOURCES will be added to the +\c{target}'s resources. Their location in the resources consists of a base point +and a relative path. The base point defaults to the concatenation of the QML +module's resource prefix and its target path, but these can be overridden with +the \l PREFIX argument. The relative path will default to the path of the file +relative to the \c{target}'s \c SOURCE_DIR target property. This relative path +can be overridden by setting the \c QT_RESOURCE_ALIAS property on the source +file. This is commonly used to collect files from different directories and +have them appear in the resources under a common location. + +\target qt_target_qml_sources_example +\snippet cmake/qt_target_qml_sources/CMakeLists.txt 0 + +In the above example, the \c qt_target_qml_sources_example target's resources +will end up with the following contents: + +\list +\li \c{/my.company.com/imports/Example/File.qml} +\li \c{/my.company.com/imports/Example/FunnySingleton.qml} +\li \c{/my.company.com/imports/Example/templates/File.qml} +\li \c{/my.company.com/imports/Example/some_old_thing.qml} +\li \c{/my.company.com/imports/Example/button-types.png} +\li \c{/my.company.com/imports/Example/doc/README.txt} +\endlist + +The generated \c qmldir file will contain the following type entries: + +\badcode +File 2.0 File.qml +singleton FunnySingleton 2.0 FunnySingleton.qml +OldThing 1.1 some_old_thing.qml +OldThing 2.0 some_old_thing.qml +\endcode + +\note The source FunnySingleton.qml file must already contain +the \c {pragma Singleton} statement. Setting the \c QT_QML_SINGLETON_TYPE source +property does not automatically generate the pragma. + +\snippet cmake/qt_target_qml_sources/FunnySingleton.qml 0 + */ diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc index 969bf4f7c0..d4fe08e37d 100644 --- a/src/qml/doc/src/cppintegration/definetypes.qdoc +++ b/src/qml/doc/src/cppintegration/definetypes.qdoc @@ -97,15 +97,18 @@ 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, add -\c QML_ELEMENT or \c QML_NAMED_ELEMENT(<name>) to the class declaration and +\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. 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 +\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_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 @@ -127,26 +130,52 @@ 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 -CONFIG += qmltypes -QML_IMPORT_NAME = com.mycompany.messaging -QML_IMPORT_MAJOR_VERSION = 1 -\endcode +\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 -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 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" @@ -334,10 +363,9 @@ 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 @@ -619,6 +647,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. diff --git a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc index 6e6d067ba6..b5f0676920 100644 --- a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc +++ b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -397,13 +397,11 @@ plugin with the Qt meta object system. Here is the \c ChartsPlugin definition in \c chartsplugin.h: -\snippet tutorials/extending-qml/chapter6-plugins/import/chartsplugin.h 0 +\snippet tutorials/extending-qml/chapter6-plugins/Charts/chartsplugin.h 0 -Then, we write a \c .pro project file that defines the project as a plugin library -and specifies with DESTDIR that library files should be built into a \c {../Charts} -directory. +Then, we write a \c .pro project file that defines the project as a plugin library. -\quotefile tutorials/extending-qml/chapter6-plugins/import/import.pro +\quotefile tutorials/extending-qml/chapter6-plugins/Charts/Charts.pro When building this example on Windows or Linux, the \c Charts directory will be located at the same level as the application that uses our new import module. @@ -413,7 +411,7 @@ plugin binary is copied to \c Contents/PlugIns in the the application bundle; this path is set in \c {chapter6-plugins/app.pro}: \quotefromfile tutorials/extending-qml/chapter6-plugins/app.pro -\skipto osx +\skipto macos \printuntil } To account for this, we also need to add this location as a @@ -432,16 +430,16 @@ to the same location as the plugin binary. The \c qmldir file declares the module name and the plugin that is made available by the module: -\quotefile tutorials/extending-qml/chapter6-plugins/import/qmldir +\quotefile tutorials/extending-qml/chapter6-plugins/Charts/qmldir Now we have a QML module that can be imported to any application, provided that the QML engine knows where to find it. The example contains an executable that loads \c app.qml, which uses the \c {import Charts 1.0} statement. Alternatively, you can -load the QML file using the \l{Prototyping with qmlscene}{qmlscene tool}, setting the -import path to the current directory so that it finds the \c qmldir file: +load the QML file using the \l {Prototyping with the QML Runtime Tool}{qml tool}, +setting the import path to the current directory so that it finds the \c qmldir file: \code - qmlscene -I . app.qml + qml -I . app.qml \endcode The module "Charts" will be loaded by the QML engine, and the types provided by that diff --git a/src/qml/doc/src/cppintegration/integrating-with-js-values-from-cpp.qdoc b/src/qml/doc/src/cppintegration/integrating-with-js-values-from-cpp.qdoc new file mode 100644 index 0000000000..64342fe1f8 --- /dev/null +++ b/src/qml/doc/src/cppintegration/integrating-with-js-values-from-cpp.qdoc @@ -0,0 +1,185 @@ +/**************************************************************************** +** +** Copyright (C) 2012 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$ +** +****************************************************************************/ +/*! +\page qtqml-integrating-with-js-values-from-cpp.html +\title Integrating with JavaScript values from C++ +\brief Description of how to load and access JavaScript from C++ code. + +The following classes can be used to load and access JavaSript from C++ code: + +\list + + \li \l QJSValue, which acts as a container for Qt/JavaScript data types. + \li \l QJSManagedValue, which represents a value on the JavaScript heap + belonging to a \l QJSEngine. + \li \l QJSPrimitiveValue, which operates on primitive types in JavaScript semantics. +\endlist + +Use QJSValue to transfer values to and from the engine, and use QJSManagedValue +to interact with JavaScript values. Only use QJSPrimitiveValues if you have to +emulate the semantics of JS primitive values in C++. + +\table + \header + \li QJSValue + \li QJSManagedValue + \li QJSPrimitiveValue + \row + \li Persistently store values + \li Short lived + \li Short lived + \row + \li Transport values to/from engine + \li Access properties + \li Only Primitives + \row + \li + \li Call methods + \li Basic arithmetic and comparison +\endtable + +\section1 QJSValue as a Container Type + +\l QJSValue stores the Qt/JavaScript data types supported in ECMAScript including +function, array and arbitrary object types as well as anything supported by +QVariant. As a container, it can be used to pass values to and receive values +from a QJSEngine. + +\snippet qtjavascript/integratingjswithcpp/exampleqjsascontainer.cpp qjs-as-container + +In case of a cache miss, \c undefined is returned. Otherwise, the cached value is +returned. Note that implicit conversions (from QString and QJSValue::SpecialValue respectively) +occur when the value is returned. + +QJSValue also has an API to interact with the contained value, but using +QJSManagedValue is recommended. + +\section1 Primitive and Managed Values + +QJSValue and QJSManagedValue store values that can be either managed or primitive. +In QML’s JS engine, a managed value can be thought of as a pointer to some data +structure on the heap, whose memory is managed by the engine’s garbage collector. +The actual content of primitive values is stored directly, using a technique +called NaN-boxing that enables you to represent a NaN-value in multiple ways, even +though only two are actually needed; one for signalling and one for quiet NaN-value. + +\table +\header + \li Primitive Values + \li Managed Values +\row + \li int + \li Function +\row + \li double + \li Array +\row + \li undefined + \li QVariant +\row + \li null + \li string object +\row + \li QString + \li +\endtable + +A pointer to the engine can be obtained from a managed value, but not from a +primitive one. When using QJSValue for its JavaScript API, you need access +to the engine to evaluate JavaScript. For example, to run the \c call(args) function, +you have to interpret it in the engine. This works, as the function is a managed +value, and you can obtain the engine from it. + +Similarly, where the engine is needed when you call a function or +access a property on a primitive number or string. Whenever you call a method on +a primitive, an instance of its corresponding non-primitive objects is created. +This is referred as boxing. When you write \c (42).constructor, that is equivalent +to \c (new Number(42)).constructor, and it returns the constructor method of the +global number object. Accordingly, if you write \c QJSValue(42).property("constructor"), +you would expect to obtain a QJSValue containing that function. However, what you +get is instead a QJSValue containing \c undefined. + +The QJSValue that you constructed contains only a primitive value, and thus you have +no way to access the engine. You also can’t simply hardcode the property lookup +for primitive values in QJSEngine, as in one engine you might set +\e {Number.prototype.constructor.additionalProperty = "the Spanish Inquisition"} +whereas in another \e {Number.prototype.constructor.additionalProperty = 42}. +The end result would then clearly be unexpected. + +To ensure that property accesses always work, you would need to always store boxed +values in QJSValue or store an additional pointer to the engine. + +However, this would be incompatible with how QJSValue is currently used, lead to +pointless JS heap allocations when passing around primitives, and increase the +size needed to store a QJSValue. Therefore, you should use \l QJSValue only for +storage and \l QJSManagedValue to obtain the engine. + +\section1 QJSManagedValue + +QJSManagedValue is similar to QJSValue, with a few differences: + +\list +\li The constructors (except for the default and move constructor2) require + passing a QJSEngine pointer. +\li Methods like \c deleteProperty and \l isSymbol are added. +\li If QJSManagedValue methods encounter an exception, they leave it intact. +\endlist + +To obtain the engine in code, either you are in a scripting context where you’ve +already got access to an engine to create new objects with \c QJSEngine::newObject +and to evaluate expressions with \c QJSEngine::evaluate, or you want to evaluate +some JavaScript in a QObject that has been registered with the engine. In the +latter case, you can use \c qjsEngine(this) to obtain the currently active +QJSEngine. + +QJSManagedValue also provides a few methods that have no equivalent in QJSEngine. + +In the example below, QJSManagedValue methods encounter an exception, and +QJSEngine::catchError is used to handle the exception. + +\snippet qtjavascript/integratingjswithcpp/exampleqjsengine.cpp qjs-engine-example + +However, inside a method of a registered object, you might want to instead let +the exception bubble up the call stack. + +QJSManagedValue should be temporarily created on the stack, +and discarded once you don’t need to work any longer on the contained value. +Since QJSValue can store primitive values in a more efficient way, QJSManagedValue +should also not be used as an interface type which is the return or parameter type of +functions, and the type of properties, as the engine does not treat it in a +special way, and will not convert values to it (in contrast to QJSValue). + +\section1 QJSPrimitiveValue + +\l QJSPrimitiveValue can store any of the primitive types, and supports arithmetic +operations and comparisons according to the ECMA-262 standard. It allows for +low-overhead operations on primitives in contrast to QJSManagedValue, which always goes +through the engine, while still yielding results that are indistinguishable +from what the engine would return. As QJSPrimitiveValue is comparatively large, it +is not recommended to store values. + +*/ diff --git a/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc b/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc index 0a824bb5b5..6277b01af3 100644 --- a/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc +++ b/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc @@ -105,6 +105,88 @@ You can also connect to any signals or call methods defined in the component using QMetaObject::invokeMethod() and QObject::connect(). See \l {Invoking QML Methods} and \l {Connecting to QML Signals} below for further details. +\section1 Accessing QML Objects via well-defined C++ Interfaces + +The best way of interacting with QML from C++ is to define an interface for +doing so in C++ and accessing it in QML itself. With other methods, refactoring +your QML code can easily lead to your QML / C++ interaction breaking. It also +helps to reason about the interaction of QML and C++ code, as having it driven +via QML can be more easily reasoned about by both users and tooling such as +qmllint. Accessing QML from C++ will lead to QML code that cannot be understood +without manually verifying that no outside C++ code is modifying a given QML +component, and even then the extent of the access might change over time, making +continued use of this strategy a maintenance burden. + +To let QML drive the interaction, first you need to define a C++ interface: + +\code +class CppInterface : public QObject +{ + Q_OBJECT + QML_ELEMENT + // ... +}; +\endcode + +Using a QML-driven approach, this interface can be interacted with in two ways: + +\section2 Singletons + +One option is to register the interface as a singleton by adding the \l +QML_SINGLETON macro to the interface, exposing it to all components. Following +that, the interface becomes available via a simple import statement: + +\code +import my.company.module + +Item { + Component.onCompleted: { + CppInterface.foo(); + } +} +\endcode + +Use this approach if you need your interface in more places than the root component, as +simply passing down an object would require explicitly passing it on to other +components via a property or utilizing the slow and not recommended method of +using \l {Unqualified access}{unqualified access}. + +\section2 Initial properties + +Another option is to mark the interface as uncreatable via \l QML_UNCREATABLE +and supplying it to the root QML Component by using \l +QQmlComponent::createWithInitialProperties() and a \l {Required +Properties}{required property} on the QML end. + +Your root component may look something like this: + +\code +import QtQuick + +Item { + required property CppInterface interface + Component.onCompleted: { + interface.foo(); + } +} +\endcode + +Marking the property as required here protects the component against being +created without the interface property being set. + +You can then initialize your component in the same way as outlined in \l +{Loading QML Objects from C++} except using \c {createWithInitialProperties()}: + +\code + component.createWithInitialProperties(QVariantMap{{u"interface"_qs, QVariant::fromValue<CppInterface *>(new CppInterface)}}); +\endcode + +This method is to be preferred if you know that your interface only needs to be +available to the root component. It also allows for connecting to signals and +slots of the interface more easily on the C++ side. + +If neither of these methods suit your needs you may want to investigate the usage of +\l {Using C++ Models with Qt Quick Views}{C++ models} instead. \section1 Accessing Loaded QML Objects by Object Name @@ -189,9 +271,9 @@ Notice the parameter and return type specified after the colon. You can use \l {QML Basic Types}{basic types} and \l {QML Object Types}{object types} as type names. -If the type is omitted in QML, then you must specify QVariant as type with -Q_RETURN_ARG() and Q_ARG() when calling QMetaObject::invokeMethod. - +If the type is omitted or specified as \c var in QML, then you must pass +QVariant as type with Q_RETURN_ARG() and Q_ARG() when calling +QMetaObject::invokeMethod. \section2 Connecting to QML Signals diff --git a/src/qml/doc/src/javascript/finetuning.qdoc b/src/qml/doc/src/javascript/finetuning.qdoc index 97dc2421c5..61ac7d0c8f 100644 --- a/src/qml/doc/src/javascript/finetuning.qdoc +++ b/src/qml/doc/src/javascript/finetuning.qdoc @@ -82,9 +82,12 @@ Running JavaScript code can be influenced by a few environment variables, partic \li \c{QV4_MAX_CALL_DEPTH} \li Stack overflows when running (as opposed to compiling) JavaScript are prevented by controlling the call depth: the number of nested function invocations. By - default, an exception is generated if the call depth exceeds 1234. If it contains a - number, this environment variable overrides the maximum call depth. Beware that the - recursion limit when compiling JavaScript is not affected. + default, an exception is generated if the call depth exceeds a maximum number tuned + to the platform's default stack size. If the \c{QV4_MAX_CALL_DEPTH} environment + variable contains a number, this number is used as maximum call depth. Beware that + the recursion limit when compiling JavaScript is not affected. The default maximum + call depth is 1234 on most platforms. On QNX it is 640 because on QNX the default + stack size is smaller than on most platforms. \row \li \c{QV4_MM_AGGRESSIVE_GC} \li Setting this environment variable runs the garbage collector before each memory diff --git a/src/qml/doc/src/javascript/hostenvironment.qdoc b/src/qml/doc/src/javascript/hostenvironment.qdoc index 6f1134a3e2..943da5cbef 100644 --- a/src/qml/doc/src/javascript/hostenvironment.qdoc +++ b/src/qml/doc/src/javascript/hostenvironment.qdoc @@ -42,7 +42,8 @@ Like a browser or server-side JavaScript environment, the QML runtime implements all of the built-in types and functions defined by the standard, such as Object, Array, and Math. The QML runtime implements the 7th edition of the standard. -\l{Nullish Coalescing} (since Qt 5.15) and \l{Optional Chaining} (since Qt 6.2) are also implemented in the QML runtime. +\l{Nullish Coalescing} (\c{??}) (since Qt 5.15) and \l{Optional Chaining} (\c{?.}) (since Qt 6.2) +are also implemented in the QML runtime. The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more information on their use, please refer to the ECMA-262 7th edition standard or one of the many online @@ -70,11 +71,10 @@ to use from C++. See \l {qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++} for more information. -Type assertions can also be used in order to cast an object to a different -object type. If the object is actually of the given type, then the type -assertion returns the same object. If not, it returns \c null. In the following -snippet we assert that the \c parent object is a \c Rectangle before accessing -a specific member of it. +Type assertions (sometimes called \e as-casts) can also be used in order to cast an object to a +different object type. If the object is actually of the given type, then the type assertion returns +the same object. If not, it returns \c null. In the following snippet we assert that the \c parent +object is a \c Rectangle before accessing a specific member of it. \qml Item { diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc index 9227f0e604..8d49c02f62 100644 --- a/src/qml/doc/src/javascript/imports.qdoc +++ b/src/qml/doc/src/javascript/imports.qdoc @@ -95,17 +95,18 @@ or modules). A JavaScript resource may import another in the following fashion: \code -.import "filename.js" as Qualifier +import * as MathFunctions from "factorial.mjs"; \endcode -For example: +Or: \code -import * as MathFunctions from "factorial.mjs"; +.import "filename.js" as Qualifier \endcode -The latter is standard ECMAScript syntax for importing ECMAScript modules, and +The former is standard ECMAScript syntax for importing ECMAScript modules, and only works from within ECMAScript modules as denoted by the \c mjs file -extension. The former is an extension to JavaScript provided by the \c QML -engine and will work also with non-modules. +extension. The latter is an extension to JavaScript provided by the \c QML +engine and will work also with non-modules. As an extension superseded by the +ECMAScript standard, its usage is discouraged. When a JavaScript file is imported this way, it is imported with a qualifier. The functions in that file are then accessible from the importing script via the diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index 3fc4c86f74..cc4f4a2747 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -45,8 +45,8 @@ \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: + \e {com.mycompany.qmlcomponents} with major version \c 1. + For qmake, specify the following in your project file: \badcode CONFIG += qmltypes @@ -54,6 +54,15 @@ QML_IMPORT_MAJOR_VERSION = 1 \endcode + With CMake, you pass the URI and version to qt_add_qml_module + + \badcode + qt6_add_qml_module(myapp + URI com.mycompany.qmlcomponents + VERSION 1.0 + ) + \endcode + Once registered, the type can be used in QML by importing the same type namespace and version number: @@ -101,8 +110,9 @@ \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. + cannot be created or used to declare properties in QML, but when passed from + C++, it is recognized. In QML, you can use properties of this type if they + are declared in C++. \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_INTERFACE */ @@ -274,7 +284,7 @@ // Initialize this using myObject where you would previously // call qmlRegisterSingletonInstance(). - static MySingleton *s_singletonInstance = nullptr; + inline static MySingleton *s_singletonInstance = nullptr; static MySingleton *create(QQmlEngine *, QJSEngine *engine) { @@ -298,7 +308,7 @@ } private: - static QJSEngine *s_engine = nullptr; + inline static QJSEngine *s_engine = nullptr; }; \endcode @@ -1243,20 +1253,25 @@ \fn bool qmlProtectModule(const char* uri, int majVersion); \relates QQmlEngine - This function protects a module from having types registered into it. This - can be used to prevent other plugins from injecting types into your module. - It can also be a performance improvement, as it allows the engine to skip - checking for the possibility of new types or plugins when this import is - reached. - - The performance benefit is primarily seen when registering application - specific types from within the application instead of through a plugin. - Using qmlProtectModule allows the engine to skip checking for a plugin when - that uri is imported, which can be noticeable with slow file systems. - - After this function is called, any attempt to register C++ types into this - uri, major version combination will lead to a runtime error. Call this after - you have registered all of your types with the engine. + This function protects a module from further modification. This can be used + to prevent other plugins from injecting types into your module. It can also + be a performance improvement, as it allows the engine to skip checking for + the possibility of new types or plugins when this import is reached. + + Once qmlProtectModule has been called, a QML engine will not search for a new + \c qmldir file to load the module anymore. It will re-use any \c qmldir files + it has loaded before, though. Therefore, types present at this point continue + to work. Mind that different QML engines may load different modules. The + module protection, however, is global and affects all engines. The overhead + of locating \c qmldir files and loading plugins may be noticeable with slow file + systems. Therefore, protecting a module once you are sure you won't need to + load it anymore can be a good optimization. Mind also that the module lock + not only affects plugins but also any other qmldir directives, like \c import + or \c prefer, as well as any composite types or scripts declared in a \c qmldir + file. + + In addition, after this function is called, any attempt to register C++ types + into this uri, major version combination will lead to a runtime error. Returns true if the module with \a uri as a \l{Identified Modules} {module identifier} and \a majVersion as a major version number was found diff --git a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc index 718b0c25ac..562b262271 100644 --- a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc @@ -53,8 +53,12 @@ The type name has the following requirements: 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. +available to other QML files within the same local directory as the engine +searches within the immediate directory when resolving QML type names. + +\note The QML engine does not automatically search remote directories this way. +You have to add a qmldir file if your documents are loaded over the network. See +\l{Importing QML Document Directories}. \section2 Custom QML Type Definition diff --git a/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc index d762621d6c..8f21a7348c 100644 --- a/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -51,7 +51,8 @@ Image { Network transparency is supported throughout QML, for example, both the FontLoader and Image elements support loading resources from a remote server. -Even QML types themselves can be on the network - if the \l {Prototyping with qmlscene} is used to load +Even QML types themselves can be on the network: if the +\l {Prototyping with the QML Runtime Tool}{qml tool} is used to load \tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file. For example if the qmldir file contains the line "World World.qml", it will load diff --git a/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc index 303ed6b18c..493b031b60 100644 --- a/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc @@ -35,8 +35,8 @@ specified by the module in its \c qmldir file. This enables such modules to be imported with a unique identifier that remains the same no matter where the module is located on the local file system. -When importing an identified module, an unquoted identifier is used, with a -mandatory version number: +When importing an identified module, an unquoted identifier is used, with an +optional version number: \snippet qml/imports/installed-module.qml imports @@ -44,6 +44,12 @@ Identified modules must be installed into the \l{qtqml-syntax-imports.html#qml-import-path}{import path} in order to be found by the QML engine. +Syntactically, each dot-separated segment of the URI must be a well-formed +ECMAScript Identifier Name. This means, for example, the segments must not start +with a number and they must not contain \e{-} (minus) characters. As the URI +will be translated into directory names, you should restrict it to alphanumeric +characters of the latin alphabet, underscores, and dots. + \section1 Locally Installed Identified Modules A directory of QML and/or C++ files can be shared as an identified module if it diff --git a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc index 95e8a179de..4d7ea272ce 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc @@ -43,278 +43,287 @@ module. For more information about the first form of \c qmldir file, see \section1 Contents of a Module Definition qmldir File -A \c qmldir file is a plain-text file that contains -the following commands: - -\table 70% - \header - \li Syntax - \li Usage - \row - \li - \code -module <ModuleIdentifier> - \endcode - \li Declares the module identifier of the module. - The <ModuleIdentifier> is the (dotted URI notation) identifier - for the module, which must match the module's install path. - - The \l{Identified Modules#Semantics of Identified Modules} - {module identifier directive} must be the first line of the file. - Exactly one module identifier directive may exist in the \c qmldir - file. - - Example: - \code -module ExampleModule - \endcode - - \row - \li - \code -[singleton] <TypeName> <InitialVersion> <File> - \endcode - \li Declares a \l{qtqml-typesystem-objecttypes.html}{QML object type} - to be made available by the module. - \list - \li \c [singleton] Optional. Used to declare a singleton type. - \li \c <TypeName> is the type being made available - \li \c <InitialVersion> is the module version for which the type is to be made available - \li \c <File> is the (relative) file name of the QML file that defines the type - \endlist - - Zero or more object type declarations may exist in the \c qmldir - file, however each object type must have a unique type name within - any particular version of the module. - \note To declare a \c singleton type, the QML file defining the - type must include the \c {pragma Singleton} statement. - - Example: - \code -//Style.qml with custom singleton type definition -pragma Singleton -import QtQuick 2.0 +A \c qmldir file is a plain-text file that contains the following commands: -QtObject { - property int textSize: 20 - property color textColor: "green" -} +\list + \li \l {Module Identifier Declaration} + \li \l {Object Type Declaration} + \li \l {Internal Object Type Declaration} + \li \l {JavaScript Resource Declaration} + \li \l {Plugin Declaration} + \li \l {Plugin Classname Declaration} + \li \l {Type Description File Declaration} + \li \l {Module Dependencies Declaration} + \li \l {Module Import Declaration} + \li \l {Designer Support Declaration} + \li \l {Preferred Path Declaration} +\endlist -// qmldir declaring the singleton type -module CustomStyles -singleton Style 1.0 Style.qml +\note Each command in a \c qmldir file must be on a separate line. -// singleton type in use -import QtQuick 2.0 -import CustomStyles 1.0 +In addition to commands, you can also add comments, which are lines starting +with \c {#}. -Text { - font.pixelSize: Style.textSize - color: Style.textColor - text: "Hello World" -} - \endcode - - \row - \li - \code -internal <TypeName> <File> - \endcode - \li Declares an object type that is in the module but should not be - made available to users of the module. - - Zero or more internal object type declarations may exist in the - \c qmldir file. - - Example: - \code -internal MyPrivateType MyPrivateType.qml - \endcode - - This is necessary if the module may be imported remotely (see - \l{Identified Modules#Remotely Installed Identified Modules} - {Remotely Installed Identified Modules}) because if an exported type depends - on an non-exported type within the module, the engine must also - load the non-exported type. - - \row - \li - \code -<ResourceIdentifier> <InitialVersion> <File> - \endcode - \li Declares a JavaScript file to be made available by the module. - The resource will be made available via the specified identifier - with the specified version number. - - Zero or more JavaScript resource declarations may exist in the - \c qmldir file, however each JavaScript resource must have a unique - identifier within any particular version of the module. - - Example: - \code -MyScript 1.0 MyScript.js - \endcode - - See the documentation about \l{qtqml-javascript-resources.html} - {defining JavaScript resources} and - \l{qtqml-javascript-imports.html} - {Importing JavaScript Resources In QML} for more information. - - \row - \li - \code -[optional] plugin <Name> [<Path>] - \endcode - \li Declares a plugin to be made available by the module. - - \list - \li \c optional denotes that the plugin itself does not contain - any relevant code and only serves to load a library it links - to. If given, and if any types for the module are already - available, indicating that the library has been loaded by some - other means, QML will not load the plugin. - \li \c <Name> is the plugin library name. This is usually not the - same as the file name of the plugin binary, which is platform - dependent; e.g. the library \c MyAppTypes would produce - \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows. - \li \c <Path> (optional) specifies either: - \list - \li an absolute path to the directory containing the plugin - file, or - \li a relative path from the directory containing the \c qmldir - file to the directory containing the plugin file. - \endlist - - By default the engine searches for the plugin library in the - directory that contains the \c qmldir file. (The plugin search - path can be queried with QQmlEngine::pluginPathList() and - modified using QQmlEngine::addPluginPath().) - \endlist - - Zero or more C++ plugin declarations may exist in the \c qmldir - file, however since plugin loading is a relatively expensive - operation, clients are advised to specify at most a single plugin. - - Example: - \code -plugin MyPluginLibrary - \endcode - \row - \li - \code -classname <C++ plugin class> - \endcode - \li Provides the class name of the C++ plugin used by the module. - - This information is required for all the QML modules that depend - on a C++ plugin for additional functionality. Qt Quick applications - built with static linking cannot resolve the module imports without - this information. - - \row - \li - \code -typeinfo <File> - \endcode - \li Declares a \l{Type Description Files}{type description file} for - the module that can be read by QML tools such as Qt Creator to - access information about the types defined by the module's plugins. - \c <File> is the (relative) file name of a \c .qmltypes file. - - Example: - \code -typeinfo mymodule.qmltypes - \endcode - - Without such a file, QML tools may be unable to offer features such - as code completion for the types defined in your plugins. - - \row - \li - \code -depends <ModuleIdentifier> <InitialVersion> - \endcode - \li Declares that this module depends on another. - - Example: - \code -depends MyOtherModule 1.0 - \endcode - - This declaration is necessary only in cases when the dependency is - hidden: for example, when the C++ code for one module is used to - load QML (perhaps conditionally) which then depends on other - modules. In such cases, the \c depends declaration is necessary - to include the other modules in application packages. - \row - \li - \code -import <ModuleIdentifier> [<Version>] - \endcode - \li Declares that this module imports another. - - Example: - \code -import MyOtherModule 1.0 - \endcode - - The types from the other module are made available in the same type - namespace as this module is imported into. Omitting the version - imports the latest version available of the other module, specifying - \c auto as version imports the same version as the version of this - module specified in the QML \c import statement. - - \row - \li - \code -# <Comment> - \endcode - \li Declares a comment. These are ignored by the engine. - - Example: - \code -# this is a comment - \endcode - - \row - \li - \code -designersupported - \endcode - - \li Set this property if the plugin is supported by Qt Quick Designer. - By default, the plugin will not be supported. - - A plugin that is supported by Qt Quick Designer has to be properly - tested. This means that the plugin does not crash when running inside - the qml2puppet that is used by Qt Quick Designer to execute QML. - Generally the plugin should work well in the Qt Quick Designer - and not cause any show stoppers, like taking huge amounts of memory, - slowing down the qml2puppet heavily or anything else that renders - the plugin effectively unusable in the Qt Quick Designer. - - The items of an unsupported plugin are not painted in the Qt Quick Designer, - but they are still available as empty boxes and the properties can be edited. - - \row - \li - \code -prefer <Path> - \endcode - - \li This property directs the QML engine to load any further files for this - module from <path>, rather than the current directory. This can be used - to load files compiled with qmlcachegen. - - For example, you can add a module's QML files as resources to a resource - path \c{:/my/path/MyModule/}. Then, add \c{prefer :/my/path/MyModule} to - the qmldir file in order to use the files in the resource system, rather - than the ones in the file system. If you then use qmlcachegen for those, - the pre-compiled files will be available to any clients of the module. - -\endtable - -Each command in a \c qmldir file must be on a separate line. +\section2 Module Identifier Declaration + +\code + module <ModuleIdentifier> +\endcode + +Declares the module identifier of the module. The <ModuleIdentifier> is the +(dotted URI notation) identifier for the module, which must match the module's +install path. + +The \l{Identified Modules#Semantics of Identified Modules} +{module identifier directive} must be the first line of the file. Exactly one +module identifier directive may exist in the \c qmldir file. + +Example: +\code + module ExampleModule +\endcode + +\section2 Object Type Declaration +\code + [singleton] <TypeName> <InitialVersion> <File> +\endcode + +Declares a \l{qtqml-typesystem-objecttypes.html}{QML object type} +to be made available by the module. +\list + \li \c [singleton] Optional. Used to declare a singleton type. + \li \c <TypeName> is the type being made available + \li \c <InitialVersion> is the module version for which the type is to be + made available + \li \c <File> is the (relative) file name of the QML file that defines + the type +\endlist + +Zero or more object type declarations may exist in the \c qmldir +file. However, each object type must have a unique type name within +any particular version of the module. +\note To declare a \c singleton type, the QML file defining the +type must include the \c {pragma Singleton} statement. + +Example: +\code + //Style.qml with custom singleton type definition + pragma Singleton + import QtQuick 2.0 + + QtObject { + property int textSize: 20 + property color textColor: "green" + } + + // qmldir declaring the singleton type + module CustomStyles + singleton Style 1.0 Style.qml + + // singleton type in use + import QtQuick 2.0 + import CustomStyles 1.0 + + Text { + font.pixelSize: Style.textSize + color: Style.textColor + text: "Hello World" + } +\endcode + +\section2 Internal Object Type Declaration + +\code + internal <TypeName> <File> +\endcode + +Declares an object type that is in the module but should not be +made available to users of the module. + +Zero or more internal object type declarations may exist in the +\c qmldir file. + +Example: +\code + internal MyPrivateType MyPrivateType.qml +\endcode + +This is necessary if the module is imported remotely +(see \l{Identified Modules#Remotely Installed Identified Modules} +{Remotely Installed Identified Modules}) because if an exported type depends +on a non-exported type within the module, the engine must also +load the non-exported type. + +\section2 JavaScript Resource Declaration + +\code + <ResourceIdentifier> <InitialVersion> <File> +\endcode + +Declares a JavaScript file to be made available by the module. +The resource will be made available via the specified identifier +with the specified version number. + +Zero or more JavaScript resource declarations may exist in the +\c qmldir file. However, each JavaScript resource must have a unique +identifier within any particular version of the module. + +Example: +\code + MyScript 1.0 MyScript.js +\endcode + +See the documentation about \l{qtqml-javascript-resources.html} +{defining JavaScript resources} and +\l{qtqml-javascript-imports.html} +{Importing JavaScript Resources In QML} for more information. + +\section2 Plugin Declaration + +\code + [optional] plugin <Name> [<Path>] +\endcode + +Declares a plugin to be made available by the module. + +\list + \li \c optional denotes that the plugin itself does not contain + any relevant code and only serves to load a library it links + to. If given, and if any types for the module are already + available, indicating that the library has been loaded by some + other means, QML will not load the plugin. + \li \c <Name> is the plugin library name. This is usually not the + same as the file name of the plugin binary, which is platform + dependent. For example, the library \c MyAppTypes would produce + \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows. + \li \c <Path> (optional) specifies either: + \list + \li an absolute path to the directory containing the plugin + file, or + \li a relative path from the directory containing the \c qmldir + file to the directory containing the plugin file. + \endlist +\endlist + +By default, the engine searches for the plugin library in the +directory that contains the \c qmldir file. (The plugin search +path can be queried with QQmlEngine::pluginPathList() and +modified using QQmlEngine::addPluginPath().) + +Zero or more C++ plugin declarations may exist in the \c qmldir +file. However, since plugin loading is a relatively expensive +operation, clients are advised to specify at most a single plugin. + +Example: +\code + plugin MyPluginLibrary +\endcode + +\section2 Plugin Classname Declaration + +\code + classname <C++ plugin class> +\endcode + +Provides the class name of the C++ plugin used by the module. + +This information is required for all the QML modules that depend +on a C++ plugin for additional functionality. Qt Quick applications +built with static linking cannot resolve the module imports without +this information. + +\section2 Type Description File Declaration + +\code + typeinfo <File> +\endcode + +Declares a \l{Type Description Files}{type description file} for +the module that can be read by QML tools such as Qt Creator to +access information about the types defined by the module's plugins. +\c <File> is the (relative) file name of a \c .qmltypes file. + +Example: +\code + typeinfo mymodule.qmltypes +\endcode + +Without such a file, QML tools may be unable to offer features such +as code completion for the types defined in your plugins. + +\section2 Module Dependencies Declaration + +\code + depends <ModuleIdentifier> <InitialVersion> +\endcode + +Declares that this module depends on another. + +Example: +\code + depends MyOtherModule 1.0 +\endcode + +This declaration is necessary only in cases when the dependency is +hidden: for example, when the C++ code for one module is used to +load QML (perhaps conditionally), which then depends on other +modules. In such cases, the \c depends declaration is necessary +to include the other modules in application packages. + +\section2 Module Import Declaration + +\code + import <ModuleIdentifier> [<Version>] +\endcode + +Declares that this module imports another. + +Example: +\code + import MyOtherModule 1.0 +\endcode + +The types from the other module are made available in the same type +namespace as this module is imported into. Omitting the version +imports the latest version available of the other module. Specifying +\c auto as version imports the same version as the version of this +module specified in the QML \c import statement. + +\section2 Designer Support Declaration + +\code + designersupported +\endcode + +Set this property if the plugin is supported by Qt Quick Designer. +By default, the plugin will not be supported. + +A plugin that is supported by Qt Quick Designer has to be properly +tested. This means that the plugin does not crash when running inside +the qml2puppet that is used by Qt Quick Designer to execute QML. +Generally, the plugin should work well in the Qt Quick Designer +and not cause any show stoppers, like taking excessive amounts of memory, +slowing down the qml2puppet heavily, or anything else that renders +the plugin effectively unusable in the Qt Quick Designer. + +The items of an unsupported plugin are not painted in the Qt Quick Designer, +but they are still available as empty boxes and the properties can be edited. + +\section2 Preferred Path Declaration + +\code + prefer <Path> +\endcode + +This property directs the QML engine to load any further files for this +module from <path>, rather than the current directory. This can be used +to load files compiled with qmlcachegen. + +For example, you can add a module's QML files as resources to a resource +path \c{:/my/path/MyModule/}. Then, add \c{prefer :/my/path/MyModule} to +the qmldir file in order to use the files in the resource system, rather +than the ones in the file system. If you then use qmlcachegen for those, +the pre-compiled files will be available to any clients of the module. \section1 Versioning Semantics @@ -434,7 +443,7 @@ documentation on this, no further action is needed. qmltyperegistrar will automatically generate the \c .qmltypes files. Example: -If your module is in \c /tmp/imports/My/Module, a file caled \c plugins.qmltypes +If your module is in \c /tmp/imports/My/Module, a file called \c plugins.qmltypes should be generated alongside the actual plugin binary. Add the line diff --git a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc index b1fce12dc3..834977994f 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc +++ b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc @@ -26,6 +26,14 @@ plugins. Library plugins should limit themselves to registering types, as any manipulation of the engine's root context may cause conflicts or other issues in the library user's code. +\note When using the CMake \l qt_add_qml_module API, a plugin will be generated +automatically for you. It will take care of type registration. +You only need to write a custom plugin if you have special +requirements, such as registering custom image +providers. In that case, pass +\l{NO_GENERATE_PLUGIN_SOURCE} to the \c qt_add_qml_module +call to disable the generation of the default plugin. + The linker might erroneously remove the generated type registration function as an optimization. You can prevent that by declaring a synthetic volatile pointer to the function somewhere in your code. If your module is diff --git a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc index 7ec8a4ff34..0623dd9934 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc @@ -109,6 +109,11 @@ a file system path. A directory of QML files can also be imported from a remote location if the directory contains a directory listing \c qmldir file. +\note This also holds for the implicit import of the directory a QML document +resides in. If your QML documents are loaded from a remote location, you need +to add qmldir files even if they don't contain any explicit directory import +statements. Otherwise your QML documents won't see each other. + For example, if the \c myapp directory in the previous example was hosted at "http://www.my-example-server.com", and the \c mycomponents directory contained a \c qmldir file defined as follows: diff --git a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc index ee104af29a..c17ced3601 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -305,8 +305,8 @@ default locations to be searched by the engine. By default, this list contains: Additional import paths can be added through QQmlEngine::addImportPath() or the \c QML_IMPORT_PATH environment variable. When running the -\l{Prototyping with qmlscene}{qmlscene} tool, you can also use the \c -I option -to add an import path. +\l {Prototyping with the QML Runtime Tool}{qml tool}, you can also use the +\c -I option to add an import path. You can specify multiple import paths in the \c QML_IMPORT_PATH environment variable by joining them using the path separator. On Windows the path separator diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc index 787e7b920b..8b3ff59ecc 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc @@ -56,6 +56,7 @@ The set of QML object-type attribute types is as follows: These attributes are discussed in detail below. \section2 The \e id Attribute +\keyword QML.id Every QML object type has exactly one \e id attribute. This attribute is provided by the language itself, and cannot be redefined or overridden by any @@ -686,8 +687,8 @@ 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++. +See \l{QQmlComponent::createWithInitialProperties}, \l{QQmlApplicationEngine::setInitialProperties} +and \l{QQuickView::setInitialProperties} for ways to initialize required properties from C++. \section3 Read-Only Properties @@ -730,6 +731,8 @@ with a particular property is as follows: } \endcode +This is commonly referred to as "on" syntax. + It is important to note that the above syntax is in fact an \l{qtqml-syntax-basics.html#object-declarations}{object declaration} which will instantiate an object which acts on a pre-existing property. diff --git a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc index 5716f6c386..6e94af6e41 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc @@ -267,38 +267,18 @@ property is only invoked when the property is reassigned to a different object v var urlObject = new URL(url); \endqml - \section1 Using the url Type - - When a relative URL is written to a \c url type property, it is converted - into a URL object, so \b {matching the URL value against the input string - value will fail}. Instead, convert the string to a URL using Qt.resolvedUrl() - for means of comparison, and use \c toString() to get the contents of the URL: - - \qml - Image { - source: "pics/logo.png" - - Component.onCompleted: { - // This prints 'false'. Although "pics/logo.png" was the input string, - // it's been converted from a string to a URL, so these two are not the same. - console.log(source == "pics/logo.png") - - // This prints 'true' as Qt.resovledUrl() converts the string into a - // URL with the correctly resolved path - console.log(source == Qt.resolvedUrl("pics/logo.png")) - - // This prints the absolute path, e.g. "file:///path/to/pics/logo.png" - console.log(source.toString()) - } - } - \endqml + \note In Qt 5, URLs were automatically resolved based on the current context + when assigning them to any \c url property. This made it impossible to + work with relative URLs and it created inconsistent behavior when reading + back a URL previously written to a property. Therefore, the behavior was + changed in Qt 6. \note When referring to files stored with the \l{resources.html}{Qt Resource System} from within QML, you should use "qrc:///" instead of ":/" as QML requires URL paths. Relative URLs resolved from within that file will use the same protocol. Additionally, URLs may contain encoded characters using the 'percent-encoding' scheme - specified by \l {http://tools.ietf.org/html/rfc3986}{RFC 3986}. These characters + specified by \l {https://datatracker.ietf.org/doc/html/rfc3986}{RFC 3986}. These characters will be preserved within properties of type \c url, to allow QML code to construct precise URL values. diff --git a/src/qml/doc/src/qmltypereference.qdoc b/src/qml/doc/src/qmltypereference.qdoc index 83544b1a66..a3df68b29b 100644 --- a/src/qml/doc/src/qmltypereference.qdoc +++ b/src/qml/doc/src/qmltypereference.qdoc @@ -26,7 +26,7 @@ ****************************************************************************/ /*! -\qmlmodule QtQml 2.\QtMinorVersion +\qmlmodule QtQml \title Qt QML QML Types \ingroup qmlmodules \brief List of QML types provided by the Qt QML module diff --git a/src/qml/doc/src/qt6-changes.qdoc b/src/qml/doc/src/qt6-changes.qdoc index 70c61849e7..9798718b96 100644 --- a/src/qml/doc/src/qt6-changes.qdoc +++ b/src/qml/doc/src/qt6-changes.qdoc @@ -213,8 +213,8 @@ engine.installTranslatorFunctions(); \newcode QJSEngine engine; - engine.installExtensions(QJSEngine::TranslationExtension - \endcode; + engine.installExtensions(QJSEngine::TranslationExtension); + \endcode \endlist diff --git a/src/qml/doc/src/qtqml-writing-a-module.qdoc b/src/qml/doc/src/qtqml-writing-a-module.qdoc new file mode 100644 index 0000000000..6ad820552e --- /dev/null +++ b/src/qml/doc/src/qtqml-writing-a-module.qdoc @@ -0,0 +1,289 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +/*! +\page qtqml-writing-a-module.html +\title Writing QML Modules +\brief How to write a custom QML module. + +You can declare a QML module using the \l{qt_add_qml_module} +{CMake QML Module API} to: + +\list +\li Generate \l {Module Definition qmldir Files}{qmldir} and + \l {Type Description Files}{*.qmltypes files}. +\li Register C++ types annotated with \l QML_ELEMENT. +\li Invoke \l {Ahead-of-Time-Compilation}{qmlcachegen}. +\li Provide modules both in the physical and in \l{The Qt Resource System} + {resource file system}. +\li Use the pre-compiled versions of QML files. +\li Bundle the module's files in the resource file system. +\li Combine QML files and C++-based types in the same module. +\li Create a backing library and an optional plugin. Link the backing library + into the application to avoid loading the plugin at run time. +\endlist + +All the above actions can also be configured separately. +For more information, see \l {qt_add_qml_module}{CMake QML Module API}. + +\section1 Multiple QML Modules in One Binary + +You can add multiple QML modules into the same binary. Define a CMake target for +each module and then link the targets to the executable. +If the extra targets are all static libraries, the result will be one binary, +which contains multiple QML modules. In short you can create an application +like this: + +\badcode +myProject + | - CMakeLists.txt + | - main.cpp + | - main.qml + | - onething.h + | - onething.cpp + | - ExtraModule + | - CMakeLists.txt + | - Extra.qml + | - extrathing.h + | - extrathing.cpp +\endcode + +To begin, let's assume main.qml contains an instantiation of Extra.qml: + + \badcode + import ExtraModule + Extra { ... } + \endcode + +The extra module has to be a static library so that you can link it +into the main program. Therefore, state as much in ExtraModule/CMakeLists.txt: + +\quotefromfile qml/CMakeLists.txt +\printuntil extrathing.h +\printuntil ) + +This generates two targets: \c extra_module for the backing library, and +\c extra_moduleplugin for the plugin. Being a static library too, the plugin cannot +be loaded at runtime. + +In myProject/CMakeLists.txt you need to specify the QML module that main.qml +and any types declared in onething.h are part of: + +\quotefromfile qml/myProject-CMakeLists.txt +\printuntil onething.h +\printuntil ) + + +From there, you add the subdirectory for the extra module: + +\quotefromfile qml/CMakeLists.txt +\skipto add_subdirectory +\printuntil ) + +To ensure that linking the extra module works correctly, you need to: + +\list +\li Define a symbol in the extra module. +\li Create a reference to the symbol from the main program. +\endlist + +QML plugins contain a symbol you can use for this purpose. +You can use the \l Q_IMPORT_QML_PLUGIN macro to create a reference to this symbol. +Add the following code to the main.cpp: + +\badcode +#include <QtQml/qqmlextensionplugin.h> +Q_IMPORT_QML_PLUGIN(ExtraModulePlugin) +\endcode + +\c ExtraModulePlugin is the name of the generated plugin class. It's composed +of the module URI with \c Plugin appended to it. Then, in the main program's +CMakeLists.txt, link the plugin, not the backing library, into the main program: + +\quotefromfile qml/myProject-CMakeLists.txt +\skipto target_link_libraries +\printuntil ) + +\section1 Exporting Multiple Major Versions from The Same Module + +\l qt_add_qml_module by default considers the major version given in its +URI argument, even if the individual types declare other versions in their +added specific version via \l QT_QML_SOURCE_VERSIONS or \l Q_REVISION. +If a module is available under more than one version, you also need to decide +what versions the individual QML files are available under. To declare further +major versions, you can use the \c PAST_MAJOR_VERSIONS option to +\c qt_add_qml_module as well as the \c {QT_QML_SOURCE_VERSIONS} property on +individual QML files. + +\quotefile qml/MajorProject-CMakeLists.txt + +\c MyModule is available in major versions 1, 2, and 3. The maximum version +available is 3.2. You can import any version 1.x or 2.x with a positive x. For +Thing.qml and OtherThing.qml we have added explicit version information. +Thing.qml is available from version 1.4, and OtherThing.qml is available from +version 2.2. You have to specify the later versions, too, in each +\c set_source_files_properties() because you may remove QML files +from a module when bumping the major version. There is no explicit version +information for OneMoreThing.qml. This means that OneMoreThing.qml is available +in all major versions, from minor version 0. + +With this setup, the generated registration code will register the module +\c versionsqmlRegisterModule() for each of the major versions. This way, all +versions can be imported. + + +\section1 Custom Directory Layouts + +The easiest way to structure QML modules is to keep them in directories named by +their URIs. For example, a module My.Extra.Module would live in a directory +My/Extra/Module relative to the application that uses it. This way, they can +easily be found at run time and by any tools. + +In more complex projects, this convention can be too limiting. You might for +instance want to group all QML modules in one place to avoid polluting the +project's root directory. Or you want to reuse a single module in multiple +applications. For those cases, \c QT_QML_OUTPUT_DIRECTORY in combination with +\c RESOURCE_PREFIX and \l IMPORT_PATH can be used. + +To collect QML modules into a specific output directory, for example a +subdirectory "qml" in the build directory \l QT_QML_OUTPUT_DIRECTORY, set the +following in the top-level CMakeLists.txt: + +\badcode +set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/qml) +\endcode + +The output directories of QML modules move to the new location. +Likewise, the \c qmllint and \c qmlcachegen invocations are automatically +adapted to use the new output directory as an \l {QML Import Path}{import path}. +Because the new output directory is not part of the default QML import path, +you have to add it explicitly at run time, so that the QML modules can be found. + + +Now that the physical file system is taken care of, you may still want to move +the QML modules into a different place in the resource file system. This is what +the RESOURCE_PREFIX option is for. You have to specify it separately in +each \l qt_add_qml_module. The QML module will then be placed under the specified +prefix, with a target path generated from the URI appended. For example, +consider the following module: + +\code +qt_add_qml_module( + URI My.Great.Module + VERSION 1.0 + RESOURCE_PREFIX /example.com/qml + QML_FILES + A.qml + B.qml +) +\endcode + +This will add a directory \c example.com/qml/My/Great/Module to the resource file +system and place the QML module defined above in it. You don't strictly need to +add the resource prefix to the QML import path as the module can still be found +in the physical file system. However, it generally is a good idea to add the +resource prefix to the QML import path because loading from the resource file +system is faster than loading from the physical file system for most modules. + +If the QML modules are meant to be used in a larger project with multiple import +paths, you'll have to do an additional step: Even if you add the import paths at +run time, tooling like \c qmllint does not have access to it, and might fail to +find the correct dependencies. Use \c IMPORT_PATH to tell tooling about the +additional paths it has to consider. For example: + +\badcode +qt_add_qml_module( + URI My.Dependent.Module + VERSION 1.0 + QML_FILES + C.qml + IMPORT_PATH "/some/where/else" +) +\endcode + +\section1 Eliminating Run Time File System Access + +If all QML modules are always loaded from the resource +file system, you can deploy the application as a single binary. Let's first +consider the simple case: + +\badcode +QQmlEngine qmlEngine; +qmlEngine.addImportPath(QStringLiteral(":/")); +// Use qmlEngine to load the main.qml file. +\endcode + +\note ":/" is used for simplicity here. See \l {Custom Directory Layouts} +for more complex cases. + +If all the modules are linked into the application and if you're following +the default resource directory structure, do not add any further import paths as +those might override the one you added. + +If you have specified a custom \c RESOURCE_PREFIX, you have to add the custom +resource prefix to the import path instead. You can also add multiple resource +prefixes. + +The path \c :/qt-project.org/imports/ is part of the default QML import path. If +you use it, you don't have to specially add it. Qt's own QML modules are placed +there, though. You have to be careful not to overwrite them. For modules that are +heavily re-used across different projects \c :/qt-project.org/imports/ is +acceptable. By using it you can avoid forcing all the users to add custom +import paths. + +\section1 Integrating custom QML plugins + +If you bundle an \l {QQuickImageProvider}{image provider} in the QML module, you +need to implement the \l {QQmlEngineExtensionPlugin::initializeEngine()} +method. This, in turn, makes it necessary to write the own plugin. To support +this use case, \l NO_GENERATE_PLUGIN_SOURCE can be used. + +Let's consider a module that provides its own plugin source: + +\quotefile qml/myimageprovider.txt + +You may declare an image provider in myimageprovider.h, like this: + +\badcode +class MyImageProvider : public QQuickImageProvider +{ + [...] +}; +\endcode + +In plugin.cpp you can then define the QQmlEngineExtensionPlugin: + +\quotefile qml/plugin.cpp.txt + +This will make the image provider available. The plugin and the backing library +both are in the same CMake target imageproviderplugin. This is done so that the +linker does not drop parts of the module in various scenarios. + +As the plugin creates an image provider, it no longer has a trivial +\c initializeEngine function. Therefore, the plugin is no longer optional. + +*/ diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc index e1ff693195..9f26c9328b 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -132,8 +132,14 @@ The QML framework allows QML code to contain JavaScript expressions and for the QML code to interact with C++ code. \list -\li \l{Important C++ Classes Provided By The Qt QML Module} -\li \l{Integrating QML and C++} + \li \l {Overview - QML and C++ Integration} + \li \l {Data Type Conversion Between QML and C++} + \li \l {Integrating with JavaScript values from C++} + \li \l {Exposing Attributes of C++ Types to QML} + \li \l {Defining QML Types from C++} + \li \l {Writing QML Modules} + \li \l {Important C++ Classes Provided By The Qt QML Module} + \li \l {Integrating QML and C++} \endlist \omit |