diff options
Diffstat (limited to 'src/qml/doc/src')
132 files changed, 12313 insertions, 3723 deletions
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..a2ca59efc8 --- /dev/null +++ b/src/qml/doc/src/cmake/cmake-properties.qdoc @@ -0,0 +1,229 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group cmake-global-properties-qtqml +\title CMake Global Properties in Qt6 Qml + +\l{CMake Command Reference#Qt6::Qml}{CMake Commands} know about the following +global CMake properties: + +\sa{CMake Property Reference} +*/ + + +/*! +\page cmake-global-property-qt-qmllinter-targets-folder.html +\ingroup cmake-properties-qtqml +\ingroup cmake-global-properties-qtqml + +\title QT_QMLLINTER_TARGETS_FOLDER + +\brief Sets the FOLDER property for targets that belong to the QML linter. + +\cmakepropertysince 6.5 +\preliminarycmakeproperty + +Name of the \l FOLDER for targets that are related to the QML linter. + +By default, this property is set to \c{QmlLinter}. + +This property only has an effect if CMake's \l USE_FOLDERS property is \c{ON}. + +You can enable folder support by calling +\l{qt6_standard_project_setup}{qt_standard_project_setup}. +*/ + + +/*! +\group cmake-source-file-properties-qtqml +\title CMake Source File Properties in Qt6 Qml + +\l{CMake Command Reference#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 + +\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 + +\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. +The source property must be set before \l{qt_add_qml_module}{creating} the module the +singleton belongs to. + +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 + +\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 + +\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 + +\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 + +\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 + +\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 + +\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{qmltc-cmake} +*/ + +/*! +\page cmake-source-file-property-qt-qml-skip-type-compiler.html +\ingroup cmake-source-file-properties-qtqml + +\title QT_QML_SKIP_TYPE_COMPILER + +\summary {Excludes a file from being compiled to C++ using qmltc.} + +\cmakepropertysince 6.4 +\preliminarycmakeproperty + +Set this property to \c TRUE to prevent the \c{.qml} file from being compiled to +C++ during qmltc compilation. + +\sa{qmltc-cmake} +*/ + +/*! +\page cmake-source-file-property-qt-qml-generate-java-class.html +\ingroup cmake-source-file-properties-qtqml +\ingroup cmake-android-build-properties + +\title QT_QML_GENERATE_JAVA_CLASS + +\summary {Marks a QML file for Java code generation.} + +\cmakepropertysince 6.8 +When using QML as a \l {Android: View} in Android via \l QtQuickView, you can choose +the QML components to make available as generated Java classes usable from Android code. +To mark a \c {.qml} file for code generation, set its \c QT_QML_GENERATE_JAVA_CLASS +source property to \c TRUE. The source property must be set before +\l {qt_add_qml_module}{creating} the module. The file should start with an uppercase +letter and define a QML component. This property is valid only if +\l QT_ANDROID_GENERATE_JAVA_QML_COMPONENTS is defined. + +\sa {Naming Custom QML Object Types} +*/ diff --git a/src/qml/doc/src/cmake/cmake-variables.qdoc b/src/qml/doc/src/cmake/cmake-variables.qdoc new file mode 100644 index 0000000000..de984c88ef --- /dev/null +++ b/src/qml/doc/src/cmake/cmake-variables.qdoc @@ -0,0 +1,76 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group cmake-variables-qtqml +\title CMake Global Variables in Qt6 Qml + +\l{CMake Command Reference#Qt6::Qml}{CMake Commands} know about the following +global CMake variables: + +*/ + +/*! +\page cmake-variable-qt-qml-output-directory.html +\ingroup cmake-variables-qtqml + +\title QT_QML_OUTPUT_DIRECTORY + +\brief Base output directory below which QML modules will be created by default. + +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. 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. +*/ + +/*! +\page cmake-variable-qt-qml-generate-qmlls-ini.html +\ingroup cmake-variables-qtqml + +\title QT_QML_GENERATE_QMLLS_INI + +\brief Enables autogeneration of .qmlls.ini files for \QMLLS. +\cmakevariablesince 6.7 + +\c QT_QML_GENERATE_QMLLS_INI is a boolean that describes whether +\l{qt6_add_qml_module}{qt6_add_qml_module()} calls generate \c{.qmlls.ini} files inside +the \b{source folder}, into each subdirectory with a CMakeLists.txt file creating a QML module. +If \c{.qmlls.ini} files already exist there, then they are overwritten. + +\note Using \c QT_QML_GENERATE_QMLLS_INI requires a CMake version >= 3.19. + +These \c{.qmlls.ini} files contain the path to the last configured build directory, +and is needed by \l{\QMLLS Reference}{\QMLLS} to find user defined modules. See also +\l{\QMLLS Reference}{\QMLLS} about the other ways of passing build folders to \QMLLS. + + +As this variable is used for IDE integration, it should normally not be set in a project itself, but +passed to CMake via an IDE or manually by passing +\badcode +-DQT_QML_GENERATE_QMLLS_INI=ON +\endcode +to the cmake executable. + +\warning The files generated by \c QT_QML_GENERATE_QMLLS_INI are only valid for the current +configuration and should be ignored by your version control system. For Git, add \tt{**\/.qmlls.ini} +to your top-level project \c{.gitignore}, for example. +The globbing is required because .qmlls.ini files are generated in \e{all source +subdirectories} that define QML Modules. + +*/ + + diff --git a/src/qml/doc/src/cmake/policy/qtp0001.qdoc b/src/qml/doc/src/cmake/policy/qtp0001.qdoc new file mode 100644 index 0000000000..a4e54ed1ae --- /dev/null +++ b/src/qml/doc/src/cmake/policy/qtp0001.qdoc @@ -0,0 +1,39 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0001.html +\ingroup qt-cmake-policies + +\title QTP0001 +\keyword qt_cmake_policy_qtp0001 + +\summary {':/qt/qml/' is the default resource prefix for QML modules.} + +This policy was introduced in Qt 6.5. It changes where +\l{qt_add_qml_module}{qt_add_qml_module()} stores QML resources in +the resource system. + +Enabling this policy ensures that your QML module is placed under +a default \l {QML Import Path}{import path}, and its types can be +found without manual calls to \l QQmlEngine::addImportPath. + +The \c OLD behavior of this policy is that, the \c RESOURCE_PREFIX argument for +\c{qt_add_qml_module()} defaults to \c{":/"}. + +The \c NEW behavior of this policy is that the \c RESOURCE_PREFIX argument +for \c{qt_add_qml_module()} defaults to \c{":/qt/qml/"}. The new behavior +ensures that modules are put into the \l{QML Import Path} and can be +found without further setup. + +Qt 6.5 issues warnings if you do not pass any of the following arguments to the +\c qt_add_qml_module command: \c RESOURCE_PREFIX, \c NO_RESOURCE_TARGET_PATH. +Use the \l qt_policy command to suppress the warning by explicitly setting +the policy to \c OLD or \c NEW. + +\qtpolicydeprecatedbehavior + +\sa qt_policy, {qt6_standard_project_setup}{qt_standard_project_setup()}, + qt_cmake_policies, qt_add_qml_module + +*/ diff --git a/src/qml/doc/src/cmake/policy/qtp0004.qdoc b/src/qml/doc/src/cmake/policy/qtp0004.qdoc new file mode 100644 index 0000000000..9d3428e52b --- /dev/null +++ b/src/qml/doc/src/cmake/policy/qtp0004.qdoc @@ -0,0 +1,34 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0004.html +\ingroup qt-cmake-policies + +\title QTP0004 +\keyword qt_cmake_policy_qtp0004 + +\summary {Extra directories with QML files in a QML module need extra qmldir files.} + +This policy was introduced in Qt 6.8. It causes the build system to generate +an extra qmldir file for each additional directory that contains QML files in +a QML module. + +Enabling this policy ensures that the implicit import of each of the QML +components in your module is the same as the module itself. This means that +all the components can see each other without explicitly importing the module. + +The \c OLD behavior of this policy is that a qmldir file is only generated for +the root directory of a module. + +The \c NEW behavior of this policy is that for each directory with QML files in +a module a separate qmldir file is generated. + +Qt 6.8 issues warnings if you do not explicitly set the policy. + +\qtpolicydeprecatedbehavior + +\sa qt_policy, {qt6_standard_project_setup}{qt_standard_project_setup()}, + qt_cmake_policies, qt_add_qml_module + +*/ diff --git a/src/qml/doc/src/cmake/policy/qtp0005.qdoc b/src/qml/doc/src/cmake/policy/qtp0005.qdoc new file mode 100644 index 0000000000..25d5175789 --- /dev/null +++ b/src/qml/doc/src/cmake/policy/qtp0005.qdoc @@ -0,0 +1,42 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0005.html +\ingroup qt-cmake-policies + +\title QTP0005 +\keyword qt_cmake_policy_qtp0005 + +\summary {qt_add_qml_module's DEPENDENCIES argument accepts targets} + +This policy was introduced in Qt 6.8. It allows passing targets to +\l{qt_add_qml_module}{qt_add_qml_module()} \c DEPENDENCIES, \c IMPORTS, \c +OPTIONAL_IMPORTS and \c DEFAULT_IMPORTS. + +Enabling this policy means that the arguments which are passed to the key words +can be prefixed with TARGET, and are then treated as a target name. + +The \c OLD behavior of this policy is that the "TARGET name" is treated as two +URIs, "TARGET" and "name". + +The \c NEW behavior of this policy is that \c TARGET is considered a keyword, +and the URI is extracted from the target which follows next. It is a hard error +if the name following \c TARGET does not name a target, or if that target does +not correspond to a QML module. + +In both the \c NEW and the \c OLD behavior it is possible to specify a module +version by appending a slash and the version. See +\l{Declaring module dependencies} for more details. + +Qt 6.8 issues warnings if you pass a URI to \c DEPENDENCIES which coincides +with a target name. +Use the \l qt_policy command to suppress the warning by explicitly setting +the policy to \c OLD or \c NEW. + +\qtpolicydeprecatedbehavior + +\sa qt_policy, {qt6_standard_project_setup}{qt_standard_project_setup()}, + qt_cmake_policies, qt_add_qml_module + +*/ diff --git a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc new file mode 100644 index 0000000000..63f9707d4d --- /dev/null +++ b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc @@ -0,0 +1,762 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-qml-module.html +\ingroup cmake-commands-qtqml + +\title qt_add_qml_module +\target qt6_add_qml_module + +\brief Defines a QML module. + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +qt_add_qml_module( + target + URI uri + [VERSION version] + [PAST_MAJOR_VERSIONS ...] + [STATIC | SHARED] + [PLUGIN_TARGET plugin_target] + [OUTPUT_DIRECTORY output_dir] + [RESOURCE_PREFIX resource_prefix] + [CLASS_NAME class_name] + [TYPEINFO typeinfo] + [IMPORTS ...] + [OPTIONAL_IMPORTS ...] + [DEFAULT_IMPORTS ...] + [DEPENDENCIES ...] + [IMPORT_PATH ...] + [SOURCES ...] + [QML_FILES ...] + [RESOURCES ...] + [OUTPUT_TARGETS out_targets_var] + [DESIGNER_SUPPORTED] + [FOLLOW_FOREIGN_VERSIONING] + [NAMESPACE namespace] + [NO_PLUGIN] + [NO_PLUGIN_OPTIONAL] + [NO_CREATE_PLUGIN_TARGET] + [NO_GENERATE_PLUGIN_SOURCE] + [NO_GENERATE_QMLTYPES] + [NO_GENERATE_QMLDIR] + [NO_LINT] + [NO_CACHEGEN] + [NO_RESOURCE_TARGET_PATH] + [NO_IMPORT_SCAN] + [ENABLE_TYPE_COMPILER] + [TYPE_COMPILER_NAMESPACE namespace] + [QMLTC_EXPORT_DIRECTIVE export_macro] + [QMLTC_EXPORT_FILE_NAME header_defining_export_macro] + +) + +\endcode + +\versionlessCMakeCommandsNote qt6_add_qml_module() + +See \l {Building a QML application} and \l {Building a reusable QML module} +for examples that define QML modules. + +See \l {QT_QML_GENERATE_QMLLS_INI} for configuring your project such that information about +QML modules is exposed to the \l{QML Language Server}. + +\section1 Description + +This command defines a QML module that can consist of C++ sources, \c{.qml} +files, or both. It ensures that essential module details are provided and that +they are consistent. It also sets up and coordinates things like cached +compilation of \c{.qml} sources, resource embedding, linting checks, and +auto-generation of some key module files. + +\section2 Target Structure + +A QML module can be structured in a few different ways. The following scenarios +are the typical arrangements: + +\section3 Separate backing and plugin targets + +This is the recommended arrangement for most QML modules. All of the module's +functionality is implemented in the \e backing target, which is given as the +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 +normally installed to the same directory as the module's +\l{Module Definition qmldir Files}{qmldir} file. + +The plugin target should ideally contain nothing more than a trivial +implementation of the plugin class. This allows the plugin to be designated as +optional in the \c qmldir file. Other targets can then link directly to the +backing target and the plugin will not be needed at runtime, which can improve +load-time performance. By default, a C++ source file that defines a minimal +plugin class will be automatically generated and added to the plugin target. +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. + +The \c STATIC QML modules also generate the static QML plugins if +\c NO_PLUGIN is not specified. Targets that import such \c STATIC QML modules +also need to explicitly link to corresponding QML plugins. + +\note +When using static linking, it might be necessary to use +\l {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 +target. In this case, the module must be loaded dynamically at runtime and +cannot be linked to directly by other targets. To create this arrangement, +the \c PLUGIN_TARGET keyword must be used, with the \c target repeated as the +plugin target name. For example: + +\badcode +qt_add_qml_module(someTarget + PLUGIN_TARGET someTarget + ... +) +\endcode + +While this arrangement may seem marginally simpler to deploy, a separate +backing target should be preferred where possible due to the potentially better +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 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 +\section2 Auto-generating \c{qmldir} and typeinfo files + +By default, a \l{Module Definition qmldir Files}{qmldir} file and a typeinfo +file will be auto-generated for the QML module being defined. The contents of +those files are determined by the various arguments given to this command, as +well as the sources and \c{.qml} files added to the backing target. +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. + +If \l{QTP0004} policy is set to \c NEW, for each further directory that contains +\c{.qml} files another \c qmldir file is generated. These extra \c qmldir files +merely redirect to the module's base directory via a \c prefer directive. This +is so that all the QML components in a module can access each other, no matter +which directory they are stored in. + +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 to set up linking relationships (the \c{NO_IMPORT_SCAN} keyword +can be given to disable this). 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 +susceptibility to errors that hand-written files do. Nevertheless, for +situations where the project needs to provide these files itself, the +auto-generation can be disabled. The \c NO_GENERATE_QMLDIR option disables the +\c qmldir auto-generation and the \c NO_GENERATE_QMLTYPES option disables the +typeinfo and C++ type registration auto-generation. If the auto-generated +typeinfo file is acceptable, but the project wants to use a different name for +that file, it can override the default name with the \c TYPEINFO option (but +this should not typically be needed). + +\target qmlcachegen-auto +\section2 Caching compiled QML sources + +All \c{.qml}, \c{.js}, and \c{.mjs} files added to the module via the +\c QML_FILES argument will be compiled to bytecode and cached directly in the +backing target. This improves load-time performance of the module. The original +uncompiled files are also stored in the backing target's resources, as these +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 (but see \l NO_RESOURCE_TARGET_PATH for an exception to this). + +If \l{QTP0001} policy is set to \c NEW, the \l{RESOURCE_PREFIX} defaults +to \c{/qt/qml/} which is the default import path of the QML engine. +This ensures that modules are put into the \l{QML Import Path} and can be +found without further setup. + +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 +location in the resources needs to be explicitly specified. This is done by +setting the \c QT_RESOURCE_ALIAS source file property, which must be set before +the \c{.qml} file is added. For example: + +\badcode +set_source_files_properties(path/to/somewhere/MyFrame.qml PROPERTIES + QT_RESOURCE_ALIAS MyFrame.qml +) + +qt_add_qml_module(someTarget + URI MyCo.Frames + RESOURCE_PREFIX /my.company.com/imports + QML_FILES + path/to/somewhere/MyFrame.qml + AnotherFrame.qml +) +\endcode + +In the above example, the target path will be \c{MyCo/Frames}. After +taking into account the source file properties, the two \c{.qml} files will be +found at the following resource paths: + +\list +\li \c{/my.company.com/imports/MyCo/Frames/MyFrame.qml} +\li \c{/my.company.com/imports/MyCo/Frames/AnotherFrame.qml} +\endlist + +In the rare case that you want to override the automatic selection of the +qmlcachegen program to be used, you may set the \c QT_QMLCACHEGEN_EXECUTABLE +target property on the module target. For example: + +\badcode +set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_EXECUTABLE qmlcachegen +) +\endcode + +This explicitly selects qmlcachegen as the program to be used, even if +better alternatives are available. + +Furthermore, you can pass extra arguments to qmlcachegen, by setting the +\c QT_QMLCACHEGEN_ARGUMENTS option. In particular, the \c --only-bytecode +option will turn off compilation of QML script code to C++. For example: + +\badcode +set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--only-bytecode" +) +\endcode + +Another important argument is \c{--direct-calls}. You can use it to enable the +direct mode of \l{The QML script compiler} in case the Qt Quick Compiler +Extensions are installed. If the extensions are not installed, the argument is +ignored. There is a shorthand called \c {QT_QMLCACHEGEN_DIRECT_CALLS} for it. + +\badcode +set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_DIRECT_CALLS ON +) +\endcode + +Finally, the \c --verbose argument can be used to see diagnostic output from +qmlcachegen: + +\badcode +set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--verbose" +) +\endcode + +With this flag set, qmlcachegen will output warnings for each function it +cannot compile to C++. Some of these warnings will point to problems in your +QML code and some will tell you that certain features of the QML language are +not implemented in the C++ code generator. In both cases, qmlcachegen will +still generate byte code for such functions. If you want to see only the +problems in your QML code, you should use qmllint and the targets generated +for it instead. + +\target qmllint-auto +\section2 Linting QML sources + +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}. 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 QT_QML_SOURCE_TYPENAME 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 \c 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. +The source property must be set before creating the module the +singleton belongs to. + +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. + +\target qmltc-cmake +\section2 Compiling QML to C++ with QML type compiler + +\note The \l{QML type compiler} \c{qmltc} does not guarantee that the generated +C++ stays API-, source- or binary-compatible between past or future versions, +even patch versions. +Furthermore, qmltc-compiled apps using Qt's QML modules will require linking +against private Qt API, see also +\l{QML type compiler#compiling-qml-code-with-qmltc}{Compiling QML code with qmltc}. + + +If a QML module has \c{.qml} files, you can compile them to C++ using \l{QML +type compiler}{qmltc}. Unlike \l{qmlcachegen-auto}{bytecode compilation}, you +have to explicitly enable qmltc via \l{ENABLE_TYPE_COMPILER} argument. In which +case, \c{.qml} files specified under \c{QML_FILES} would be compiled. Files +ending with \c{.js} and \c{.mjs} are ignored as qmltc does not compile +JavaScript code. Additionally, files marked with QT_QML_SKIP_TYPE_COMPILER +source file property are also skipped. + +By default, qmltc creates lower-case \c{.h} and \c{.cpp} files for a given +\c{.qml} file. For example, \c{Foo.qml} ends up being compiled into \c{foo.h} +and \c{foo.cpp}. + +The created C++ files are placed into a dedicated \c{.qmltc/<target>/} +sub-directory of the \c BINARY_DIR of the \c target. These files are then +automatically added to the target sources and compiled as Qt C++ code along with +other source files. + +While processing QML_FILES, the following source file properties are respected: +\list + \li \c{QT_QMLTC_FILE_BASENAME}: use this source file property to specify a + non-default .h and .cpp file name, which might be useful to e.g. resolve + conflicting file names (imagine you have main.qml that is being + compiled, but main.h already exists, so #include "main.h" might not do + what you expect it to do). QT_QMLTC_FILE_BASENAME is expected to be a + file name (without extension), so any preceding directory is ignored. + Unlike in the case of default behavior, the QT_QMLTC_FILE_BASENAME is + not lower-cased. + \li \c{QT_QML_SKIP_TYPE_COMPILER}: use this source file property to + specify that a QML file must be ignored by qmltc. +\endlist + +\section1 Arguments + +\section2 Required arguments + +The \c target specifies the name of the backing target for the QML module. +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. + +Every QML module must define a \c URI. It should be specified in dotted URI +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 +form the \e{target path} by replacing dots with forward slashes. + +See \l{qtqml-modules-identifiedmodules.html}{Identified Modules} for further +in-depth discussion of the module URI. + +\section2 Versions + +A QML module can 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 (see below). +See \l{qtqml-modules-identifiedmodules.html}{Identified Modules} for further +in-depth discussion of version numbering, +\l{Registering past major versions} for registering past major versions, and +\l{Keeping module versions in sync} for keeping module versions in sync. + +If you don't need versions you should omit the \c VERSION argument. It defaults +to the highest possible version. Internal versioning of QML modules has some +fundamental flaws. You should use an external package management mechanism to +manage different versions of your QML modules. + +\section2 Adding sources and resources to the module + +\c SOURCES specifies a list of non-QML sources to be added to the backing +target. It is provided as a convenience and is equivalent to adding the sources +to the backing target with the built-in \c{target_sources()} CMake command. + +\c QML_FILES lists the \c{.qml}, \c{.js} and \c{.mjs} files for the module. +These will be automatically \l{qmlcachegen-auto}{compiled into bytecode} and +embedded in the backing target unless the \c NO_CACHEGEN option is given. +The uncompiled file is always stored in the embedded resources of the backing +target, even if \c NO_CACHEGEN is specified. Unless the \c NO_LINT option is +given, the uncompiled files will also be +\l{Linting QML sources}{processed by \c qmllint} via a separate custom build +target. The files will also be used to populate type information in the +generated \l{Module Definition qmldir Files}{qmldir} file by default. +\c NO_GENERATE_QMLDIR can be given to disable the automatic generation of the +\c qmldir file. This should normally be avoided, but for cases where the +project needs to provide its own \c qmldir file, this option can be used. + +\note See \l{qt6_target_qml_sources}{qt_target_qml_sources()} for further details on +how to add qmlfiles after \c qt_add_qml_module() was called. +For example, you may wish to add files conditionally based on an if statement +expression, or from subdirectories that will only be added if certain criteria +are met. +Furthermore, files added with \l{qt6_target_qml_sources}{qt_target_qml_sources()} +also can specify if they should be skipped for the linting, +\l{qmlcachegen-auto}{bytecode compilation} or \c qmldir file generation. + +\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 (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}). + +\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 +be chosen to avoid clashing with the resource prefix of anything else used by +the project or likely to be used by any other project that might consume it. +A good choice is to incorporate the domain name of the organization the project +belongs to. A common convention is to append \c{/imports} to the domain name to +form the resource prefix. For example: + +\badcode +qt_add_qml_module(someTarget + RESOURCE_PREFIX /my.company.com/imports + ... +) +\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 PAST_MAJOR_VERSIONS +\section2 Registering past major versions + +\c PAST_MAJOR_VERSIONS contains a list of additional major version that the module +provides. 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. + +\section2 Declaring module dependencies + +\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 +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 +engine when importing the current module, but rather serve as hints to tools +like \c qmllint. Versions can be specified in the same way as for \c IMPORTS. +Each module listed here will be added as an \c{optional import} entry in the +generated \l{Module Definition qmldir Files}{qmldir} file. + +\c DEFAULT_IMPORTS specifies which of the optional imports are the default entries +that should be loaded by tooling. One entry should be specified for every group of +\c OPTIONAL_IMPORTS in the module. As optional imports are only resolved at runtime, +tooling like qmllint cannot in general know which of the optional imports should +be resolved. To remedy this, you can specify one of the optional imports as the +default import; tooling will then pick it. If you have one optional import that +gets used at runtime without any further configuration, that is an ideal candidate +for the default import. + +\c DEPENDENCIES provides a list of other QML modules that this module depends +on, but doesn't necessarily import. It would typically be used for dependencies +that only exist at the C++ level, such as a module registering a class to QML +which is a subclass of one defined in another module. + +For example, if one would like to subclass \c QQuickItem as following: + +\badcode +class MyItem: public QQuickItem { ... }; +\endcode + +then one has to make sure that the module containing \c QQuickItem, called +\c Quick, is declared as a dependency via the \c DEPENDENCIES option. Not doing +so might result in errors during type compilation with +\l{QML type compiler}{qmltc} or during binding and function compilation to C++ +with \l{qmlcachegen-auto}{qmlcachegen}. + +\note Adding the module to \c DEPENDENCIES is not necessary if the module +is already imported via the \c IMPORTS option. The recommended way is to +use the lighter alternative \c DEPENDENCIES over \c IMPORTS. + +The module version of the +dependencies must be specified along with the module name, in the same form as +used for \c IMPORTS and \c OPTIONAL_IMPORTS. Each module listed here will be +added as a \c{depends} entry in the generated +\l{Module Definition qmldir Files}{qmldir} file. + +\target IMPORT_PATH +\c IMPORT_PATH can be used to add to the search paths where other QML modules +that this one depends on can be found. The other modules must have their +\c qmldir file under their own target path below one of the search paths. + +If the backing target is a static library and that static library will be +installed, \c OUTPUT_TARGETS should be given to provide a variable in which to +store a list of additional targets that will also need to be installed. +These additional targets are generated internally by \c{qt_add_qml_module()} +and are referenced by the backing target's linking requirements as part of +ensuring that resources are set up and loaded correctly. + +\note Since Qt 6.8, it is possible to pass a target name to IMPORTS and +DEPENDENCIES. See \l{QTP0005} for more details. + +\target PLUGIN_TARGET +\section2 Targets and plugin targets + +\c PLUGIN_TARGET specifies the plugin target associated with the QML module. +The \c PLUGIN_TARGET can be the same as the backing +\c target, in which case there will be no separate backing target. +If \c PLUGIN_TARGET is not given, it defaults to \c target with \c plugin +appended. For example, a backing target called \c mymodule would have a default +plugin name of \c mymoduleplugin. The plugin target's name will be used to +populate a \c{plugin} line in the generated +\l{Module Definition qmldir Files}{qmldir} file. Therefore, you must not try to +change the plugin's output name by setting target properties like +\c OUTPUT_NAME or any of its related properties. + +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 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. + +\target NO_CREATE_PLUGIN_TARGET +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. When \c NO_CREATE_PLUGIN_TARGET is given, \c PLUGIN_TARGET must +also be provided to explicitly name the plugin target. + +\target CLASS_NAME +\target NO_GENERATE_PLUGIN_SOURCE +By default, \c{qt_add_qml_module()} will auto-generate a \c{.cpp} file that +implements the plugin class named by the \c CLASS_NAME argument. The generated +\c{.cpp} file will be automatically added to the plugin target as a source file +to be compiled. If the project wants to provide its own implementation of the +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. 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 +the generated \c qmldir file as non-optional. If all of a QML module's +functionality is implemented in its backing target and the plugin target is +separate, then the plugin can be optional, which is the default and recommended +arrangement. The auto-generated plugin source file satisfies this requirement. +Where a project provides its own \c{.cpp} implementation for the plugin, that +would normally mean the \c NO_PLUGIN_OPTIONAL keyword is also needed because +the plugin will almost certainly contain functionality that the QML module +requires. + +\section2 Automatic type registration + +Type registration is automatically performed for the backing target's C++ +sources that are processed by AUTOMOC. This will generate a typeinfo file in the +\l{OUTPUT_DIRECTORY}{output directory}, the file name being the \c target name +with \c{.qmltypes} appended. This file name can be changed using the +\c TYPEINFO option if desired, but this should not normally be necessary. +The file name is also recorded as a \c typeinfo entry in the generated +\l{Module Definition qmldir Files}{qmldir} file. Automatic type registration +can be disabled using the \c NO_GENERATE_QMLTYPES option, in which case no +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. + +\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, 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. 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, +\l{qt6_import_qml_plugins}{automatic importing} of plugins in static builds, +and \l{qt_deploy_qml_imports}{deploying imported QML modules} for non-static +builds all work correctly. + +\section2 Qt Quick Designer compatibility + +\c DESIGNER_SUPPORTED should be given if the QML module supports +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 Qt Quick Designer handles the plugin. + +\section2 Keeping module versions in sync + +The \c FOLLOW_FOREIGN_VERSIONING keyword relates to base types of your own +C++-defined QML types that live in different QML modules. Typically, the +versioning scheme of your module does not match that of the module providing +the base types. Therefore, by default all revisions of the base types are +made available in any import of your module. If \c FOLLOW_FOREIGN_VERSIONING +is given, the version information attached to the base types and their +properties is respected. So, an \c {import MyModule 2.8} will then only make +available versioned properties up to version \c{2.8} of any base types outside +\c{MyModule}. +This is mostly useful if you want to keep your module version in sync +with other modules you're basing types on. In that case you might want your custom +types to not expose properties from a module's base type version greater than the one being +imported. + +\section2 C++ namespaces of generated code + +If a namespace is given with the \c NAMESPACE keyword, the plugin and registration +code will be generated into a C++ namespace of this name. + +\section2 qmlimportscanner and NO_IMPORT_SCAN + +For static Qt builds, \c{qmlimportscanner} is run at configure time to scan the +\c{.qml} files of a QML module and identify the QML imports it uses (see +\l{qt6_import_qml_plugins}{qt_import_qml_plugins()}). For non-static Qt builds, +if the target is an executable, a similar scan is performed at build time to +provide the information needed by deployment scripts (see +\l{qt6_deploy_qml_imports}{qt_deploy_qml_imports()}). Both scans can be +disabled by providing the \c{NO_IMPORT_SCAN} option. Doing so means the project +takes on the responsibility of ensuring all required plugins are instantiated +and linked for static builds. For non-static builds the project must manually +work out and deploy all QML modules used by an executable target. + +\section2 Arguments for qmltc + +\target ENABLE_TYPE_COMPILER +\c ENABLE_TYPE_COMPILER can be used to compile \c{.qml} files to C++ source code +with \l{QML type compiler}{qmltc}. Files with the source property +\c{QT_QML_SKIP_TYPE_COMPILER} are not compiled to C++. + +\c TYPE_COMPILER_NAMESPACE argument allows to override the namespace in which +\l{QML type compiler}{qmltc} generates code. +By default, the namespace of the generated code follows the module +hierarchy as depicted in the URI, +e.g., \c MyModule for a module with URI \c MyModule or +\c com::example::Module for URI \c com.example.MyModule. +By specifying the \c TYPE_COMPILER_NAMESPACE option, the generated code +can be put instead in a custom namespace, where different subnamespaces are to +be separated by a "::", e.g. "MyNamespace::MySubnamespace" for the namespace MySubnamespace that +is inside the MyNamespace. Apart from the "::", C++ namespace naming rules +apply. + +\c QMLTC_QMLTC_EXPORT_DIRECTIVE should be used with \c QMLTC_EXPORT_FILE_NAME when +the classes generated by \l{QML type compiler}{qmltc} should be exported from +the qml library. By default, classes generated by qmltc are not exported from +their library. +The header defining the export macro for the current library +can be specified as an optional argument to \c QMLTC_EXPORT_FILE_NAME while the +exporting macro name should be specified as an argument to +\c QMLTC_QMLTC_EXPORT_DIRECTIVE. If no additional include is required or wanted, +e.g. when the header of the export macro is already indirectly included by a base +class, then the \c QMLTC_EXPORT_FILE_NAME option can be left out. +*/ diff --git a/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc new file mode 100644 index 0000000000..2ce744559c --- /dev/null +++ b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc @@ -0,0 +1,120 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-qml-plugin.html +\ingroup cmake-commands-qtqml + +\title qt_add_qml_plugin +\target qt6_add_qml_plugin + +\brief Defines a plugin associated with a QML module. + +\section1 Synopsis + +\badcode +qt_add_qml_plugin( + target + [BACKING_TARGET backing_target] + [STATIC | SHARED] + [OUTPUT_DIRECTORY] + [URI] + [CLASS_NAME] + [NO_GENERATE_PLUGIN_SOURCE] + [NAMESPACE namespace] +) + +\endcode + +\versionlessCMakeCommandsNote qt6_add_qml_plugin() + +\section1 Description + +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 + +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 + +If a namespace is given with the \c NAMESPACE keyword, the plugin +code will be generated into a C++ namespace of this name. + +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_deploy_qml_imports.qdoc b/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc new file mode 100644 index 0000000000..87125cd0bf --- /dev/null +++ b/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc @@ -0,0 +1,116 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-deploy-qml-imports.html +\ingroup cmake-commands-qtqml + +\title qt_deploy_qml_imports +\keyword qt6_deploy_qml_imports + +\summary {Deploy the runtime components of QML modules needed by an executable.} + +\include cmake-find-package-qml.qdocinc + +Unlike most other CMake commands provided by Qt, +\c{qt6_deploy_qml_imports} can only be called from a +deployment script. It cannot be called directly by the project. + +\include cmake-qml-qt-finalize-target-warning.qdocinc warning + +\section1 Synopsis + +\badcode +qt_deploy_qml_imports( + TARGET target + [QML_DIR qml_dir] + [PLUGINS_FOUND var_name] + [NO_QT_IMPORTS] +) +\endcode + +\section1 Description + +\note This command does not usually need to be called directly. It is used + internally by other higher level commands, but projects wishing to + implement more customized deployment logic may find it useful. + +When installing an application that uses QML, it may be non-trivial to work out +which QML modules and which parts of those QML modules need to also be +installed. Because QML plugins are not linked directly to an application's +executable, \l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()} won't find these QML modules. +The \c{qt6_deploy_qml_imports} command provides the necessary logic which +complements \l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()} and deploys the runtime parts +of all QML modules imported by the application. + +The \c{TARGET} option is mandatory and should specify a \c{target} that is an +executable (on macOS, it should be an app bundle) and also a QML module. +All QML sources that were added to the \c{target} via +\l{qt6_add_qml_module}{qt_add_qml_module()} or +\l{qt6_target_qml_sources}{qt_target_qml_sources()} will be recursively scanned +for QML imports. The \c{NO_IMPORT_SCAN} option must not have been given to +\l{qt6_add_qml_module}{qt_add_qml_module()}. The \c{qmldir} files and plugins +from the imported QML modules will be deployed. The \c{NO_QT_IMPORTS} option +can be given to skip deploying any QML modules provided by Qt. + +By default, the runtime parts of imported QML modules will be deployed to the +\c{Resources/qml} directory for a macOS app bundle target, and to the \c{qml} +directory under the base installation location for other platforms. For the +non-macOS case, the \c{QML_DIR} option can be used to override this default +choice. + +The command will store a list of all QML plugins it deploys in the variable +named by the \c{PLUGINS_FOUND} option, if given. This is often passed as the +\c{ADDITIONAL_MODULES} argument in a subsequent call to +\l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}. + +\sa {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}, + {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}, + QT_DEPLOY_QML_DIR + +\section1 Example + +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) +qt_add_qml_module(MyApp + URI Application + VERSION 1.0 + QML_FILES main.qml MyThing.qml +) + +# The following script must only be executed at install time +set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake") + +file(GENERATE OUTPUT ${deploy_script} CONTENT " +include(\"${QT_DEPLOY_SUPPORT}\") +qt_deploy_qml_imports( + # Deploy QML modules used by MyApp + TARGET MyApp + + # The found QML plugins are stored in the plugins_found variable + PLUGINS_FOUND plugins_found + + # The QML modules will be deployed into a custom directory + QML_DIR \"myqmldir\" + + # Qt QML modules will be skipped, only project-created QML modules will be deployed + NO_QT_IMPORTS +) +# Deploy application runtime dependencies and runtime dependencies +# of the found QML module plugins. +qt_deploy_runtime_dependencies( + EXECUTABLE $<TARGET_FILE:MyApp> + ADDITIONAL_MODULES \${plugins_found} +) +") + +install(TARGETS MyApp) +install(SCRIPT ${deploy_script}) +\endcode +*/ diff --git a/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc b/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc new file mode 100644 index 0000000000..0d5088e7e5 --- /dev/null +++ b/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc @@ -0,0 +1,177 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-deploy-qml-app-script.html +\ingroup cmake-commands-qtqml + +\title qt_generate_deploy_qml_app_script +\target qt6_generate_deploy_qml_app_script + +\summary {Generate a deployment script for a QML application.} + +\include cmake-find-package-qml.qdocinc + +\cmakecommandsince 6.3 + +\include cmake-qml-qt-finalize-target-warning.qdocinc warning + +\section1 Synopsis + +\badcode +qt_generate_deploy_qml_app_script( + TARGET <target> + OUTPUT_SCRIPT <var> + [NO_UNSUPPORTED_PLATFORM_ERROR] + [NO_TRANSLATIONS] + [NO_COMPILER_RUNTIME] + [DEPLOY_TOOL_OPTIONS ...] + [DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM] + [MACOS_BUNDLE_POST_BUILD] + [PRE_INCLUDE_REGEXES regexes...] + [PRE_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_REGEXES regexes...] + [POST_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_FILES files...] + [POST_EXCLUDE_FILES files...] +) +\endcode + +\versionlessCMakeCommandsNote qt6_generate_deploy_qml_app_script() + +\section1 Description + +Installing an executable target that is also a QML module requires deploying +a number of things in addition to the target itself. Qt libraries and other +libraries from the project, Qt plugins, and the runtime parts of all QML modules +the application uses may all need to be installed too. The installed layout +is also going to be different for macOS app bundles compared to other platforms. +The \c{qt_generate_deploy_qml_app_script()} is a convenience command intended +to simplify that process, similar to what +\l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} does for +non-QML applications. + +The command expects the application to follow Qt's recommended install +directory structure fairly closely. That structure is based on CMake's default +install layout, as determined by \l{GNUInstallDirs} (except for macOS app +bundles, which follow Apple's requirements instead). QML modules are installed +to the appropriate location for the platform. For macOS bundles, each QML +module's \c{qmldir} file is installed under the appropriate subdirectory below +\c{Resources/qml} and the module's plugin (if present) is installed under +\c{PlugIns}. The app bundle is assumed to be installed directly to the base +installation location (see the \l{Example} further below). For all other platforms, +both the \c{qmldir} and the module's plugin are installed under the appropriate +subdirectory below \c{qml}, which itself is relative to the base installation +location. + +\c{qt_generate_deploy_qml_app_script()} generates a script whose name will be +stored in the variable named by the \c{OUTPUT_SCRIPT} option. That script +is only written at CMake generate-time. It is intended to be used with the +\l{install(SCRIPT)} command, which should come after the application's target +has been installed using \l{install(TARGETS)}. + +The deployment script will call +\l{qt6_deploy_qml_imports}{qt_deploy_qml_imports()} with a suitable set of +options for the standard install layout. For macOS app bundles and Windows +targets, it will then also call +\l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}, again +with suitable options for the standard install layout. + +Calling \c{qt_generate_deploy_qml_app_script()} for a platform that is not +supported by \c{qt_deploy_runtime_dependencies} will result in a fatal error, +unless the \c{NO_UNSUPPORTED_PLATFORM_ERROR} option is given. When the option +is given and the project is built for an unsupported platform, neither QML modules +nor regular runtime dependencies will be installed. +To ensure that the QML modules are still installed, specify both the +\c{NO_UNSUPPORTED_PLATFORM_ERROR} and +\c{DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM} options. +The latter option will ensure that QML modules built as part of the project +are still installed. + +The \c{MACOS_BUNDLE_POST_BUILD} option enables an extra step when \c{target} +is a macOS app bundle. A post-build rule will be created which uses the +deployment script to deploy enough of the imported QML modules to allow the +application to run directly from the build directory (essentially just the +\c{qmldir} files and symlinks to plugins). This is usually desirable to support +development of the application. \c{MACOS_BUNDLE_POST_BUILD} is ignored for all +other platforms. + +On platforms other than macOS, Qt translations are automatically deployed. To +inhibit this behavior, specify \c{NO_TRANSLATIONS}. Use +\l{qt_deploy_translations}{qt_deploy_translations()} to deploy translations in a +customized way. + +For Windows desktop applications, the required runtime files for the compiler +are also installed by default. To prevent this, specify \c{NO_COMPILER_RUNTIME}. + +Since Qt 6.7, you can use \c{DEPLOY_TOOL_OPTIONS} to pass additional options to +the underlying deployment tool. This only has an effect if the underlying +deployment tool is either macdeployqt or windeployqt. + +The options \c{PRE_INCLUDE_REGEXES}, \c{PRE_EXCLUDE_REGEXES}, +\c{POST_INCLUDE_REGEXES}, \c{POST_EXCLUDE_REGEXES}, \c{POST_INCLUDE_FILES}, and +\c{POST_EXCLUDE_FILES} can be specified to control the deployment of runtime +dependencies. These options do not apply to all platforms and are forwarded +unmodified to +\l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}. + +For deploying a non-QML application, use +\l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} +instead. It is an error to call both \c{qt_generate_deploy_qml_app_script()} +and \l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} for the +same target. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()}, + {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} + +\section1 Example + +The following example shows how to deploy a QtQuick app. + +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) +qt_add_qml_module(MyApp + URI Application + VERSION 1.0 + QML_FILES main.qml MyThing.qml +) + +install(TARGETS MyApp + BUNDLE DESTINATION . + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} +) + +qt_generate_deploy_qml_app_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + MACOS_BUNDLE_POST_BUILD + NO_UNSUPPORTED_PLATFORM_ERROR + DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM +) +install(SCRIPT ${deploy_script}) +\endcode + +The following example shows how to pass additional options to the underlying +deployment tool. + +\badcode +set(deploy_tool_options_arg "") +if(APPLE) + set(deploy_tool_options_arg --hardened-runtime) +elseif(WIN32) + set(deploy_tool_options_arg --no-compiler-runtime) +endif() + +qt_generate_deploy_qml_app_script( + ... + DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg} +) +install(SCRIPT ${deploy_script}) +\endcode +*/ diff --git a/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc b/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc new file mode 100644 index 0000000000..22d72c101b --- /dev/null +++ b/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc @@ -0,0 +1,77 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-foreign-qml-types.html +\ingroup cmake-commands-qtqml + +\title qt_generate_foreign_qml_types +\target qt6_generate_foreign_qml_types + +\summary{Registers types from one target in a QML module.} + +\include cmake-find-package-qml.qdocinc + +\section1 Synopsis + +\badcode +qt_generate_foreign_qml_types( + source_target + destination_qml_target +) + +\endcode + +\versionlessCMakeCommandsNote qt6_generate_foreign_qml_types() + +\section1 Description + +\c qt_generate_foreign_qml_types extracts types marked via QML registration +macros (like \l QML_ELEMENT) from \c source_target and registers them as foreign +types in the QML module \c destination_qml_target. + +This can be useful when one wants to create a library with optional QML integration, without +depending directly on QML. + +\badcode +// myclass.h +#include <QtQmlIntegration/qqmlintegration.h> + +class MyClass : public QObject +{ + QML_ELEMENT + Q_OBJECT + + // [...] +}; +\endcode + +\badcode +# CMakeLists.txt +qt_add_library(mylib myclass.h ...) +target_link_libraries(mylib PRIVATE Qt::Core Qt::QmlIntegration) + +qt_add_qml_module(mylib_declarative + VERSION 1.0 + URI "mylib" + ... +) +qt_generate_foreign_qml_types(mylib mylib_declarative) +\endcode + +\note In the example above, \c mylib does not depend on QtQml or QtQuick, but only on the +header-only QmlIntegration target (for the QtQmlIntegration/qqmlintegration.h header, which provides +the \c QML_ELEMENT macro). + +The effect is equivalent to using \c QML_FOREIGN with custom structs in the QML library to expose +the types. + +\note In order to implement custom behavior, such as exposing an existing +singleton instance with its own life cycle to QML, you should add custom types +to your QML library (mylib_declarative in the above example). In turn, you +should omit the \l QML_ELEMENT and similar macros from the original C++ classes +so that qt_generate_foreign_qml_types() does not generate more QML integration +structs for them. The QML macros, as well as any singleton factory functions, +can be added to the structs that contain the \l QML_FOREIGN. + +*/ diff --git a/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc new file mode 100644 index 0000000000..8d6b32f903 --- /dev/null +++ b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc @@ -0,0 +1,55 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-import-qml-plugins.html +\ingroup cmake-commands-qtqml + +\title qt_import_qml_plugins +\target qt6_import_qml_plugins + +\brief Ensures QML plugins needed by a target are imported for static builds. + +\cmakecommandsince 6.0 + +\section1 Synopsis + +\badcode +qt_import_qml_plugins(target) +\endcode + +\versionlessCMakeCommandsNote qt6_import_qml_plugins() + +\section1 Description + +\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 (unless the \c{NO_IMPORT_SCAN} option was +passed to \l{qt6_add_qml_module}{qt_add_qml_module()} when defining the QML +module). 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. + +\sa Q_IMPORT_QML_PLUGIN + +*/ diff --git a/src/qml/doc/src/cmake/qt_query_qml_module.qdoc b/src/qml/doc/src/cmake/qt_query_qml_module.qdoc new file mode 100644 index 0000000000..c72626a52d --- /dev/null +++ b/src/qml/doc/src/cmake/qt_query_qml_module.qdoc @@ -0,0 +1,213 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-query-qml-module.html +\ingroup cmake-commands-qtqml + +\title qt_query_qml_module +\target qt6_query_qml_module + +\summary {Retrieve information about a QML module.} + +\include cmake-find-package-qml.qdocinc + +\cmakecommandsince 6.3 + +\section1 Synopsis + +\badcode +qt_query_qml_module( + target + [URI uri_var] + [VERSION version_var] + [PLUGIN_TARGET plugin_target_var] + [TARGET_PATH target_path_var] + [MODULE_RESOURCE_PATH module_resource_path_var] + [QMLDIR qmldir_var] + [TYPEINFO typeinfo_var] + [QML_FILES qml_files_var] + [QML_FILES_DEPLOY_PATHS qml_files_deploy_paths_var] + [QML_FILES_PREFIX_OVERRIDES qml_files_prefix_overrides_var] + [RESOURCES resources_var] + [RESOURCES_DEPLOY_PATHS resources_deploy_paths_var] + [RESOURCES_PREFIX_OVERRIDES resources_prefix_overrides_var] +) +\endcode + +\versionlessCMakeCommandsNote qt6_query_qml_module() + +\section1 Description + +This command is used to obtain information about a QML module \c target. +That \c target must have previously been created by or passed to an earlier +call to \l{qt6_add_qml_module}{qt_add_qml_module()}. The \c target cannot be an +imported target. + +The information provided by this command enables the caller to deploy all parts +of a single QML module. The project should install the \c target and the +associated plugin target (if the module has one and it is separate from the +backing \c target) using the standard \l{install(TARGETS)} command. +Everything else can be deployed with \l{install(FILES)}. + +\section1 Arguments + +Each of the optional arguments specifies the name of a variable in which to +store the corresponding QML module property. + +\c URI and \c VERSION provide the module's uri and version respectively. + +\c PLUGIN_TARGET can be used to obtain the name of the plugin target for the +QML module. Not all QML modules have a plugin, so the value returned for this +option could be an empty string. If the QML module has no separate backing +target, then \c target will be the same as the plugin target. + +\c TARGET_PATH is the \c URI with dots (.) replaced by forward slashes (/). +It represents the path below the base QML module installation directory where +this QML module's \c{qmldir} file (and possibly others) should be deployed. +The QML module installation directory serves as a QML import path where +the QML engine will look for QML modules. +The default base QML module installation directory used by +\l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} +is \c{qml}. A project using a deployment script can use \l{QT_DEPLOY_QML_DIR} +rather than hard-coding this location (also see \l{QT_DEPLOY_PREFIX}). + +\c MODULE_RESOURCE_PATH provides the resource path under which the QML module's +compiled-in files can be found. It is formed from +\l{qt6_add_qml_module}{qt_add_qml_module()}'s \c{RESOURCE_PREFIX} concatenated +with the module's \c TARGET_PATH. +The queried value should not be used for deployment, but may be helpful in +matching up resource paths with file system locations, if needed. + +\c QMLDIR provides the path to the \c{qmldir} file. When deploying the QML +module, this file should be copied to the target path. In a deployment script, +this location can be obtained using \c{${QT_DEPLOY_PREFIX}/${QT_DEPLOY_QML_DIR}}. + +\c TYPEINFO provides the path to the module's typeinfo file, if it has one. +It will be an empty string if the module has no typeinfo file. The typeinfo +file should be deployed to the same path as the \c{qmldir} file. + +\c QML_FILES provides a list of all files added to the QML module through one +of the following methods: + +\list +\li As \c{QML_FILES} arguments in \l{qt6_add_qml_module}{qt_add_qml_module()}. +\li As \c{FILES} arguments in \l{qt6_target_qml_sources}{qt_target_qml_sources()}. +\endlist + +All files will be recorded with absolute paths. + +\c QML_FILES_DEPLOY_PATHS provides a list with exactly the same number of +elements as \c QML_FILES. Each element of the \c QML_FILES_DEPLOY_PATHS list is +the path below the target path where the corresponding element of \c QML_FILES +should be deployed. The paths in \c QML_FILES_DEPLOY_PATHS include the file +name, since this could be different to the file name in \c QML_FILES due to the +use of resource aliases (see \l{QT_RESOURCE_ALIAS}). + +Entries in \c QML_FILES_DEPLOY_PATHS can also be an empty string. Any file +added using \l{qt6_target_qml_sources}{qt_target_qml_sources()} with a custom +\c PREFIX will have no deploy path, since using a custom prefix typically means +the file sits outside of the QML module's target path. + +\c QML_FILES_PREFIX_OVERRIDES provides another list with exactly the same +number of elements as \c QML_FILES. Where a file has been added with a custom +prefix as described in the preceding paragraph, its corresponding entry in the +\c QML_FILES_PREFIX_OVERRIDES list will contain the custom prefix used. For all +other files, their list entries will be an empty string. + +\note As a special case, if there is only one file in the \c QML_FILES list, +then \c QML_FILES_DEPLOY_PATHS or \c QML_FILES_PREFIX_OVERRIDES may be an empty +string depending on whether that file has a custom prefix. +This is because CMake's way of representing lists and strings means that +it is impossible to distinguish between an empty string and a list with a single +empty element. + +The \c RESOURCES, \c RESOURCES_DEPLOY_PATHS, and \c RESOURCES_PREFIX_OVERRIDES +options are analogous to those for \c QML_FILES discussed above. +\c RESOURCES provides a list of all files added to the QML module as +\c RESOURCES arguments to either \l{qt6_add_qml_module}{qt_add_qml_module()} or +\l{qt6_target_qml_sources}{qt_target_qml_sources()}. All paths will be +absolute. The meaning and usage of \c RESOURCES_DEPLOY_PATHS and +\c RESOURCES_PREFIX_OVERRIDES follows the same patterns as +\c QML_FILES_DEPLOY_PATHS and \c QML_FILES_PREFIX_OVERRIDES respectively. + +\section1 Example + +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml) + +set(module_name "MyThings") +qt_add_qml_module(${module_name} + URI My.Things + VERSION 1.3 + RESOURCE_PREFIX org.mycompany/imports + QML_FILES + First.qml + Second.qml + RESOURCES + Third.txt +) + +qt_query_qml_module(${module_name} + URI module_uri + VERSION module_version + PLUGIN_TARGET module_plugin_target + TARGET_PATH module_target_path + QMLDIR module_qmldir + TYPEINFO module_typeinfo + QML_FILES module_qml_files + QML_FILES_DEPLOY_PATHS qml_files_deploy_paths + RESOURCES module_resources + RESOURCES_DEPLOY_PATHS resources_deploy_paths +) + +message("My QML module URI is: ${module_uri}") +message("My QML module version is: ${module_version}") + +# Install the QML module backing library +set(staging_prefix "staging") +install(TARGETS ${module_name} + ARCHIVE DESTINATION "${staging_prefix}/${CMAKE_INSTALL_LIBDIR}" + LIBRARY DESTINATION "${staging_prefix}/${CMAKE_INSTALL_LIBDIR}" + RUNTIME DESTINATION "${staging_prefix}/${CMAKE_INSTALL_BINDIR}" +) +set(module_dir "${staging_prefix}/qml/${module_target_path}") + +# Install the QML module runtime loadable plugin +install(TARGETS "${module_plugin_target}" + LIBRARY DESTINATION "${module_dir}" + RUNTIME DESTINATION "${module_dir}" +) + +# Install the QML module meta information. +install(FILES "${module_qmldir}" DESTINATION "${module_dir}") +install(FILES "${module_typeinfo}" DESTINATION "${module_dir}") + +# Install QML files, possibly renamed. +list(LENGTH module_qml_files num_files) +math(EXPR last_index "${num_files} - 1") +foreach(i RANGE 0 ${last_index}) + list(GET module_qml_files ${i} src_file) + list(GET qml_files_deploy_paths ${i} deploy_path) + get_filename_component(dst_name "${deploy_path}" NAME) + get_filename_component(dest_dir "${deploy_path}" DIRECTORY) + install(FILES "${src_file}" DESTINATION "${module_dir}/${dest_dir}" RENAME "${dst_name}") +endforeach() + +# Install resources, possibly renamed. +list(LENGTH module_resources num_files) +math(EXPR last_index "${num_files} - 1") +foreach(i RANGE 0 ${last_index}) + list(GET module_resources ${i} src_file) + list(GET resources_deploy_paths ${i} deploy_path) + get_filename_component(dst_name "${deploy_path}" NAME) + get_filename_component(dest_dir "${deploy_path}" DIRECTORY) + install(FILES "${src_file}" DESTINATION "${module_dir}/${dest_dir}" RENAME "${dst_name}") +endforeach() + +\endcode + +*/ diff --git a/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc b/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc new file mode 100644 index 0000000000..0ef6e421ed --- /dev/null +++ b/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc @@ -0,0 +1,14 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-target-compile-qml-to-cpp.html +\ingroup cmake-commands-qtqml + +\title qt_target_compile_qml_to_cpp +\target qt6_target_compile_qml_to_cpp + +This command is removed in Qt 6.4 in favor of \l{qt6_add_qml_module} which can +now invoke qmltc internally as described in the \l{qmltc-cmake}{qmltc section}. + +*/ diff --git a/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc new file mode 100644 index 0000000000..336cd973f9 --- /dev/null +++ b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc @@ -0,0 +1,206 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-target-qml-sources.html +\ingroup cmake-commands-qtqml + +\title qt_target_qml_sources +\target qt6_target_qml_sources + +\brief Add qml files and resources to an existing QML module target. + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +qt_target_qml_sources( + target + [QML_FILES ...] + [RESOURCES ...] + [PREFIX resource_path] + [OUTPUT_TARGETS out_targets_var] + [NO_LINT] + [NO_CACHEGEN] + [NO_QMLDIR_TYPES] +) + +\endcode + +\versionlessCMakeCommandsNote qt6_target_qml_sources() + +\section1 Description + +\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 + +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}. +The source properties must be set before \l{qt_add_qml_module}{creating} the +module the singleton belongs to. + +\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/cppclasses/topic.qdoc b/src/qml/doc/src/cppclasses/topic.qdoc index 6b23dfd433..b440ca437d 100644 --- a/src/qml/doc/src/cppclasses/topic.qdoc +++ b/src/qml/doc/src/cppclasses/topic.qdoc @@ -1,38 +1,14 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-cppclasses-topic.html -\title Important C++ Classes Provided By The Qt QML Module -\brief Overview of the C++ classes provided by the Qt QML module +\title Important C++ Classes Provided By The Qt Qml Module +\brief Overview of the C++ classes provided by the Qt Qml module. -The \l{Qt QML} module provides C++ classes which implement the QML framework. +The \l{Qt Qml} module provides C++ classes which implement the QML framework. Clients can use these classes to interact with the QML run-time (for example, by injecting data or invoking methods on objects), and to instantiate a -hierarchy of objects from a QML document. The Qt QML module provides more +hierarchy of objects from a QML document. The Qt Qml module provides more C++ API than just the classes listed here, however the classes listed here provide the foundations of the QML runtime and the core concepts of QML. @@ -119,7 +95,7 @@ These pages describe how to create QML applications which interact with the C++ classes: \list -\li \l{qtqml-cppintegration-topic.html}{Integrating QML and C++} +\li \l{Overview - QML and C++ Integration} \list \li \l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Classes to QML} \li \l{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++} diff --git a/src/qml/doc/src/cppintegration/contextproperties.qdoc b/src/qml/doc/src/cppintegration/contextproperties.qdoc index 869e01c69e..1783c0cdc8 100644 --- a/src/qml/doc/src/cppintegration/contextproperties.qdoc +++ b/src/qml/doc/src/cppintegration/contextproperties.qdoc @@ -1,34 +1,27 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-cppintegration-contextproperties.html \title Embedding C++ Objects into QML with Context Properties \brief Description of how to embed C++ data into QML using context properties +\warning By using context properties in your QML code, you create a dependency from your QML code + to the specific context you have in mind when writing it. This limits re-usability of your + code since the context may be different in other places where it might be used. + Furthermore, the dependency is not declared. You never \c import the context or otherwise + state what you expect. Therefore, anyone trying to re-use your code will have difficulties + finding out whether the place of re-use has a context sufficient for your code. + +\warning Context properties are invisible to any tooling that processes QML code ahead of time, + before you load it into the QML engine. The \l{Qt Quick Compiler}, + \l{qmllint Reference}{qmllint}, and the \l{\QMLLS Reference}{\QMLLS} do + not know anything about your context properties and will consider any access to context + properties as an \e{unqualified access}. + +\note Context properties can generally be replaced either by regular properties on the root object + of a component, or by singletons defined either in C++ using \l{QML_SINGLETON}{QML_SINGLETON} + or in QML using \l{Structure of a QML Document#Singleton}{pragma Singleton}. + When loading a QML object into a C++ application, it can be useful to directly embed some C++ data that can be used from within the QML code. This makes it possible, for example, to invoke a C++ method on the embedded object, or use a C++ object instance as a data model for a QML view. diff --git a/src/qml/doc/src/cppintegration/data.qdoc b/src/qml/doc/src/cppintegration/data.qdoc index 8ebbd28737..4932943fc1 100644 --- a/src/qml/doc/src/cppintegration/data.qdoc +++ b/src/qml/doc/src/cppintegration/data.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-cppintegration-data.html \title Data Type Conversion Between QML and C++ @@ -38,6 +14,10 @@ The QML engine provides built-in support for a large number of Qt C++ data types. Additionally, custom C++ types may be registered with the QML type system to make them available to the engine. +For more information about C++ and the different QML integration methods, +see the +\l {Overview - QML and C++ Integration} {C++ and QML integration overview} page. + This page discusses the data types supported by the QML engine and how they are converted between QML and C++. @@ -59,13 +39,13 @@ has a parent. \section1 Basic Qt Data Types By default, QML recognizes the following Qt data types, which are -automatically converted to a corresponding \l {QML Basic Types}{QML basic type} +automatically converted to a corresponding \l {QML Value Types}{QML value type} when passed from C++ to QML and vice-versa: \table \row \li Qt Type - \li QML Basic Type + \li QML Value Type \row \li bool \li \l bool @@ -112,7 +92,7 @@ when passed from C++ to QML and vice-versa: \li QVector2D, QVector3D, QVector4D \li \l vector2d, \l vector3d, \l vector4d \row - \li Enums declared with Q_ENUM() or Q_ENUMS() + \li Enums declared with Q_ENUM() \li \l enumeration \endtable @@ -133,7 +113,7 @@ Item { } \endqml -See documentation for each individual type under \l {QML Basic Types} for more +See documentation for each individual type under \l {QML Value Types} for more information. @@ -197,6 +177,25 @@ type or method parameter, the value can be created as a JavaScript array or object in QML, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++. +Mind that QVariantList and QVariantMap properties of C++ types are stored as +values and cannot be changed in place by QML code. You can only replace the +whole map or list, but not manipulate its contents. The following code does +not work if the property \c l is a QVariantList: + +\code +MyListExposingItem { + l: [1, 2, 3] + Component.onCompleted: l[0] = 10 +} +\endcode + +The following code does work: +\code +MyListExposingItem { + l: [1, 2, 3] + Component.onCompleted: l = [10, 2, 3] +} +\endcode \section2 QDateTime to JavaScript Date @@ -247,6 +246,51 @@ Similarly, if a C++ type uses a QDateTime for a property type or method parameter, the value can be created as a JavaScript \c Date object in QML, and is automatically converted to a QDateTime value when it is passed to C++. +\note Watch out for the difference in month numbering: JavaScript numbers +January as 0 through 11 for December, off by one from Qt's numbering +of January as 1 through 12 for December. + +\note When using a string in JavaScript as the value of a \c Date object, +note that a string with no time fields (so a simple date) is +interpreted as the UTC start of the relevant day, in contrast +to \c{new Date(y, m, d)} which uses the local time start of the day. +Most other ways of constructing a \c Date object in JavaScript produce +a local time, unless methods with UTC in their names are used. If your +program is run in a zone behind UTC (nominally west of The Prime +Meridian), use of a date-only string will lead to a \c Date object +whose \c getDate() is one less than the day-number in your string; it +will typically have a large value for \c getHours(). The UTC variants +of these methods, \c getUTCDate() and \c getUTCHours(), will give the +results you expect for such a \c Date objects. See also the next +section. + +\section2 QDate and JavaScript Date + +The QML engine converts automatically between \l QDate and the +JavaScript \c Date type by representing the date by the UTC start of +its day. A date is mapped back to QDate via QDateTime, selecting +its \l {QDateTime::}{date()} method, using the local time form of the +date unless the UTC form of it coincides with the start of the next +day, in which case the UTC form is used. + +This slighly eccentric arrangement is a work-around for the fact that +JavaScript's construction of a \c Date object from a date-only string +uses the UTC start of the day, but \c{new Date(y, m, d)} uses the +local time start of the indicated date, as discussed in a note at the +end of the previous section. + +As a result, where a QDate property or parameter is exposed to QML, +care should be taken in reading its value: the \c +Date.getUTCFullYear(), \c Date.getUTCMonth() and \c Date.getUTCDate() +methods are more likely to deliver the results users expect than the +corresponding methods without UTC in their names. + +It is thus commonly more robust to use a \l QDateTime property. This +makes it possible to take control, on the QDateTime side, of whether +the date (and time) is specified in terms of UTC or local time; as +long as the JavaScript code is written to work with the same standard, +it should be possible to avoid trouble. + //! Target adds an anchor, so renaming the section won't break incoming links. \target QTime to JavaScript Date \section2 QTime and JavaScript Date @@ -256,94 +300,20 @@ JavaScript \c Date objects. As QTime values do not contain a date component, one is created for the conversion only. Thus, you should not rely on the date component of the resulting Date object. -Under the hood, conversion from a JavaScript \c Date object to QTime is done by -converting to a QDateTime object and calling its \l {QDateTime::}{time()} -method. +Under the hood, conversion from a JavaScript \c Date object to QTime +is done by converting to a QDateTime object (using local time) and +calling its \l {QDateTime::}{time()} method. \section2 Sequence Type to JavaScript Array -Certain C++ sequence types are supported transparently in QML to behave like -JavaScript \c Array types. - -In particular, QML currently supports: -\list - \li \c {QList<int>} - \li \c {QList<qreal>} - \li \c {QList<bool>} - \li \c {QList<QString>} and \c{QStringList} - \li \c {QVector<QString>} - \li \c {std::vector<QString>} - \li \c {QList<QUrl>} - \li \c {QVector<QUrl>} - \li \c {std::vector<QUrl>} - \li \c {QVector<int>} - \li \c {QVector<qreal>} - \li \c {QVector<bool>} - \li \c {std::vector<int>} - \li \c {std::vector<qreal>} - \li \c {std::vector<bool>} -\endlist - -These sequence types are implemented directly in terms of the underlying C++ -sequence. There are two ways in which such sequences can be exposed to QML: -as a Q_PROPERTY of the given sequence type; or as the return type of a -Q_INVOKABLE method. There are some differences in the way these are -implemented, which are important to note. - -If the sequence is exposed as a Q_PROPERTY, accessing any value in the -sequence by index will cause the sequence data to be read from the QObject's -property, then a read to occur. Similarly, modifying any value in the -sequence will cause the sequence data to be read, and then the modification -will be performed and the modified sequence will be written back to the -QObject's property. - -If the sequence is returned from a Q_INVOKABLE function, access and mutation -is much cheaper, as no QObject property read or write occurs; instead, the -C++ sequence data is accessed and modified directly. - -In both the Q_PROPERTY and return from Q_INVOKABLE cases, the elements -of a std::vector are copied. This copying may be an expensive operation, -so std::vector should be used judiciously. - -Other sequence types are not supported transparently, and instead an -instance of any other sequence type will be passed between QML and C++ as an -opaque QVariantList. - -\b {Important Note:} There are some minor differences between the -semantics of such sequence Array types and default JavaScript Array types -which result from the use of a C++ storage type in the implementation. In -particular, deleting an element from an Array will result in a -default-constructed value replacing that element, rather than an Undefined -value. Similarly, setting the length property of the Array to a value larger -than its current value will result in the Array being padded out to the -specified length with default-constructed elements rather than Undefined -elements. Finally, the Qt container classes support signed (rather than -unsigned) integer indexes; thus, attempting to access any index greater -than INT_MAX will fail. - -The default-constructed values for each sequence type are as follows: -\table -\row \li QList<int> \li integer value 0 -\row \li QList<qreal> \li real value 0.0 -\row \li QList<bool> \li boolean value \c {false} -\row \li QList<QString> and QStringList \li empty QString -\row \li QVector<QString> \li empty QString -\row \li std::vector<QString> \li empty QString -\row \li QList<QUrl> \li empty QUrl -\row \li QVector<QUrl> \li empty QUrl -\row \li std::vector<QUrl> \li empty QUrl -\row \li QVector<int> \li integer value 0 -\row \li QVector<qreal> \li real value 0.0 -\row \li QVector<bool> \li boolean value \c {false} -\row \li std::vector<int> \li integer value 0 -\row \li std::vector<qreal> \li real value 0.0 -\row \li std::vector<bool> \li boolean value \c {false} -\endtable +See \l{QML Sequence Types} for a general description of sequence types. The +\l{Qt Qml QML Types}{QtQml module} contains a few sequence types +you may want to use. -If you wish to remove elements from a sequence rather than simply replace -them with default constructed values, do not use the indexed delete operator -("delete sequence[i]") but instead use the \c {splice} function -("sequence.splice(startIndex, deleteCount)"). +You can also create a list-like data structure by constructing a QJSValue using +QJSEngine::newArray(). Such a JavaScript array does not need any conversion +when passing it between QML and C++. See \l{QJSValue#Working With Arrays} for +details on how to manipulate JavaScript arrays from C++. \section2 QByteArray to JavaScript ArrayBuffer @@ -378,6 +348,14 @@ properties: Q_DECLARE_METATYPE(Actor) \endcode +The usual pattern is to use a gadget class as the type of a property, or to +emit a gadget as a signal argument. In such cases, the gadget instance is +passed by value between C++ and QML (because it's a value type). If QML code +changes a property of a gadget property, the entire gadget is re-created and +passed back to the C++ property setter. In Qt 5, gadget types cannot be +instantiated by direct declaration in QML. In contrast, a QObject instance can +be declared; and QObject instances are always passed by pointer from C++ to QML. + \section1 Enumeration Types To use a custom enumeration as a data type, its class must be registered and @@ -462,6 +440,62 @@ class Message : public QObject }; \endcode +Enums from related types are usually registered in the scope of the relating +type. For example any enum from a different type used in a \l{Q_PROPERTY} +declaration causes all enums from that type to be made available in QML. This +is usually more of a liability than a feature. In order to prevent it from +happening, annotate your class with a special \l{Q_CLASSINFO} macro. +Use the name \c RegisterEnumsFromRelatedTypes with the value \c false to prevent +enums from related types from being registered in this type. + +You should explicitly register the enclosing types of any enums you want to use +in QML, using \l{QML_ELEMENT} or \l{QML_NAMED_ELEMENT}, rather than rely on +their enums to be injected into other types. + +\code +class OtherType : public QObject +{ + Q_OBJECT + QML_ELEMENT + +public: + enum SomeEnum { A, B, C }; + Q_ENUM(SomeEnum) + + enum AnotherEnum { D, E, F }; + Q_ENUM(AnotherEnum) +}; + +class Message : public QObject +{ + Q_OBJECT + QML_ELEMENT + + // This would usually cause all enums from OtherType to be registered + // as members of Message ... + Q_PROPERTY(OtherType::SomeEnum someEnum READ someEnum CONSTANT) + + // ... but this way it doesn't. + Q_CLASSINFO("RegisterEnumsFromRelatedTypes", "false") + +public: + OtherType::SomeEnum someEnum() const { return OtherType::B; } +}; +\endcode + +The important difference is the scope for the enums in QML. If an enum from a +related class is automatically registered, the scope is the type it is +imported into. In the above case, without the extra \l{Q_CLASSINFO}, you would +use \c {Message.A}, for example. If C++ type holding the enums is explicitly +registered, and the registration of enums from related types is suppressed, the +QML type for the C++ type holding the enums is the scope for all of its enums. +You would use \c {OtherType.A} instead of \c {Message.A} in QML. + +Mind that you can use \l QML_FOREIGN to register a type you cannot modify. You +can also use \l QML_FOREIGN_NAMESPACE to register the enumerators of a C++ type +into a QML namespace of any upper-case name, even if the same C++ type is +also registered as a QML value type. + \section2 Enumeration Types as Signal and Method Parameters C++ signals and methods with enumeration-type parameters can be used from QML diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc index 41bc9fd140..feb9053632 100644 --- a/src/qml/doc/src/cppintegration/definetypes.qdoc +++ b/src/qml/doc/src/cppintegration/definetypes.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-cppintegration-definetypes.html \title Defining QML Types from C++ @@ -40,12 +16,17 @@ as an instantiable \l{qtqml-typesystem-objecttypes.html}{QML object type} from QML, or enabling a singleton instance of the class to be imported and used from QML. -Additionally, the \l {Qt QML} module provides mechanisms for implementing QML-specific +Additionally, the \l {Qt Qml} module provides mechanisms for implementing QML-specific features such as \e{attached properties} and \e{default properties} in C++. (Note that a number of the important concepts covered in this document are demonstrated in the \l{Writing QML Extensions with C++} tutorial.) +\b{NOTE:} All headers that declare QML types need to be accessible without any prefix from the project's include path. + +For more information about C++ and the different QML integration methods, +see the +\l {Overview - QML and C++ Integration} {C++ and QML integration overview} page. \section1 Registering C++ Types with the QML Type System @@ -69,6 +50,21 @@ exposed to QML but the type itself should not be instantiable. For a quick guide to choosing the correct approach to expose C++ types to QML, see \l {Choosing the Correct Integration Method Between C++ and QML}. +\section2 Preconditions + +All the macros mentioned below are available from the \c qqmlregistration.h +header. You need to add the following code to the files using them in order to +make the macros available: + +\code +#include <QtQml/qqmlregistration.h> +\endcode + +Furthermore, your class declarations have to live in headers reachable via your +project's include path. The declarations are used to generate registration code +at compile time, and the registration code needs to include the headers that +contain the declarations. + \section2 Registering an Instantiable Object Type \b{Any QObject-derived C++ class can be registered as the definition of a @@ -80,9 +76,20 @@ class instance can be manipulated from QML; as Types to QML} explains, the properties, methods and signals of any QObject-derived class are accessible from QML code. -To register a QObject-derived class as an instantiable QML object type, call -qmlRegisterType() to register the class as QML type into a particular type -namespace. Clients can then import that namespace in order to use the type. +To register a QObject-derived class as an instantiable QML object type, add +\c QML_ELEMENT or \c QML_NAMED_ELEMENT(<name>) to the class declaration. You +also need to make adjustments in the build system. For qmake, add +\c {CONFIG += qmltypes}, a \c {QML_IMPORT_NAME}, and a +\c QML_IMPORT_MAJOR_VERSION to your project file. For CMake, the file containing +the class should be part of a target set-up with +\l{qt_add_qml_module}{qt_add_qml_module()}. +This will register the class into the type namespace under the given major version, +using either the class name or an explicitly given name as QML type name. The +minor version(s) will be derived from any revisions attached to properties, +methods, or signals. The default minor version is \c 0. You can explicitly +restrict the type to be available only from specific minor versions by adding +the \c QML_ADDED_IN_VERSION() macro to the class declaration. Clients can +import suitable versions of the namespace in order to use the type. For example, suppose there is a \c Message class with \c author and \c creationDate properties: @@ -93,25 +100,62 @@ class Message : public QObject Q_OBJECT Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged) Q_PROPERTY(QDateTime creationDate READ creationDate WRITE setCreationDate NOTIFY creationDateChanged) + QML_ELEMENT public: // ... }; \endcode -This type can be registered by calling qmlRegisterType() with an appropriate -type namespace and version number. For example, to make the type available in -the \c com.mycompany.messaging namespace with version 1.0: +This type can be registered by adding an appropriate type namespace and version +number to the project file. For example, to make the type available in the +\c com.mycompany.messaging namespace with version 1.0: + +\if defined(onlinedocs) + \tab {build-qt-app}{tab-cmake}{CMake}{selected} + \tab {build-qt-app}{tab-qmake}{qmake}{} + \tabcontent {tab-cmake} + \else + \section3 Using CMake +\endif + \badcode + qt_add_qml_module(messaging + URI com.mycompany.messaging + VERSION 1.0 + SOURCES + message.cpp message.h + ) + \endcode +\if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmake} +\else + \section3 Using QMake +\endif + \code + CONFIG += qmltypes + QML_IMPORT_NAME = com.mycompany.messaging + QML_IMPORT_MAJOR_VERSION = 1 + \endcode + + If the header the class is declared in is not accessible from your project's + include path, you may have to amend the include path so that the generated + registration code can be compiled. + + \code + INCLUDEPATH += com/mycompany/messaging + \endcode +\if defined(onlinedocs) + \endtabcontent +\endif + -\code -qmlRegisterType<Message>("com.mycompany.messaging", 1, 0, "Message"); -\endcode The type can be used in an \l{qtqml-syntax-basics.html#object-declarations} {object declaration} from QML, and its properties can be read and written to, as per the example below: \qml -import com.mycompany.messaging 1.0 +import com.mycompany.messaging Message { author: "Amelie" @@ -119,6 +163,102 @@ Message { } \endqml +\section2 Registering Value Types + +Any type with a \l{Q_GADGET} macro can the registered as a +\l{qtqml-typesystem-valuetypes.html}{QML value type}. Once such a type is +registered with the QML type system it can be used as property type in QML +code. Such an instance can be manipulated from QML; as +\l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ +Types to QML} explains, the properties and methods of any value type are +accessible from QML code. + +In contrast to object types, value types require \b{lower case} names. The +preferred way to register them is using the \l{QML_VALUE_TYPE} or +\l{QML_ANONYMOUS} macros. There is no equivalent to \l{QML_ELEMENT} as your +C++ classes are typically going to have upper case names. Otherwise the +registration is very similar to the registration of object types. + +For example, suppose you want to register a value type \c{person} that consists +of two strings for first and last name: + +\code +class Person +{ + Q_GADGET + Q_PROPERTY(QString firstName READ firstName WRITE setFirstName) + Q_PROPERTY(QString lastName READ lastName WRITE setLastName) + QML_VALUE_TYPE(person) +public: + // ... +}; +\endcode + +There are some further limitations on what you can do with value types: +\list +\li Value types cannot be singletons. +\li Value types need to be default-constructible and copy-constructible. +\li Using QProperty as a member of a value type is problematic. Value types get + copied, and you would need to decide what to do with any bindings on the + QProperty at that point. You should not use QProperty in value types. +\li Value types cannot provide attached properties. +\li The API to define extensions to value types (\l{QML_EXTENDED}) is not public + and subject to future changes. +\endlist + +\section2 Value Types with Enumerations + +Exposing enumerations from a value type to QML requires some extra steps. + +Value types have lower case names in QML and types with lower case +names are generally not addressable in JavaScript code (unless you specify +\l{ValueTypeBehavior}{pragma ValueTypeBehavior: Addressable}). If you have +a value type in C++ with an enumeration you want to expose to QML, you +need to expose the enumeration separately. + +This can be solved by using \l{QML_FOREIGN_NAMESPACE}. First, derive from +your value type to create a separate C++ type: + +\code +class Person +{ + Q_GADGET + Q_PROPERTY(QString firstName READ firstName WRITE setFirstName) + Q_PROPERTY(QString lastName READ lastName WRITE setLastName) + QML_VALUE_TYPE(person) +public: + enum TheEnum { A, B, C }; + Q_ENUM(TheEnum) + //... +}; + +class PersonDerived: public Person +{ + Q_GADGET +}; +\endcode + +Then expose the derived type as a foreign namespace: + +\code +namespace PersonDerivedForeign +{ + Q_NAMESPACE + QML_NAMED_ELEMENT(Person) + QML_FOREIGN_NAMESPACE(PersonDerived) +} +\endcode + +This produces a \l{qtqml-typesystem-namespaces.html}{QML Namespace} +called \c Person (upper case) with an enumeration called \c TheEnum and +values \c{A}, \c{B}, and \c{C}. Then you can write the following in QML: + +\qml + someProperty: Person.A +\endqml + +At the same time you can still use your value type called \c person +(lower case) exactly as before. \section2 Registering Non-Instantiable Types @@ -135,23 +275,25 @@ not be instantiable should not be instantiable from QML \endlist -The \l {Qt QML} module provides several methods for registering non-instantiable +The \l {Qt Qml} module provides several macros for registering non-instantiable types: \list -\li qmlRegisterType() (with no parameters) registers a C++ type that is not -instantiable and cannot be referred to from QML. This enables the engine to -coerce any inherited types that are instantiable from QML. -\li qmlRegisterInterface() registers an existing Qt interface type. The type is +\li QML_ANONYMOUS registers a C++ type that is not instantiable and cannot be +referred to from QML. This enables the engine to coerce any inherited types that +are instantiable from QML. +\li QML_INTERFACE registers an existing Qt interface type. The type is not instantiable from QML, and you cannot declare QML properties with it. Using C++ properties of this type from QML will do the expected interface casts, though. -\li qmlRegisterUncreatableType() registers a named C++ type that is not -instantiable but should be identifiable as a type to the QML type system. This -is useful if a type's enums or attached properties should be accessible from QML -but the type itself should not be instantiable. -\li qmlRegisterSingletonType() registers a singleton type that can be imported -from QML, as discussed below. +\li QML_UNCREATABLE(reason) combined with with QML_ELEMENT or QML_NAMED_ELEMENT +registers a named C++ type that is not instantiable but should be identifiable +as a type to the QML type system. This is useful if a type's enums or attached +properties should be accessible from QML but the type itself should not be +instantiable. The parameter should be an error message to be emitted if an +attempt at creating an instance of the type is detected. +\li QML_SINGLETON combined with QML_ELEMENT or QML_NAMED_ELEMENT registers a +singleton type that can be imported from QML, as discussed below. \endlist Note that all C++ types registered with the QML type system must be @@ -195,11 +337,26 @@ Rectangle { A QJSValue may also be exposed as a singleton type, however clients should be aware that properties of such a singleton type cannot be bound to. -See \l{qmlRegisterSingletonType()} for more information on how implement and +See \l{QML_SINGLETON} for more information on how implement and register a new singleton type, and how to use an existing singleton type. +See \l{Singletons in QML} for more in-depth information about singletons. \note Enum values for registered types in QML should start with a capital. +\section2 Final properties + +Properties declared final using the \c FINAL modifier to \l Q_PROPERTY cannot +be overridden. This means that any properties or functions of the same name, +declared either in QML or in C++ on derived types, are ignored by the QML +engine. You should declare properties \c FINAL when possible, in order to avoid +accidental overrides. An override of a property is visible not only in +derived classes, but also to QML code executing the context of the base class. +Such QML code, typically expects the original property, though. This is a +frequent source of mistakes. + +Properties declared \c FINAL can also not be overridden by functions in QML, or +by \l Q_INVOKABLE methods in C++. + \section2 Type Revisions and Versions Many of the type registration functions require versions to be specified @@ -245,30 +402,20 @@ class CppType : public BaseType { Q_OBJECT Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1) + QML_ELEMENT signals: Q_REVISION(1) void rootChanged(); }; \endcode -To register the new class revision to a particular version the following -function is used: - -\code -template<typename T, int metaObjectRevision> -int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) -\endcode - -To register \c CppType version 1 for \c {MyTypes 1.1}: - -\code -qmlRegisterType<CppType,1>("MyTypes", 1, 1, "CppType") -\endcode +The revisions given this way are automatically interpreted as minor versions to +the major version given in the project file. In this case, \c root is only +available when \c MyTypes version 1.1 or higher is imported. Imports of +\c MyTypes version 1.0 remain unaffected. -\c root is only available when \c MyTypes version 1.1 is imported. - -For the same reason, new types introduced in later versions should use -the minor version argument of qmlRegisterType. +For the same reason, new types introduced in later versions should be tagged +with the QML_ADDED_IN_VERSION macro. This feature of the language allows for behavioural changes to be made without breaking existing applications. Consequently QML module authors @@ -276,29 +423,10 @@ should always remember to document what changed between minor versions, and QML module users should check that their application still runs correctly before deploying an updated import statement. -You may also register the revision of a base class that your type depends -upon using the qmlRegisterRevision() function: - -\code -template<typename T, int metaObjectRevision> -int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) - -template<typename T, int metaObjectRevision> -int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason) - -template<typename T, typename E, int metaObjectRevision> -int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason) -\endcode - -For example, if \c BaseType is changed and now has a revision 1, you can -specify that your type uses the new revision: - -\code -qmlRegisterRevision<BaseType,1>("MyTypes", 1, 1); -\endcode - -This is useful when deriving from base classes provided by other authors, -e.g. when extending classes from the Qt Quick module. +Revisions of a base class that your type depends upon are automatically +registered when registering the type itself. This is useful when deriving +from base classes provided by other authors, e.g. when extending classes from +the Qt Quick module. \note The QML engine does not support revisions for properties or signals of grouped and attached property objects. @@ -312,32 +440,27 @@ classes directly, if this is either not possible or is complicated by some other concerns, extension objects allow limited extension possibilities without direct modifications. -\e{Extension objects} add additional properties to an existing type. Extension -objects can only add properties, not signals or methods. An extended type -definition allows the programmer to supply an additional type, known as the -\e{extension type}, when registering the class. The properties are transparently +\e{Extension objects} add additional properties to an existing type. An extended +type definition allows the programmer to supply an additional type, known as the +\e{extension type}, when registering the class. Its members are transparently merged with the original target class when used from within QML. For example: -\snippet referenceexamples/extended/example.qml 0 +\qml +QLineEdit { + leftMargin: 20 +} +\endqml The \c leftMargin property is a new property added to an existing C++ type, \l QLineEdit, without modifying its source code. -The \l {QQmlEngine::}{qmlRegisterExtendedType()} function is for registering extended types. -Note that it has two forms. - -\code -template<typename T, typename ExtendedT> -int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) - -template<typename T, typename ExtendedT> -int qmlRegisterExtendedType() -\endcode +The QML_EXTENDED(extension) macro is for registering extended types. The +argument is the name of another class to be used as extension. -This functions should be used instead of the regular \c qmlRegisterType() -variations. The arguments are identical to the corresponding non-extension -registration functions, except for the ExtendedT parameter which is the type of -the extension object. +You can also use QML_EXTENDED_NAMESPACE(namespace) to register a namespace, and +especially the enumerations declared within, as an extension to a type. If the +type you are extending is itself a namespace, you need to use +QML_NAMESPACE_EXTENDED(namespace) instead. An extension class is a regular QObject, with a constructor that takes a QObject pointer. However, the extension class creation is delayed until the first @@ -345,9 +468,32 @@ extended property is accessed. The extension class is created and the target object is passed in as the parent. When the property on the original is accessed, the corresponding property on the extension object is used instead. -The \l{Extending QML - Extension Objects Example}{Extension Objects Example} -demonstrates a usage of extension objects. +\section2 Registering Foreign Types + +There may be C++ types that cannot be modified to hold the above mentioned +macros. Those may be types from 3rdparty libraries, or types that need to +fulfill some contract that contradicts the presence of those macros. You can +still expose those types to QML, though, using the QML_FOREIGN macro. In order +to do this, create a separate struct that consists entirely of the registration +macros, like this: + +\code +// Contains class Immutable3rdParty +#include <3rdpartyheader.h> + +struct Foreign +{ + Q_GADGET + QML_FOREIGN(Immutable3rdParty) + QML_NAMED_ELEMENT(Accessible3rdParty) + QML_ADDED_IN_VERSION(2, 4) + // QML_EXTENDED, QML_SINGLETON ... +}; +\endcode +From this code, you get a QML type with the methods and properties of +Immutable3rdParty, and the QML traits (e.g.: singleton, extended) specified in +Foreign. \section1 Defining QML-Specific Types and Attributes @@ -425,8 +571,9 @@ the attributes to be made accessible to \e attachee objects. For the attached property accesses. Consequently the attachment object may not be deleted until the attachee \c object is destroyed. -\li is declared as an attaching type, by calling the QML_DECLARE_TYPEINFO() - macro with the QML_HAS_ATTACHED_PROPERTIES flag +\li is declared as an attaching type, by adding the QML_ATTACHED(attached) macro + to the class declaration. The argument is the name of the + \e{attached object type} \endlist @@ -441,6 +588,7 @@ class Message : public QObject Q_OBJECT Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged) Q_PROPERTY(QDateTime creationDate READ creationDate WRITE setCreationDate NOTIFY creationDateChanged) + QML_ELEMENT public: // ... }; @@ -471,7 +619,8 @@ will be accessible to the \e attachee: class MessageBoardAttachedType : public QObject { Q_OBJECT - Q_PROPERTY(bool expired READ expired WRITE expired NOTIFY expiredChanged) + Q_PROPERTY(bool expired READ expired WRITE setExpired NOTIFY expiredChanged) + QML_ANONYMOUS public: MessageBoardAttachedType(QObject *parent); bool expired() const; @@ -485,20 +634,21 @@ signals: Then the \e {attaching type}, \c MessageBoard, must declare a \c qmlAttachedProperties() method that returns an instance of the \e {attached object type} as implemented by MessageBoardAttachedType. -Additionally, \c Message board must be declared as an attached type -through the QML_DECLARE_TYPEINFO() macro: +Additionally, \c MessageBoard must be declared as an attaching type +via the QML_ATTACHED() macro: \code class MessageBoard : public QObject { Q_OBJECT + QML_ATTACHED(MessageBoardAttachedType) + QML_ELEMENT public: - static MessageBoard *qmlAttachedProperties(QObject *object) + static MessageBoardAttachedType *qmlAttachedProperties(QObject *object) { return new MessageBoardAttachedType(object); } }; -QML_DECLARE_TYPEINFO(MessageBoard, QML_HAS_ATTACHED_PROPERTIES) \endcode Now, a \c Message type can access the properties and signals of the attached @@ -530,6 +680,14 @@ qDebug() << "Value of MessageBoard.expired:" << attached->expired(); \endcode +\section3 Propagating Attached Properties + +\l QQuickAttachedPropertyPropagator can be subclassed to propagate attached properties +from a parent object to its children, similar to \l {Control::}{font} and +\l {Item::}{palette} propagation. It supports propagation through +\l {Item}{items}, \l {Popup}{popups}, and \l {Window}{windows}. + + \section2 Property Modifier Types A property modifier type is a special kind of QML object type. A property @@ -577,6 +735,8 @@ Item { } \endqml +This is commonly referred to as "on" syntax. + Clients can register their own property value source types, but currently not property value write interceptors. @@ -607,6 +767,7 @@ class RandomNumberGenerator : public QObject, public QQmlPropertyValueSource Q_OBJECT Q_INTERFACES(QQmlPropertyValueSource) Q_PROPERTY(int maxValue READ maxValue WRITE setMaxValue NOTIFY maxValueChanged); + QML_ELEMENT public: RandomNumberGenerator(QObject *parent) : QObject(parent), m_maxValue(100) @@ -672,7 +833,7 @@ assignment fails does the engine call the \l the type to also be used in contexts other than just as a value source. -\section2 Specifying Default Properties for QML Object Types +\section2 Specifying Default and Parent Properties for QML Object Types Any QObject-derived type that is registered as an instantiable QML object type can optionally specify a \e {default property} for the type. A default @@ -690,6 +851,7 @@ class MessageBoard : public QObject Q_OBJECT Q_PROPERTY(QQmlListProperty<Message> messages READ messages) Q_CLASSINFO("DefaultProperty", "messages") + QML_ELEMENT public: QQmlListProperty<Message> messages(); @@ -728,6 +890,37 @@ objects added to this \c data property are also added to the list of to be declared for an item without explicitly assigning them to the \l{Item::}{children} property.) +Additionally, you can declare a "ParentProperty" Q_CLASSINFO() to inform the QML +engine which property should denote the parent object in the QML hierarchy. For +example, the Message type might be declared as follows: + +\code +class Message : public QObject +{ + Q_OBJECT + Q_PROPERTY(QObject* board READ board BINDABLE boardBindable) + Q_PROPERTY(QString author READ author BINDABLE authorBindable) + Q_CLASSINFO("ParentProperty", "board") + QML_ELEMENT + +public: + Message(QObject *parent = nullptr) : QObject(parent) { m_board = parent; } + + QObject *board() const { return m_board.value(); } + QBindable<QObject *> boardBindable() { return QBindable<QObject *>(&m_board); } + + QString author() const { return m_author.value(); } + QBindable<QString> authorBindable() { return QBindable<QString>(&m_author); } + +private: + QProperty<QObject *> m_board; + QProperty<QString> m_author; +}; +\endcode + +Defining the parent property affords \l qmllint and other tools better insight +into the intention of your code and avoids false positive warnings on some +property accesses. \section2 Defining Visual Items with the Qt Quick Module @@ -753,7 +946,7 @@ its properties have been set. For example, this may be the case if the initialization is costly, or if the initialization should not be performed until all property values have been initialized. -The \l {Qt QML} module provides the QQmlParserStatus to be subclassed for these +The \l {Qt Qml} module provides the QQmlParserStatus to be subclassed for these purposes. It defines a number of virtual methods that are invoked at various stages during component instantiation. To receive these notifications, a C++ class should inherit QQmlParserStatus and also notify the Qt meta system @@ -766,6 +959,7 @@ class MyQmlType : public QObject, public QQmlParserStatus { Q_OBJECT Q_INTERFACES(QQmlParserStatus) + QML_ELEMENT public: virtual void componentComplete() { diff --git a/src/qml/doc/src/cppintegration/exposecppattributes.qdoc b/src/qml/doc/src/cppintegration/exposecppattributes.qdoc index 52534b4a62..6031d0eebb 100644 --- a/src/qml/doc/src/cppintegration/exposecppattributes.qdoc +++ b/src/qml/doc/src/cppintegration/exposecppattributes.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-cppintegration-exposecppattributes.html \title Exposing Attributes of C++ Types to QML @@ -32,9 +8,9 @@ QML can easily be extended with functionality defined in C++ code. Due to the tight integration of the QML engine with the \l{The Meta-Object System}{Qt meta-object system}, any functionality that is appropriately exposed by a -QObject-derived class is accessible from QML code. This enables C++ data and -functions to be accessible directly from QML, often with little or no -modification. +QObject-derived class or a Q_GADGET type is accessible from QML code. This +enables C++ data and functions to be accessible directly from QML, often with +little or no modification. The QML engine has the ability to introspect QObject instances through the meta-object system. This means any QML code can access the following members of @@ -46,7 +22,7 @@ an instance of a QObject-derived class: \li Signals \endlist -(Additionally, enums are available if they have been declared with Q_ENUMS. +(Additionally, enums are available if they have been declared with Q_ENUM. See \l{qtqml-cppintegration-data.html}{Data Type Conversion Between QML and C++} for more details.) @@ -56,11 +32,27 @@ system}{registered with the QML type system}. However, if a class is to be used in a way that requires the engine to access additional type information — for example, if the class itself is to be used as a method parameter or property, or if one of its enum types is to be used in this way — then the -class may need to be registered. +class may need to be registered. Registration is recommended for all types you +use in QML, as only registered types can be analyzed at compile time. + +Registration is required for Q_GADGET types, as they don't derive from a known +common base and can't be made available automatically. Without registration, +their properties and methods are inaccessible. + +You can make C++ types from a different module available in your own module by +adding a dependency to your \l{qt_add_qml_module} call using the \e DEPENDENCIES +option. You may, for example, want to depend on QtQuick so that your QML-exposed +C++ types can use \l QColor as method arguments and return values. QtQuick +exposes \l QColor as a \l {QML Value Types}{value type} \e color. Such +dependencies may be automatically inferred at run time, but you should not rely +on this. Also note that a number of the important concepts covered in this document are demonstrated in the \l{Writing QML Extensions with C++} tutorial. +For more information about C++ and the different QML integration methods, +see the +\l {Overview - QML and C++ Integration} {C++ and QML integration overview} page. \section1 Data Type Handling and Ownership @@ -85,37 +77,70 @@ A \e property can be specified for any QObject-derived class using the Q_PROPERTY() macro. A property is a class data member with an associated read function and optional write function. -All properties of a QObject-derived class are accessible from QML. +All properties of a QObject-derived or Q_GADGET class are accessible from QML. For example, below is a \c Message class with an \c author property. As specified by the Q_PROPERTY macro call, this property is readable through the \c author() method, and writable through the \c setAuthor() method: +\note Do not use \e typedef or \e using for Q_PROPERTY types as these +will confuse moc. This may make certain type comparisons fail. + +Instead of: + +\badcode +using FooEnum = Foo::Enum; + +class Bar : public QObject +{ + Q_OBJECT + Q_PROPERTY(FooEnum enum READ enum WRITE setEnum NOTIFY enumChanged) +}; +\endcode + +Refer to the type directly: + +\code +class Bar : public QObject +{ + Q_OBJECT + Q_PROPERTY(Foo::Enum enum READ enum WRITE setEnum NOTIFY enumChanged) +}; +\endcode + +In order to make \c Message available you need to use \l{QML_ELEMENT} in C++ +and \l{qt_add_qml_module} in CMake. + \code class Message : public QObject { Q_OBJECT + QML_ELEMENT Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged) public: - void setAuthor(const QString &a) { + void setAuthor(const QString &a) + { if (a != m_author) { m_author = a; emit authorChanged(); } } - QString author() const { + + QString author() const + { return m_author; } + signals: void authorChanged(); + private: QString m_author; }; \endcode -If an instance of this class was \l{Embedding C++ Objects into QML with Context -Properties}{set as a context property} when loading a file named \c MyItem.qml -from C++: +An instance of \c Message can be passed as required property to a file called +\c MyItem.qml to make it available: \code int main(int argc, char *argv[]) { @@ -123,7 +148,7 @@ from C++: QQuickView view; Message msg; - view.engine()->rootContext()->setContextProperty("msg", &msg); + view.setInitialProperties({{"msg", &msg}}); view.setSource(QUrl::fromLocalFile("MyItem.qml")); view.show(); @@ -135,9 +160,11 @@ Then, the \c author property could be read from \c MyItem.qml: \qml // MyItem.qml -import QtQuick 2.0 +import QtQuick Text { + required property Message msg + width: 100; height: 100 text: msg.author // invokes Message::author() to get this value @@ -374,6 +401,8 @@ that is a public slot: class MessageBoard : public QObject { Q_OBJECT + QML_ELEMENT + public: Q_INVOKABLE bool postMessage(const QString &msg) { qDebug() << "Called the C++ method with" << msg; @@ -387,7 +416,7 @@ that is a public slot: }; \endcode -If an instance of \c MessageBoard was set as the context data for a file \c +If an instance of \c MessageBoard was set as the required property for a file \c MyItem.qml, then \c MyItem.qml could invoke the two methods as shown in the examples below: @@ -401,7 +430,7 @@ examples below: MessageBoard msgBoard; QQuickView view; - view.engine()->rootContext()->setContextProperty("msgBoard", &msgBoard); + view.setInitialProperties({{"msgBoard", &msgBoard}}); view.setSource(QUrl::fromLocalFile("MyItem.qml")); view.show(); @@ -416,6 +445,8 @@ examples below: import QtQuick 2.0 Item { + required property MessageBoard msgBoard + width: 100; height: 100 MouseArea { @@ -441,6 +472,54 @@ be called according to the number and the types of arguments that are provided. Values returned from C++ methods are converted to JavaScript values when accessed from JavaScript expressions in QML. +\section2 C++ methods and the 'this' object + +You may want to retrieve a C++ method from one object and call it on a different +object. Consider the following example, within a QML module called \c{Example}: + +\table +\row +\li C++ +\li +\code +class Invokable : public QObject +{ + Q_OBJECT + QML_ELEMENT +public: + Invokable(QObject *parent = nullptr) : QObject(parent) {} + + Q_INVOKABLE void invoke() { qDebug() << "invoked on " << objectName(); } +}; +\endcode +\row +\li QML +\li +\qml +import QtQml +import Example + +Invokable { + objectName: "parent" + property Invokable child: Invokable {} + Component.onCompleted: child.invoke.call(this) +} +\endqml +\endtable + +If you load the QML code from a suitable main.cpp, it should print +"invoked on parent". However, due to a long standing bug, it doesn't. +Historically, the 'this' object of C++-based methods is inseparably bound to +the method. Changing this behavior for existing code would cause subtle errors +since the 'this' object is implicit in many places. Since Qt 6.5 you can +explicitly opt into the correct behavior and allow C++ methods to accept a +'this' object. To do so, add the following pragma to your QML documents: + +\qml +pragma NativeMethodBehavior: AcceptThisObject +\endqml + +With this line added, the example above will work as expected. \section1 Exposing Signals @@ -475,7 +554,7 @@ value: \qml MessageBoard { - onNewMessagePosted: console.log("New message received:", subject) + onNewMessagePosted: (subject)=> console.log("New message received:", subject) } \endqml diff --git a/src/qml/doc/src/cppintegration/exposecppstate.qdoc b/src/qml/doc/src/cppintegration/exposecppstate.qdoc new file mode 100644 index 0000000000..8abd498c49 --- /dev/null +++ b/src/qml/doc/src/cppintegration/exposecppstate.qdoc @@ -0,0 +1,66 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! +\page qtqml-cppintegration-exposecppstate.html +\title Exposing State from C++ to QML +\brief Description of how to expose global state from C++ to QML + +It is often desirable to expose some properties from C++ to all QML elements in a +particular component, all QML elements in a module, or even all QML elements +overall. You can do this by introducing singletons or by adding properties to the +root objects of select components. + +\section1 Using Singletons + +If you want to expose a number of global properties to all elements in a module +or all elements overall, you can define a singleton in C++. To do this, add the +\l{QML_ELEMENT} or \l{QML_NAMED_ELEMENT} macros and the \l{QML_SINGLETON} macro +to a class containing the properties you want to expose as \l{Q_PROPERTY} +declarations: + +\snippet qml/exposing-state/singleton.h 0 + +Now you can access the \e thing property of the singleton from any QML code that +imports this module: + +\snippet qml/exposing-state/useSingleton.qml 0 + +If you have placed your QML files in the same directory as the module (which +is highly recommended), the singleton is available from the implicit import +within your module. You don't need to import anything explicitly. If not, or if +you want to access the \e thing property from other modules, you do need to +import the module the singleton belongs to. + +In order to set the value of the property from C++, you may need to retrieve the +singleton instance. For this purpose you may use +\l{QQmlEngine::singletonInstance}. The preferred way to do this is by giving a +module and type name as parameters: + +\snippet qml/exposing-state/singleton.h 1 + +\section1 Using Object Properties + +If you want to expose some properties to only the QML elements in a specific +component, you can add them as regular properties to the root object of the +component. In order to make sure they are actually set in all cases, you can +make them \l{Required Properties}. You might write your QML component as +follows: + +\snippet qml/exposing-state/RequiredProperties.qml 0 + +We use an ID for the root element of the component and reference the property +by ID and name from any inner objects. In order to safely make the ID of +the root element available to any nested components, we use +\l{ComponentBehavior}. + +Then, in C++, when you create an object from such a component, you need to make +sure to call the \l{QQmlComponent::createWithInitialProperties}, +\l{QQmlApplicationEngine::setInitialProperties}, or +\l{QQuickView::setInitialProperties} in order to initialize the properties. For +example: + +\snippet qml/exposing-state/createWithInitialProperties.cpp 0 + +This is assuming your module URI is \e MyModule and the module is available in +the QML import path. +*/ diff --git a/src/qml/doc/src/cppintegration/extending-tutorial-advanced.qdoc b/src/qml/doc/src/cppintegration/extending-tutorial-advanced.qdoc new file mode 100644 index 0000000000..7e489276ac --- /dev/null +++ b/src/qml/doc/src/cppintegration/extending-tutorial-advanced.qdoc @@ -0,0 +1,380 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tutorials-extending-qml-advanced-example.html +\meta tags{qml,extensions,advanced} + +\title Writing advanced QML Extensions with C++ +\brief Tutorial about advanced extensions to QML with Qt C++. + + +\section1 BirthdayParty Base Project +\c extending-qml-advanced/advanced1-Base-project + +This tutorial uses the example of a birthday party to demonstrate some of +the features of QML. The code for the various features explained below is +based on this birthday party project and relies on some of the material in the +first tutorial on \l {Writing QML Extensions with C++}{QML extensions}. This +simple example is then expanded upon to illustrate the various QML extensions +explained below. The complete code for each new extension to the code can be +found in the tutorials at the location specified under each section's title or +by following the link to the code at the very end of this page. + +\image extending-qml-advanced-word-cloud.png + +The base project defines the \c Person class and the \c BirthdayParty class, +which model the attendees and the party itself respectively. +\quotefromfile tutorials/extending-qml-advanced/advanced1-Base-project/person.h + \skipto class + \printuntil QML_ELEMENT + \dots + \skipuntil private: + \printuntil /\};/ + +\quotefromfile tutorials/extending-qml-advanced/advanced1-Base-project/birthdayparty.h + \skipto class + \printuntil QML_ELEMENT + \dots + \skipto Person *m_host = nullptr; + \printuntil /\};/ + +All the information about the party can then be stored in the corresponding QML +file. +\quotefromfile tutorials/extending-qml-advanced/advanced1-Base-project/Main.qml + \skipto BirthdayParty + \printuntil /^\}/ + +The \c main.cpp file creates a simple shell application that displays whose +birthday it is and who is invited to their party. +\quotefromfile tutorials/extending-qml-advanced/advanced1-Base-project/main.cpp + \skipto engine + \printuntil } + +The app outputs the following summary of the party. +\badcode +"Bob Jones" is having a birthday! +They are inviting: + "Leo Hodges" + "Jack Smith" + "Anne Brown" +\endcode + +The following sections go into how to add support for \c Boy and \c Girl +attendees instead of just \c Person by using inheritance and coercion, how to +make use of default properties to implicitly assign attendees of the party as +guests, how to assign properties as groups instead of one by one, how to use +attached objects to keep track of invited guests' reponses, how to use a +property value source to display the lyrics of the happy birthday song over +time, and how to expose third party objects to QML. + + + +\section1 Inheritance and Coercion +\c extending-qml-advanced/advanced2-Inheritance-and-coercion + +Right now, each attendant is being modelled as a person. This is a bit too +generic and it would be nice to be able to know more about the attendees. By +specializing them as boys and girls, we can already get a better idea of who's +coming. + +To do this, the \c Boy and \c Girl classes are introduced, both inheriting from +\c Person. +\quotefromfile tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/person.h + \skipto Boy + \printuntil /^\};/ + +\quotefromfile tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/person.h + \skipto Girl + \printuntil /^\};/ + +The \c Person class remains unaltered and the \c Boy and \c Girl C++ classes +are trivial extensions of it. The types and their QML name are registered with +the QML engine with \l QML_ELEMENT. + +Notice that the \c host and \c guests properties in \c BirthdayParty still take +instances of \c Person. +\quotefromfile tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/birthdayparty.h + \skipto BirthdayParty + \printuntil QML_ELEMENT + \dots + \skipto /^\};/ + \printuntil /^\};/ + +The implementation of the \c Person class itself has not been changed. However, +as the \c Person class was repurposed as a common base for \c Boy and \c Girl, +\c Person should no longer be instantiable from QML directly. An explicit +\c Boy or \c Girl should be instantiated instead. +\quotefromfile tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/person.h + \skipto Person + \printto Q_OBJECT + \dots + \skipto QML_ELEMENT + \printuntil QML_UNCREATABLE + \dots + \skipto /^\};/ + \printuntil /^\};/ + +While we want to disallow instantiating \c Person from within QML, it still +needs to be registered with the QML engine so that it can be used as a property +type and other types can be coerced to it. This is what the QML_UNCREATABLE +macro does. As all three types, \c Person, \c Boy and \c Girl, have been +registered with the QML system, on assignment, QML automatically (and type-safely) +converts the \c Boy and \c Girl objects into a \c Person. + +With these changes in place, we can now specify the birthday party with the +extra information about the attendees as follows. +\quotefromfile tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/Main.qml + \skipto BirthdayParty + \printuntil /^\}/ + + + +\section1 Default Properties +\c extending-qml-advanced/advanced3-Default-properties + +Currently, in the QML file, each property is assigned explicitly. For example, +the \c host property is assigned a \c Boy and the \c guests property is +assigned a list of \c Boy or \c Girl. This is easy but it can be made a bit +simpler for this specific use case. Instead of assigning the \c guests property +explicitly, we can add \c Boy and \c Girl objects inside the party directly +and have them assigned to \c guests implicitly. It makes sense that all the +attendees that we specify, and that are not the host, are guests. This change +is purely syntactical but it can add a more natural feel in many situations. + +The \c guests property can be designated as the default property of +\c BirthdayParty. Meaning that each object created inside of a \c BirthdayParty +is implicitly appended to the default property \c guests. The resulting QML +looks like this. +\quotefromfile tutorials/extending-qml-advanced/advanced3-Default-properties/Main.qml + \skipto BirthdayParty + \printuntil /^\}/ + +The only change required to enable this behavior is to add the \c DefaultProperty +class info annotation to \c BirthdayParty to designate \c guests as its default +property. +\quotefromfile tutorials/extending-qml-advanced/advanced3-Default-properties/birthdayparty.h + \skipto class + \printuntil QML_ELEMENT + \dots + \skipto /^\};/ + \printuntil /^\};/ + +You may already be familiar with this mechanism. The default property for all +descendants of \c Item in QML is the \c data property. All elements not +explicitly added to a property of an \c Item will be added to \c data. This +makes the structure clear and reduces unnecessary noise in the code. + +\sa {Specifying Default and Parent Properties for QML Object Types} + + + +\section1 Grouped Properties +\c extending-qml-advanced/advanced4-Grouped-properties + +More information is needed about the shoes of the guests. Aside from their +size, we also want to store the shoes' color, brand, and price. This +information is stored in a \c ShoeDescription class. +\quotefromfile tutorials/extending-qml-advanced/advanced4-Grouped-properties/person.h + \skipto ShoeDescription + \printuntil price + \dots + \skipto /^\};/ + \printuntil /^\};/ + +Each person now has two properties, a \c name and a shoe description \c shoe. +\quotefromfile tutorials/extending-qml-advanced/advanced4-Grouped-properties/person.h + \skipto Person + \printuntil shoe + \dots + \skipto /^\};/ + \printuntil /^\};/ + +Specifying the values for each element of the shoe description works but is a +bit repetitive. +\quotefromfile tutorials/extending-qml-advanced/advanced4-Grouped-properties/Main.qml + \skipto Girl + \printuntil } + +Grouped properties provide a more elegant way of assigning these properties. +Instead of assigning the values to each property one-by-one, the individual +values can be passed as a group to the \c shoe property making the code more +readable. No changes are required to enable this feature as it is available by +default for all of QML. +\quotefromfile tutorials/extending-qml-advanced/advanced4-Grouped-properties/Main.qml + \skipto host + \printuntil /^....}/ + +\sa {Grouped Properties} + + + +\section1 Attached Properties +\c extending-qml-advanced/advanced5-Attached-properties + +The time has come for the host to send out invitations. To keep track of which +guests have responded to the invitation and when, we need somewhere to store +that information. Storing it in the \c BirthdayParty object iself would not +really fit. A better way would be to store the responses as attached objects to +the party object. + +First, we declare the \c BirthdayPartyAttached class which holds the guest reponses. +\quotefromfile tutorials/extending-qml-advanced/advanced5-Attached-properties/birthdayparty.h + \skipto BirthdayPartyAttached + \printuntil QML_ANONYMOUS + \dots + \skipto /^\};/ + \printuntil /^\};/ + +And we attach it to the \c BirthdayParty class and define +\c qmlAttachedProperties() to return the attached object. +\quotefromfile tutorials/extending-qml-advanced/advanced5-Attached-properties/birthdayparty.h + \skipto /BirthdayParty : public QObject/ + \printuntil /^{/ + \dots + \skipto QML_ATTACHED + \printuntil QML_ATTACHED + \dots + \skipto qmlAttachedProperties + \printuntil qmlAttachedProperties + \skipto /^\};/ + \printuntil /^\};/ + +Now, attached objects can be used in the QML to hold the rsvp information of the invited guests. +\quotefromfile tutorials/extending-qml-advanced/advanced5-Attached-properties/Main.qml + \skipto BirthdayParty + \printuntil /^}/ + +Finally, the information can be accessed in the following way. +\quotefromfile tutorials/extending-qml-advanced/advanced5-Attached-properties/main.cpp + \skipto rsvpDate + \printuntil attached->property("rsvp").toDate(); + +The program outputs the following summary of the party to come. +\badcode +"Jack Smith" is having a birthday! +He is inviting: + "Robert Campbell" RSVP date: "Wed Mar 1 2023" + "Leo Hodges" RSVP date: "Mon Mar 6 2023" +\endcode + +\sa {Providing Attached Properties} + + + +\section1 Property Value Source +\c extending-qml-advanced/advanced6-Property-value-source + +During the party the guests have to sing for the host. It would be handy if the +program could display the lyrics customized for the occasion to help the +guests. To this end, a property value source is used to generate the verses of +the song over time. +\quotefromfile tutorials/extending-qml-advanced/advanced6-Property-value-source/happybirthdaysong.h + \skipto class + \printuntil Q_INTERFACES + \dots + \skipto setTarget + \printuntil setTarget + \skipto /^\};/ + \printuntil /^\};/ + +The class \c HappyBirthdaySong is added as a value source. It must inherit from +\c QQmlPropertyValueSource and implement the QQmlPropertyValueSource interface +with the Q_INTERFACES macro. The \c setTarget() function is used to define +which property this source acts upon. In this case, the value source writes to +the \c announcement property of the \c BirthdayParty to display the lyrics +over time. It has an internal timer that causes the \c announcement +property of the party to be set to the next line of the lyrics repeatedly. + +In QML, a \c HappyBirthdaySong is instantiated inside the \c BirthdayParty. The +\c on keyword in its signature is used to specify the property that the value +source targets, in this case \c announcement. The \c name property of the +\c HappyBirthdaySong object is also \l {Property Binding}{bound} to the name of +the host of the party. +\quotefromfile tutorials/extending-qml-advanced/advanced6-Property-value-source/Main.qml + \skipto BirthdayParty + \printuntil } + \dots + \skipto /^\}/ + \printuntil /^\}/ + +The program displays the time at which the party started using the +\c partyStarted signal and then prints the following happy birthday verses +over and over. +\badcode +Happy birthday to you, +Happy birthday to you, +Happy birthday dear Bob Jones, +Happy birthday to you! +\endcode + +\sa {Property Value Sources} + + + +\section1 Foreign objects integration +\c extending-qml-advanced/advanced7-Foreign-objects-integration + +Instead of just printing the lyrics out to the console, the attendees would +like to use a more fancy display with support for colors. They would like to +integrate it in the project but currently it is not possible to configure the +screen from QML because it comes from a third party library. To solve this, the +necessary types need to be exposed to the QML engine so its properties are +available for modification in QML directly. + +The display can be controlled by the \c ThirdPartyDisplay class. It has +properties to define the content and the foreground and background colors of the text +to display. +\quotefromfile tutorials/extending-qml-advanced/advanced7-Foreign-objects-integration/library/ThirdPartyDisplay.h + \skipto ThirdPartyDisplay + \printuntil backgroundColor + \dots + \skipto }; + \printuntil }; + +To expose this type to QML, we can register it with the engine with +QML_ELEMENT. However, since the class isn't accessible for modification, +QML_ELEMENT cannot simply be added to it. To register the type with the engine, +the type needs to be registered from the outside. This is what QML_FOREIGN is +for. When used in a type in conjunction with other QML macros, the other macros +apply not to the type they reside in but to the foreign type designated by +QML_FOREIGN. +\quotefromfile tutorials/extending-qml-advanced/advanced7-Foreign-objects-integration/foreigndisplay.h + \skipto ForeignDisplay + \printuntil }; + +This way, the BirthdayParty now has a new property with the display. +\quotefromfile tutorials/extending-qml-advanced/advanced7-Foreign-objects-integration/birthdayparty.h + \skipuntil BirthdayPartyAttached + \skipto BirthdayParty + \printto Q_CLASSINFO + \dots + \skipto }; + \printuntil }; + +And, in QML, the colors of the text on the fancy third display can be set explicitly. +\quotefromfile tutorials/extending-qml-advanced/advanced7-Foreign-objects-integration/Main.qml + \skipto BirthdayParty + \printuntil BirthdayParty + \skipto display: + \printuntil } + \dots + \skipto /^}/ + \printuntil /^}/ + +Setting the \c announcement property of the BirthdayParty now sends the +message to the fancy display instead of printing it itself. +\quotefromfile tutorials/extending-qml-advanced/advanced7-Foreign-objects-integration/birthdayparty.cpp + \skipto setAnnouncement + \printuntil /^}/ + +The output then looks like this over and over similar to the previous section. +\badcode +[Fancy ThirdPartyDisplay] Happy birthday to you, +[Fancy ThirdPartyDisplay] Happy birthday to you, +[Fancy ThirdPartyDisplay] Happy birthday dear Bob Jones, +[Fancy ThirdPartyDisplay] Happy birthday to you! +\endcode + +\sa {Registering Foreign Types} +*/ diff --git a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc index 26556644d6..156ad47089 100644 --- a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc +++ b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc @@ -1,36 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\example tutorials/extending-qml +\page qtqml-tutorials-extending-qml-example.html \title Writing QML Extensions with C++ \brief Tutorial about extending QML with Qt C++. -The \l {Qt QML} module provides a set of APIs for extending QML through +The \l {Qt Qml} module provides a set of APIs for extending QML through C++ extensions. You can write extensions to add your own QML types, extend existing Qt types, or call C/C++ functions that are not accessible from ordinary QML code. @@ -39,18 +15,24 @@ core QML features, including properties, signals and bindings. It also shows how extensions can be deployed through plugins. Many of the topics covered in this tutorial are documented in further detail in -\l {qtqml-cppintegration-topic.html}{Integrating QML and C++} and its documentation -sub-topics. In particular, you may be interested in the sub-topics +\l{Overview - QML and C++ Integration} and its documentation sub-topics. In +particular, you may be interested in the sub-topics \l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Classes to QML} and \l {qtqml-cppintegration-definetypes.html}{Defining QML Types from C++}. -\section1 Running the Tutorial Examples +\section1 Opening the Tutorial Sources -The code in this tutorial is available as an example project with subprojects -associated with each tutorial chapter. In \l{Qt Creator Manual}{Qt Creator}, open -the \uicontrol Welcome mode and select the tutorial from \uicontrol Examples. In -\uicontrol Edit mode, expand the \e extending-qml project, right-click on the -subproject (chapter) you want to run and select \uicontrol Run. +The code in this tutorial is available as part of the Qt sources. +If you installed Qt with the \QOI, you can +find the sources in the Qt installation directory under +Examples/Qt-\QtVersion/qml/tutorials/extending-qml/. + +\section1 Creating Project from Scratch + +Alternatively, you can follow the tutorial by creating the sources from scratch: +For each chapter, create a new project using the \e {Qt Quick Application} template +in Qt Creator, as instructed in \l {Qt Creator: Creating Qt Quick Projects}. +Then follow along by adapting and extending the generated skeleton code. \section1 Chapter 1: Creating a New Type \c extending-qml/chapter1-basics @@ -72,15 +54,15 @@ a version of 1.0. We want this \c PieChart type to be usable from QML like this: -\badcode - import Charts 1.0 +\qml + import Charts PieChart { width: 100; height: 100 name: "A simple pie chart" color: "red" } -\endcode +\endqml To do this, we need a C++ class that encapsulates this \c PieChart type and its two properties. Since QML makes extensive use of Qt's \l{Meta-Object System}{meta object system}, @@ -91,77 +73,103 @@ this new class must: \li Declare its properties using the Q_PROPERTY macro \endlist +\section2 Class Declaration + Here is our \c PieChart class, defined in \c piechart.h: \snippet tutorials/extending-qml/chapter1-basics/piechart.h 0 The class inherits from QQuickPaintedItem because we want to override -QQuickPaintedItem::paint() in perform drawing operations with the QPainter API. +QQuickPaintedItem::paint() to perform drawing operations with the QPainter API. If the class just represented some data type and was not an item that actually needed to be displayed, it could simply inherit from QObject. Or, if we want to extend the functionality of an existing QObject-based class, it could inherit from that class instead. Alternatively, if we want to create a visual item that doesn't need to perform drawing operations with the QPainter API, we can just subclass QQuickItem. -The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro, -and overrides QQuickPaintedItem::paint(). The class implementation in \c piechart.cpp -simply sets and returns the \c m_name and \c m_color values as appropriate, and -implements \c paint() to draw a simple pie chart. It also turns off the -QGraphicsItem::ItemHasNoContents flag to enable painting: +The \c PieChart class defines the two properties, \c name and \c color, with the +Q_PROPERTY macro, and overrides QQuickPaintedItem::paint(). The \c PieChart +class is registered using the QML_ELEMENT macro, to allow it to be used from +QML. If you don't register the class, \c App.qml won't be able to create a +\c PieChart. + +\section2 qmake Setup + +For the registration to take effect, the \c qmltypes option is added to +\c CONFIG in the project file and a \c QML_IMPORT_NAME and +\c QML_IMPORT_MAJOR_VERSION are given: + +\snippet tutorials/extending-qml/chapter1-basics/chapter1-basics.pro 0 + +\section2 CMake Setup + +Similarly, for the registration to take effect when using CMake, use the +\l{qt6_add_qml_module} {qt_add_qml_module} command: + +\snippet tutorials/extending-qml/chapter1-basics/CMakeLists.txt 0 + +\section2 Class Implementation + +The class implementation in \c piechart.cpp simply sets and returns the +\c m_name and \c m_color values as appropriate, and implements \c paint() to +draw a simple pie chart: \snippet tutorials/extending-qml/chapter1-basics/piechart.cpp 0 \dots 0 \snippet tutorials/extending-qml/chapter1-basics/piechart.cpp 1 -Now that we have defined the \c PieChart type, we will use it from QML. The \c app.qml -file creates a \c PieChart item and display the pie chart's details +\section2 QML Usage + +Now that we have defined the \c PieChart type, we will use it from QML. The \c +App.qml file creates a \c PieChart item and displays the pie chart's details using a standard QML \l Text item: -\snippet tutorials/extending-qml/chapter1-basics/app.qml 0 +\snippet tutorials/extending-qml/chapter1-basics/App.qml 0 Notice that although the color is specified as a string in QML, it is automatically converted to a QColor object for the PieChart \c color property. Automatic conversions are -provided for various other \l {QML Basic Types}{basic types}; for example, a string +provided for various other \l {QML Value Types}{value types}. For example, a string like "640x480" can be automatically converted to a QSize value. We'll also create a C++ application that uses a QQuickView to run and -display \c app.qml. The application must register the \c PieChart type -using the qmlRegisterType() function, to allow it to be used from QML. If -you don't register the type, \c app.qml won't be able to create a \c PieChart. +display \c App.qml. Here is the application \c main.cpp: \snippet tutorials/extending-qml/chapter1-basics/main.cpp 0 -This call to qmlRegisterType() registers the \c PieChart type as a type called "PieChart", -in a type namespace called "Charts", with a version of 1.0. +\section2 Project Build -Lastly, we write a \c .pro project file that includes the files and the \c declarative library: +To build the project we include the files, link against the libraries, and +define a type namespace called "Charts" with version 1.0 for any types exposed +to QML. + +Using qmake: \quotefile tutorials/extending-qml/chapter1-basics/chapter1-basics.pro +Using CMake: + +\quotefile tutorials/extending-qml/chapter1-basics/CMakeLists.txt + Now we can build and run the application: \image extending-tutorial-chapter1.png -\note You may see a warning \e {Expression ... depends on non-NOTIFYable properties: +\note You may see a warning \e {Expression ... depends on non-NOTIFYable properties: PieChart::name}. This happens because we add a binding to the writable \c name property, but haven't yet defined a notify signal for it. The QML engine therefore cannot update the binding if the \c name value changes. This is addressed in the following chapters. -The source code from the following files are referred to in this chapter: -\noautolist -\generatelist examplefiles .*chapter1.* - \section1 Chapter 2: Connecting to C++ Methods and Signals \c extending-qml/chapter2-methods Suppose we want \c PieChart to have a "clearChart()" method that erases the -chart and then emits a "chartCleared" signal. Our \c app.qml would be able +chart and then emits a "chartCleared" signal. Our \c App.qml would be able to call \c clearChart() and receive \c chartCleared() signals like this: -\snippet tutorials/extending-qml/chapter2-methods/app.qml 0 +\snippet tutorials/extending-qml/chapter2-methods/App.qml 0 \image extending-tutorial-chapter2.png @@ -193,8 +201,7 @@ disappears, and the application outputs: qml: The chart has been cleared \endcode -The source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter2.* + \section1 Chapter 3: Adding Property Bindings \c extending-qml/chapter3-bindings @@ -206,7 +213,7 @@ other types' values when property values are changed. Let's enable property bindings for the \c color property. That means if we have code like this: -\snippet tutorials/extending-qml/chapter3-bindings/app.qml 0 +\snippet tutorials/extending-qml/chapter3-bindings/App.qml 0 \image extending-tutorial-chapter3.png @@ -229,7 +236,7 @@ is emitted whenever the value changes. \dots \snippet tutorials/extending-qml/chapter3-bindings/piechart.h 3 -Then, we emit this signal in \c setPieSlice(): +Then, we emit this signal in \c setColor(): \snippet tutorials/extending-qml/chapter3-bindings/piechart.cpp 0 @@ -244,8 +251,7 @@ automatically updated and cannot be used as flexibly in QML. Also, since bindings are invoked so often and relied upon in QML usage, users of your custom QML types may see unexpected behavior if bindings are not implemented. -The source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter3.* + \section1 Chapter 4: Using Custom Property Types @@ -289,7 +295,7 @@ For example, let's replace the use of the \c property with a type called "PieSlice" that has a \c color property. Instead of assigning a color, we assign an \c PieSlice value which itself contains a \c color: -\snippet tutorials/extending-qml/chapter4-customPropertyTypes/app.qml 0 +\snippet tutorials/extending-qml/chapter4-customPropertyTypes/App.qml 0 Like \c PieChart, this new \c PieSlice type inherits from QQuickPaintedItem and declares its properties with Q_PROPERTY(): @@ -314,18 +320,27 @@ item when its contents are drawn: \snippet tutorials/extending-qml/chapter4-customPropertyTypes/piechart.cpp 0 -Like the \c PieChart type, the \c PieSlice type has to be registered -using qmlRegisterType() to be used from QML. As with \c PieChart, we'll add the -type to the "Charts" type namespace, version 1.0: +Like the \c PieChart type, the \c PieSlice type has to be exposted to QML +using QML_ELEMENT. -\snippet tutorials/extending-qml/chapter4-customPropertyTypes/main.cpp 0 +\snippet tutorials/extending-qml/chapter4-customPropertyTypes/pieslice.h 0 \dots -\snippet tutorials/extending-qml/chapter4-customPropertyTypes/main.cpp 1 + +As with \c PieChart, we add the "Charts" type namespace, version 1.0, to our +build file: + +Using qmake: + +\quotefile tutorials/extending-qml/chapter4-customPropertyTypes/chapter4-customPropertyTypes.pro + +Using CMake: + \dots -\snippet tutorials/extending-qml/chapter4-customPropertyTypes/main.cpp 2 +\snippet tutorials/extending-qml/chapter4-customPropertyTypes/CMakeLists.txt 0 +\snippet tutorials/extending-qml/chapter4-customPropertyTypes/CMakeLists.txt 1 +\dots + -The source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter4.* \section1 Chapter 5: Using List Property Types \c extending-qml/chapter5-listproperties @@ -334,7 +349,7 @@ Right now, a \c PieChart can only have one \c PieSlice. Ideally a chart would have multiple slices, with different colors and sizes. To do this, we could have a \c slices property that accepts a list of \c PieSlice items: -\snippet tutorials/extending-qml/chapter5-listproperties/app.qml 0 +\snippet tutorials/extending-qml/chapter5-listproperties/App.qml 0 \image extending-tutorial-chapter5.png @@ -369,14 +384,13 @@ The \c PieSlice class has also been modified to include \c fromAngle and \c angl properties and to draw the slice according to these values. This is a straightforward modification if you have read the previous pages in this tutorial, so the code is not shown here. -The source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter5.* + \section1 Chapter 6: Writing an Extension Plugin \c extending-qml/chapter6-plugins -Currently the \c PieChart and \c PieSlice types are used by \c app.qml, +Currently the \c PieChart and \c PieSlice types are used by \c App.qml, which is displayed using a QQuickView in a C++ application. An alternative way to use our QML extension is to create a plugin library to make it available to the QML engine as a new QML import module. This allows the \c PieChart and @@ -385,33 +399,33 @@ by any QML application, instead of restricting these types to be only used by the one application. The steps for creating a plugin are described in \l {Creating C++ Plugins for QML}. -To start with, we create a plugin class named \c ChartsPlugin. It subclasses QQmlExtensionPlugin -and registers our QML types in the inherited \l{QQmlExtensionPlugin::}{registerTypes()} method. +To start with, we create a plugin class named \c ChartsPlugin. It subclasses +QQmlEngineExtensionPlugin and uses the Q_PLUGIN_METADATA() macro to register the +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 configure the build file to define the project as a plugin library. -And its implementation in \c chartsplugin.cpp: +Using qmake: -\snippet tutorials/extending-qml/chapter6-plugins/import/chartsplugin.cpp 0 +\quotefile tutorials/extending-qml/chapter6-plugins/Charts/Charts.pro -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. +Using CMake: -\quotefile tutorials/extending-qml/chapter6-plugins/import/import.pro +\quotefile tutorials/extending-qml/chapter6-plugins/Charts/CMakeLists.txt 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. This way, the QML engine will find our module as the default search path for QML imports includes the directory of the application executable. On \macos, the -plugin binary is copied to \c Contents/PlugIns in the the application bundle; -this path is set in \l {tutorials/extending-qml/chapter6-plugins/app.pro} -{chapter6-plugins/app.pro}: +plugin binary is copied to \c Contents/PlugIns in the the application bundle. +With qmake, 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 @@ -430,23 +444,22 @@ 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: +\c App.qml, which uses the \c {import Charts 1.0} statement. Alternatively, you can +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 module will be available for use in any QML document which imports it. -The source code from the following files are referred to in this chapter: -\generatelist examplefiles .*chapter6.* + \section1 Chapter 7: Summary @@ -454,7 +467,7 @@ In this tutorial, we've shown the basic steps for creating a QML extension: \list \li Define new QML types by subclassing QObject and registering them with - qmlRegisterType() + QML_ELEMENT or QML_NAMED_ELEMENT() \li Add callable methods using \l Q_INVOKABLE or Qt slots, and connect to Qt signals with an \c onSignal syntax \li Add property bindings by defining \l{Qt's Property System}{NOTIFY} signals @@ -464,9 +477,9 @@ In this tutorial, we've shown the basic steps for creating a QML extension: \l {Module Definition qmldir Files}{qmldir} file \endlist -The \l{Integrating QML and C++} documentation shows -other useful features that can be added to QML extensions. For example, we -could use \l{Default Properties}{default properties} to allow +The \l{Overview - QML and C++ Integration}{QML and C++ Integration overview} +documentation shows other useful features that can be added to QML extensions. +For example, we could use \l{Default Properties}{default properties} to allow slices to be added without using the \c slices property: \badcode @@ -485,5 +498,6 @@ Or randomly add and remove slices from time to time using \l{Property Value Sour } \endcode -\sa {Integrating QML and C++} +\note To continue learning about QML extensions and features follow the +\l {Writing advanced QML Extensions with C++} tutorial. */ 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..aac9c080d8 --- /dev/null +++ b/src/qml/doc/src/cppintegration/integrating-with-js-values-from-cpp.qdoc @@ -0,0 +1,162 @@ +// Copyright (C) 2012 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! +\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 \l {QJSManagedValue::}{deleteProperty} and + \l {QJSManagedValue::}{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 9c33979f40..eb866eb843 100644 --- a/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc +++ b/src/qml/doc/src/cppintegration/interactqmlfromcpp.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-cppintegration-interactqmlfromcpp.html \title Interacting with QML Objects from C++ @@ -41,6 +17,9 @@ into a C++ application. Once a QML object is created, it can be inspected from C++ in order to read and write to properties, invoke methods and receive signal notifications. +For more information about C++ and the different QML integration methods, +see the +\l {Overview - QML and C++ Integration} {C++ and QML integration overview} page. \section1 Loading QML Objects from C++ @@ -105,6 +84,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"_s, 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 @@ -166,9 +227,12 @@ updated, and any \c onButtonTextChanged handlers would not be called. \section2 Invoking QML Methods -All QML methods are exposed to the meta-object system and can be called from C++ -using QMetaObject::invokeMethod(). Method parameters and return values passed -from QML are always translated into QVariant values in C++. +All QML methods are exposed to the meta-object system and can be called from +C++ using QMetaObject::invokeMethod(). You can specify types for the parameters +and the return value after the colon character, as shown in the code snippet +below. This can be useful, for example, when you want to connect a signal in +C++ with a certain signature to a QML-defined method. If you omit the types, +the C++ signature will use QVariant. Here is a C++ application that calls a QML method using QMetaObject::invokeMethod(): @@ -182,10 +246,13 @@ QMetaObject::invokeMethod(): \li \snippet qml/qtbinding/functions-qml/main.cpp 0 \endtable -Notice the Q_RETURN_ARG() and Q_ARG() arguments for QMetaObject::invokeMethod() -must be specified as QVariant types, as this is the generic data type used for -QML method parameters and return values. +Notice the parameter and return type specified after the colon. You can use \l +{QML Value Types}{value types} and \l {QML Object Types}{object types} as type +names. +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 @@ -210,9 +277,8 @@ QObject::connect(), so that the \c cppSlot() method is called whenever the \snippet qml/qtbinding/signals-qml/main.cpp 0 \endtable -When a QML object type is used as a signal parameter, the parameter should -use \l var as the type, and the value should be received in C++ using the -QVariant type: +A QML object type in a signal parameter is translated to a pointer to the class +in C++: \table \row @@ -226,7 +292,7 @@ QVariant type: id: item width: 100; height: 100 - signal qmlSignal(var anObject) + signal qmlSignal(anObject: Item) MouseArea { anchors.fill: parent @@ -241,18 +307,16 @@ QVariant type: { Q_OBJECT public slots: - void cppSlot(const QVariant &v) { - qDebug() << "Called the C++ slot with value:" << v; + void cppSlot(QQuickItem *item) { + qDebug() << "Called the C++ slot with item:" << item; - QQuickItem *item = - qobject_cast<QQuickItem*>(v.value<QObject*>()); qDebug() << "Item dimensions:" << item->width() << item->height(); } }; int main(int argc, char *argv[]) { - QApplication app(argc, argv); + QGuiApplication app(argc, argv); QQuickView view(QUrl::fromLocalFile("MyItem.qml")); QObject *item = view.rootObject(); diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc index fbb654378d..b14c54a24e 100644 --- a/src/qml/doc/src/cppintegration/topic.qdoc +++ b/src/qml/doc/src/cppintegration/topic.qdoc @@ -1,96 +1,13 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qtqml-cppintegration-topic.html -\title Integrating QML and C++ -\brief Provides instruction to integrate QML and C++ - -QML applications often need to handle more advanced and performance-intensive -tasks in C++. The most common and quickest way to do this is to expose the C++ -class to the QML runtime, provided the C++ implementation is derived from -QObject. Assuming that you have Qt 5.7 or later installed, the following -step-by-step instructions guide you through the process of using the C++ class, -BackEnd, in a QML application: - -\list 1 - -\li Create a new project using the "Qt Quick Application" template in Qt Creator - -\note Uncheck the \uicontrol {With ui.qml file} option in the -\uicontrol {Define Project Details} section of \uicontrol {New Project Wizard}. - -\li Add a new C++ class called \c BackEnd to the project and replace its header -file contents with: - -\snippet code/backend/backend.h backend_header - -The \c Q_PROPERTY macro declares a property that could be accessed from QML. - -\li Replace its C++ file contents with: - -\snippet code/backend/backend.cpp backend_cpp - -The \c setUserName function emits the \c userNameChanged signal every time -\c m_userName value changes. The signal can be handled from QML using the -\c onUserNameChanged handler. - -\li Include \c "backend.h" in \c main.cpp and register the class as a QML type -under a import URL as shown below: - -\snippet code/backend/main.cpp main_cpp - -The BackEnd class is registered as a type, which is accessible from QML by -importing the URL, "\c{io.qt.examples.backend 1.0}". - -\li Replace the contents of \c main.qml with the following code: - -\snippet code/backend/main.qml main_qml - -The \c BackEnd instance lets you access the \c userName property, which -is updated when the TextField's \c text property changes. - -\endlist - -Now the application can be run. - -\borderedimage cppintegration-ex.png -\caption Application running on Ubuntu - -Qt offers several methods to integrate C++ with QML, and the method discussed -in this tutorial is just one of them. For more details about these methods, -refer to \l{Overview - QML and C++ Integration}. -*/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-cppintegration-overview.html \title Overview - QML and C++ Integration \brief Highlights important points about integrating C++ with QML. +\ingroup explanations-programminglanguages -QML is designed to be easily extensible through C++ code. The classes in the \l {Qt QML} module +QML is designed to be easily extensible through C++ code. The classes in the \l {Qt Qml} module enable QML objects to be loaded and manipulated from C++, and the nature of QML engine's integration with Qt's \l{Meta Object System}{meta object system} enables C++ functionality to be invoked directly from QML. This allows the development of hybrid applications which are implemented @@ -104,7 +21,7 @@ with QML and JavaScript within \l{qtqml-documents-topic.html}{QML documents}, an C++ \li Use and invoke some C++ functionality from QML (for example, to invoke your application logic, use a data model implemented in C++, or call some functions in a third-party C++ library) -\li Access functionality in the \l {Qt QML} or \l {Qt Quick} C++ API (for example, to dynamically generate +\li Access functionality in the \l {Qt Qml} or \l {Qt Quick} C++ API (for example, to dynamically generate images using QQuickImageProvider) \li Implement your own \l{qtqml-typesystem-objecttypes.html}{QML object types} from C++ \unicode{0x2014} whether for use within your own specific application, or for distribution to others @@ -132,11 +49,15 @@ methods and signals to be accessed from QML These are the most common methods of accessing C++ functionality from QML code; for more options and details, see the main documentation pages that are described in the sections further below. -Additionally, aside from the ability to access C++ functionality from QML, the \l {Qt QML} module also +Additionally, aside from the ability to access C++ functionality from QML, the \l {Qt Qml} module also provides ways to do the reverse and manipulate QML objects from C++ code. See \l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++} for more details. +It is often desirable to expose some state as global properties to QML. +\l{qtqml-cppintegration-exposecppstate.html}{Exposing State from C++ to QML} +describes how to do this. + Finally, the C++ code may be integrated into either a C++ application or a C++ plugin depending on whether it is to be distributed as a standalone application or a library. A plugin can be integrated with a QML module that can then be imported and used by QML code in other applications; see @@ -148,7 +69,10 @@ information. To quickly determine which integration method is appropriate for your situation, the following flowchart can be used: -\image cpp-qml-integration-flowchart +\image cpp-qml-integration-flowchart.png + +For a description of the macros in the flowchart, see the +\l {qtqml-cppintegration-definetypes.html}{Defining QML Types from C++} documentation. \section1 Exposing Attributes of C++ Classes to QML @@ -171,7 +95,7 @@ registered for other purposes: for example, it could be registered as a \e {Sing single class instance to be imported by QML code, or it could be registered to enable the enumeration values of a non-instantiable class to be accessible from QML. -Additionally, the \l {Qt QML} module provides mechanisms to define QML types that integrate with QML +Additionally, the \l {Qt Qml} module provides mechanisms to define QML types that integrate with QML concepts like attached properties and default properties. For more information on registering and creating custom QML types from C++, see the \l @@ -182,7 +106,7 @@ For more information on registering and creating custom QML types from C++, see C++ objects and values can be embedded directly into the context (or \e scope) of loaded QML objects using \e {context properties} and \e {context objects}. This is achieved through the QQmlContext -class provided by the \l {Qt QML} module, which exposes data to the context of a QML component, allowing +class provided by the \l {Qt Qml} module, which exposes data to the context of a QML component, allowing data to be injected from C++ into QML. See \l{qtqml-cppintegration-contextproperties.html}{Embedding C++ Objects into QML with Context @@ -199,7 +123,8 @@ dynamically load and introspect objects through the Qt meta object system. \include warning.qdocinc For more information on accessing QML objects from C++, see the documentation on -\l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++}. +\l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++}, +and the \l {Exposing Data from C++ to QML} section of the Best Practices page. \section1 Data Type Conversion Between QML and C++ diff --git a/src/qml/doc/src/examples.qdoc b/src/qml/doc/src/examples.qdoc deleted file mode 100644 index 7aad09ecee..0000000000 --- a/src/qml/doc/src/examples.qdoc +++ /dev/null @@ -1,71 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\group qmlextendingexamples -\title Qt QML Examples -\brief List of Qt QML examples for reference. - -The list of examples demonstrating how to extend C++ to QML or the other way -around. - -\noautolist - -\table - \row - \li \l {Extending QML - Adding Types Example} - \li Exporting C++ Classes - \row - \li \l {Extending QML - Object and List Property Types Example} - \li Exporting C++ Properties - \row - \li \l {Extending QML - Extension Objects Example} - \li Extension Objects - \row - \li \l {Extending QML - Inheritance and Coercion Example} - \li C++ Inheritance and Coercion - \row - \li \l {Extending QML - Methods Example} - \li Methods Support - \row - \li \l {Extending QML - Attached Properties Example} - \li Attached Properties - \row - \li \l {Extending QML - Signal Support Example} - \li Signal Support - \row - \li \l {Extending QML - Property Value Source Example} - \li Property Value Source - \row - \li \l {Extending QML - Default Property Example} - \li Default Property - \row - \li \l {Extending QML - Grouped Properties Example} - \li Grouped Properties -\endtable - -*/ diff --git a/src/qml/doc/src/external-resources.qdoc b/src/qml/doc/src/external-resources.qdoc index 68c5ab4664..6ea7e4a005 100644 --- a/src/qml/doc/src/external-resources.qdoc +++ b/src/qml/doc/src/external-resources.qdoc @@ -1,78 +1,80 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \externalpage http://www.ecma-international.org/publications/standards/Ecma-262.htm + \externalpage https://www.ecma-international.org/publications-and-standards/standards/ecma-262/ \title ECMA-262 */ /*! - \externalpage http://qmlbook.github.io/ - \title Qt5 Cadaques + \externalpage https://www.w3schools.com/jsref/default.asp + \title W3Schools JavaScript Reference */ /*! - \externalpage http://www.w3schools.com/jsref/default.asp - \title W3Schools JavaScript Reference + \externalpage https://tc39.es/ecma262/#sec-date-objects + \title ECMAScript Specification of Date */ /*! - \externalpage https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date - \title Mozilla Developer Network Date Reference + \externalpage https://www.qt.io/product/testing-tools#squish + \title Squish GUI Test Automation Tool */ /*! - \externalpage hhttps://www.froglogic.com/squish/gui-testing - \title Squish + \externalpage https://doc.qt.io/GammaRay + \title GammaRay Manual */ /*! - \externalpage http://doc.qt.io/GammaRay - \title GammaRay + \externalpage https://doc.qt.io/QtQmlLive + \title QmlLive Manual */ /*! - \externalpage http://doc.qt.io/QtQmlLive - \title QmlLive + \externalpage https://doc.qt.io/qtcreator/creator-debugging-qml.html + \title Qt Creator: QML Debugger */ /*! - \externalpage http://doc.qt.io/qtcreator/creator-debugging-qml.html - \title QML Debugger + \externalpage https://doc.qt.io/qtcreator/creator-qml-performance-monitor.html + \title Qt Creator: QML Profiler */ /*! - \externalpage http://doc.qt.io/qtcreator/creator-qml-performance-monitor.html - \title QML Profiler + \externalpage https://doc.qt.io/qtcreator/creator-live-preview-desktop.html + \title Qt Creator: QML Preview On Desktop */ /*! - \externalpage http://doc.qt.io/qtcreator/index.html - \title Qt Creator Manual + \externalpage https://fontawesome.com/ + \title Font Awesome */ /*! - \externalpage https://doc.qt.io/qtcreator/creator-project-creating.html#creating-resource-files - \title Creating Resource Files + \externalpage https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing_operator + \title Nullish Coalescing */ /*! - \externalpage https://fontawesome.com/ - \title Font Awesome + \externalpage https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining + \title Optional Chaining +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/command/install.html#files + \title install(FILES) +*/ +/*! + \externalpage https://developer.android.com/reference/android/view/View + \title Android: View +*/ +/*! + \externalpage https://developer.android.com/reference/java/security/InvalidParameterException + \title Android: InvalidParameterException +*/ +/*! + \externalpage https://developer.android.com/reference/java/lang/ClassCastException + \title Android: ClassCastException */ +/*! + \externalpage https://developer.android.com/topic/libraries/view-binding + \title Android: View binding +*/ +/*! + \externalpage https://developer.android.com/reference/android/Manifest.permission#SYSTEM_ALERT_WINDOW + \title Android: SYSTEM_ALERT_WINDOW +*/ + diff --git a/src/qml/doc/src/includes/cmake-find-package-qml.qdocinc b/src/qml/doc/src/includes/cmake-find-package-qml.qdocinc new file mode 100644 index 0000000000..f92b87592e --- /dev/null +++ b/src/qml/doc/src/includes/cmake-find-package-qml.qdocinc @@ -0,0 +1,6 @@ +The command is defined in the \c Qml component of the \c Qt6 package, which +can be loaded like so: + +\badcode +find_package(Qt6 REQUIRED COMPONENTS Qml) +\endcode diff --git a/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.qdocinc b/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.qdocinc new file mode 100644 index 0000000000..0125a1c4c2 --- /dev/null +++ b/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.qdocinc @@ -0,0 +1,9 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [warning] +\warning If you are using a CMake version lower than 3.19, make sure that you +pass the \c MANUAL_FINALIZATION option to +\l{qt_add_executable}{qt6_add_executable()}, and then call +\l{qt_finalize_target}{qt6_finalize_target()} before calling this function. +//! [warning] diff --git a/src/qml/doc/src/includes/qqmlcomponent.qdoc b/src/qml/doc/src/includes/qqmlcomponent.qdoc index 6949d8823a..fcc6fdc802 100644 --- a/src/qml/doc/src/includes/qqmlcomponent.qdoc +++ b/src/qml/doc/src/includes/qqmlcomponent.qdoc @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE: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$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only //! [url-note] Ensure that the URL provided is full and correct, in particular, use diff --git a/src/qml/doc/src/includes/qualified-class-name.qdocinc b/src/qml/doc/src/includes/qualified-class-name.qdocinc new file mode 100644 index 0000000000..fce8b45cc0 --- /dev/null +++ b/src/qml/doc/src/includes/qualified-class-name.qdocinc @@ -0,0 +1,7 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [class name must be qualified] +\note The class name needs to be fully qualified, even if you're already + inside the namespace. +//! [class name must be qualified] diff --git a/src/qml/doc/src/javascript/date.qdoc b/src/qml/doc/src/javascript/date.qdoc index 431f9649a0..26ce1d5d29 100644 --- a/src/qml/doc/src/javascript/date.qdoc +++ b/src/qml/doc/src/javascript/date.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype Date @@ -31,98 +7,48 @@ \brief Provides date functions. The QML Date object extends the - \l{Mozilla Developer Network Date Reference}{JS Date object} with + \l{ECMAScript Specification of Date}{JS Date object} with locale aware functions. - Functions that accept a locale format may be either an enumeration - value: - \table - \row \li Locale.LongFormat \li The long version of the string; for example, returning "January" as a month name. - \row \li Locale.ShortFormat \li The short version of the string; for example, returning "Jan" as a month name. - \row \li Locale.NarrowFormat \li A special version for use when space is limited; - for example, returning "J" as a month name. Note that the narrow format might contain - the same text for different months and days or it can even be an empty string if the - locale doesn't support narrow names, so you should avoid using it for date formatting. - Also, for the system locale this format is the same as ShortFormat. - \endtable + Functions that accept a \c format argument take either Locale.LongFormat, + Locale.ShortFormat, Locale.NarrowFormat enumeration values, + or a string specifying the format. - or a string specifying the format These expressions may be used for format dates: - \table - \header \li Expression \li Output - \row \li d \li the day as number without a leading zero (1 to 31) - \row \li dd \li the day as number with a leading zero (01 to 31) - \row \li ddd - \li the abbreviated localized day name (e.g. 'Mon' to 'Sun'). - \row \li dddd - \li the long localized day name (e.g. 'Monday' to 'Sunday'). - \row \li M \li the month as number without a leading zero (1 to 12) - \row \li MM \li the month as number with a leading zero (01 to 12) - \row \li MMM - \li the abbreviated localized month name (e.g. 'Jan' to 'Dec'). - \row \li MMMM - \li the long localized month name (e.g. 'January' to 'December'). - \row \li yy \li the year as two digit number (00 to 99) - \row \li yyyy \li the year as four digit number. If the year is negative, - a minus sign is prepended in addition. - \endtable + The form of the supported format strings is as described in the + documentation of \l QDate::toString(), \l QTime::toString() and \l + QDateTime::toString(). - All other input characters will be ignored. Any sequence of characters that - are enclosed in singlequotes will be treated as text and not be used as an - expression. Two consecutive singlequotes ("''") are replaced by a singlequote - in the output. + If the date is invalid, an empty string is returned. - Example format strings (assuming that the Date is the 20 July - 1969): - - \table - \header \li Format \li Result - \row \li dd.MM.yyyy \li 20.07.1969 - \row \li ddd MMMM d yy \li Sun July 20 69 - \row \li 'The day is' dddd \li The day is Sunday - \endtable + \section1 Format Enumeration Values - These expressions may be used for formatting time: + Use the enumeration values when you want a format that matches the locale + preferences. \table - \header \li Expression \li Output - \row \li h - \li the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display) - \row \li hh - \li the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display) - \row \li H - \li the hour without a leading zero (0 to 23, even with AM/PM display) - \row \li HH - \li the hour with a leading zero (00 to 23, even with AM/PM display) - \row \li m \li the minute without a leading zero (0 to 59) - \row \li mm \li the minute with a leading zero (00 to 59) - \row \li s \li the second without a leading zero (0 to 59) - \row \li ss \li the second with a leading zero (00 to 59) - \row \li z \li the milliseconds without leading zeroes (0 to 999) - \row \li zzz \li the milliseconds with leading zeroes (000 to 999) - \row \li AP or A - \li use AM/PM display. \e AP will be replaced by either "AM" or "PM". - \row \li ap or a - \li use am/pm display. \e ap will be replaced by either "am" or "pm". - \row \li t \li the timezone (for example "CEST") + \row \li Locale.LongFormat \li Longer format + \row \li Locale.ShortFormat \li Shorter format + \row \li Locale.NarrowFormat \li In this context same as Locale.ShortFormat \endtable - All other input characters will be ignored. Any sequence of characters that - are enclosed in singlequotes will be treated as text and not be used as an - expression. Two consecutive singlequotes ("''") are replaced by a singlequote - in the output. + The format that the enumerations represent will depend on your locale, but also + the method that the enumeration is used for. - Example format strings (assuming that the QTime is 14:13:09.042) + For example, for the \c en_US locale, these format strings are used: \table - \header \li Format \li Result - \row \li hh:mm:ss.zzz \li 14:13:09.042 - \row \li h:m:s ap \li 2:13:9 pm - \row \li H:m:s a \li 14:13:9 pm + \header \li Function \li Locale Enum \li Format String + \row \li fromLocaleDateString, toLocaleDateString \li Locale.LongFormat \li \c{dddd, MMMM d, yyyy} + \row \li fromLocaleDateString, toLocaleDateString \li Locale.ShortFormat \li \c{M/d/yy} + \row \li fromLocaleTimeString, toLocaleTimeString \li Locale.LongFormat \li \c{h:mm:ss AP t} + \row \li fromLocaleTimeString, toLocaleTimeString \li Locale.ShortFormat \li \c{h:mm AP} + \row \li fromLocaleString, toLocaleString \li Locale.LongFormat \li \c{dddd, MMMM d, yyyy h:mm:ss AP t} + \row \li fromLocaleString, toLocaleString \li Locale.ShortFormat \li \c{M/d/yy h:mm AP} \endtable - If the date is invalid, an empty string will be returned. + \section1 Further Notes - Note: Using the locale-aware functions to perform date or time formatting can + Using the locale-aware functions to perform date or time formatting can result in incorrectly formatted times, due to an inconsistency in specification between Qt and JS. ECMA-262 specifies that historical dates should be intrepreted by projecting the current rules for daylight-saving onto past years, while Qt uses @@ -132,7 +58,7 @@ hour, if DST is currently in effect, while it was not for the time specified, or vice versa. - Note: There are different date formats with different understandings of negative years. Common + There are different date formats with different understandings of negative years. Common human language does not have a year 0. The year after 1BC is 1AD. This understanding is reflected when printing or parsing dates in one of the formats not standardized by ECMAScript. That is: toString(), toLocaleString(), toUTCString() and friends. ECMAScript does standardize diff --git a/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc index be4db4c917..f20111d154 100644 --- a/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc +++ b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-javascript-dynamicobjectcreation.html @@ -35,10 +11,6 @@ useful to delay instantiation of objects until necessary, thereby improving application startup time. It also allows visual objects to be dynamically created and added to the scene in reaction to user input or other events. -See the \l {QML Example - Dynamic Scene}{Dynamic Scene example} for a -demonstration of the concepts discussed on this page. - - \section1 Creating Objects Dynamically There are two ways to create objects dynamically from JavaScript. You can @@ -126,6 +98,12 @@ It is also possible to instantiate components without blocking via the \section2 Creating an Object from a String of QML +\warning Creating objects from a string of QML is extremely slow since the engine has to compile the +passed QML string every time you do it. Furthermore, it's very easy to produce invalid QML when +programmatically constructing QML code. It's much better to keep your QML components as separate +files and add properties and methods to customize their behavior than to produce new components by +string manipulation. + If the QML is not defined until runtime, you can create a QML object from a string of QML using the \l{QtQml::Qt::createQmlObject()}{Qt.createQmlObject()} function, as in the following example: diff --git a/src/qml/doc/src/javascript/expressions.qdoc b/src/qml/doc/src/javascript/expressions.qdoc index b83127389a..d4f0115033 100644 --- a/src/qml/doc/src/javascript/expressions.qdoc +++ b/src/qml/doc/src/javascript/expressions.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-javascript-expressions.html \title JavaScript Expressions in QML Documents @@ -147,7 +123,7 @@ Rectangle { TapHandler { id: inputHandler - onTapped: { + onTapped: { // arbitrary JavaScript expression console.log("Tapped!") } @@ -310,14 +286,14 @@ signal just before being destroyed. resources in Qt 5.0.0, so mark this section as internal for now. It should eventually become public API - There is another section about scarce resources in basictypes.qdoc. It should + There is another section about scarce resources in valuetypes.qdoc. It should be enabled at the same time. \section1 Scarce Resources in JavaScript -As described in the documentation for \l{QML Basic Types}, a \c var type +As described in the documentation for \l{QML Value Types}, a \c var type property may hold a \e{scarce resource} (image or pixmap). There are several important semantics of scarce resources which should be noted: @@ -339,7 +315,7 @@ For the following examples, imagine that we have defined the following class: and that we have registered it with the QML type-system as follows: -\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 0 +\snippet qml/integrating-javascript/scarceresources/scarceresources.pro 0 The AvatarExample class has a property which is a pixmap. When the property is accessed in JavaScript scope, a copy of the resource will be created and diff --git a/src/qml/doc/src/javascript/finetuning.qdoc b/src/qml/doc/src/javascript/finetuning.qdoc new file mode 100644 index 0000000000..0e8a913a2a --- /dev/null +++ b/src/qml/doc/src/javascript/finetuning.qdoc @@ -0,0 +1,107 @@ +// Copyright (C) 2019 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! + +\page qtqml-javascript-finetuning.html +\title Configuring the JavaScript Engine +\brief Describes the environment variables available, to control how Javascript is run. + +Running JavaScript code can be influenced by a few environment variables, particularly: + +\table + \header + \li Environment Variable + \li Description + \row + \li \c{QV4_JIT_CALL_THRESHOLD} + \li The JavaScript engine contains a Just-In-Time compiler (JIT). The JIT will compile + frequently run JavaScript functions into machine code to run faster. This + environment variable determines how often a function needs to be run to be + considered for JIT compilation. The default value is 3 times. + \row + \li \c{QV4_FORCE_INTERPRETER} + \li Setting this environment variable runs all functions and expressions through the + interpreter. The JIT is never used, no matter how often a function or expression is + called. Functions and expressions may still be compiled ahead of time using + \l{qmlcachegen} or \l{qmlsc}, but only the generated byte code is used at run time. Any + generated C++ code and the machine code resulting from it is ignored. + \row + \li \c{QV4_JS_MAX_STACK_SIZE} + \li The JavaScript engine reserves a special memory area as a stack to run JavaScript. + This stack is separate from the C++ stack. Usually this area is 4MB in size. If this + environment variable contains a number, the JavaScript engine interprets it as the + size of the memory area, in bytes, to be allocated as the JavaScript stack. + \row + \li \c{QV4_GC_MAX_STACK_SIZE} + \li In addition to the regular JavaScript stack, the JavaScript engine keeps another stack + for the garbage collector, usually 2MB of memory. If the garbage collector needs to + handle an excessive number of objects at the same time, this stack might overrun. + If it contains a number, this environment variable is interpreted as the size in bytes + of the memory area that will be allocated as the stack for the garbage collector. + \row + \li \c{QV4_CRASH_ON_STACKOVERFLOW} + \li Usually the JavaScript engine tries to catch C++ stack overflows caused by + excessively recursive JavaScript code, and generates a non-fatal error condition. + There are separate recursion checks for compiling JavaScript and running JavaScript. A + stack overflow when compiling JavaScript indicates that the code contains deeply nested + objects and functions. A stack overflow at run-time indicates that the code results in + a deeply recursive program. The check for this is only indirectly related to the + JavaScript stack size mentioned above, as each JavaScript function call consumes stack + space on both, the C++ and the JavaScript stack. The code that checks for excessive + recursion is necessarily conservative, as the available stack size depends on many + factors and can often be customized by the user. With this environment variable set, the + JavaScript engine does not check for stack overflows when compiling or running + JavaScript and will not generate exceptions for them. Instead, when the stack overflows + the program attempts an invalid memory access. This most likely terminates the + program. In turn, the program gets to use up all the stack space the operating system + can provide. + \warning malicious code may be able to evade the termination and access unexpected + memory locations this way. + \row + \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 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 + allocation. This is very expensive at run-time, but it quickly uncovers many memory + management errors, for example the manual deletion of an object belonging to the QML + engine from C++. + \row + \li \c{QV4_PROFILE_WRITE_PERF_MAP} + \li On Linux, the \c perf utility can be used to profile programs. To analyze JIT-compiled + JavaScript functions, it needs to know about their names and locations in memory. To + provide this information, there's a convention to create a special file called + \c{perf-<pid>.map} in \e{/tmp} which perf then reads. This environment variable, if + set, causes the JIT to generate this file. + \row + \li \c{QV4_SHOW_BYTECODE} + \li Outputs the IR bytecode generated by Qt to the console. + Has to be combined with \c{QML_DISABLE_DISK_CACHE} or already cached bytecode will not + be shown. + \row + \li \c{QV4_DUMP_BASIC_BLOCKS} + \li Outputs the basic blocks of each function compiled ahead of time. The details of the + blocks are printed to the console. Additionally, control flow graphs with the byte code + for each block are generated in the DOT format for each compiled function. The value of + \c {QV4_DUMP_BASIC_BLOCKS} is used as the path to the folder where the DOT files should + be generated. If the path is any of ["-", "1", "true"] or if files can't be opened, + the graphs are dumped to stdout instead. + \row + \li \c{QV4_VALIDATE_BASIC_BLOCKS} + \li Performs checks on the basic blocks of a function compiled ahead of time to validate + its structure and coherence. If the validation fails, an error message is printed to + the console. +\endtable + +\l{The QML Disk Cache} accepts further environment variables that allow fine tuning its behavior. +In particular \c{QML_DISABLE_DISK_CACHE} may be useful for debugging. + +*/ + diff --git a/src/qml/doc/src/javascript/functionlist.qdoc b/src/qml/doc/src/javascript/functionlist.qdoc index 7a6a922480..d656bc2234 100644 --- a/src/qml/doc/src/javascript/functionlist.qdoc +++ b/src/qml/doc/src/javascript/functionlist.qdoc @@ -1,37 +1,13 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-javascript-functionlist.html \title List of JavaScript Objects and Functions \brief A list of objects, functions, and properties supported in QML. This reference contains a list of objects, functions and - properties supported by the \l{QQmlEngine}{QML engine}. For a detailed - description, see the \l{ECMA-262} specification. + properties supported by the \l{QJSEngine}{JavaScript engine} in Qt. + For a detailed description, see the \l{ECMA-262} specification. \section1 The Global Object @@ -233,9 +209,9 @@ \li [Symbol.iterator]() \endlist - Additionally, the QML engine adds the following functions to the \l String prototype: + Additionally, the QML engine adds the following functions to the \c String prototype: \list - \li \l {String::arg}{arg()} + \li \l {string}{string::arg()} \endlist diff --git a/src/qml/doc/src/javascript/hostenvironment.qdoc b/src/qml/doc/src/javascript/hostenvironment.qdoc index c22c392b80..a27fe48fbe 100644 --- a/src/qml/doc/src/javascript/hostenvironment.qdoc +++ b/src/qml/doc/src/javascript/hostenvironment.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-javascript-hostenvironment.html \title JavaScript Host Environment @@ -42,6 +18,9 @@ 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} (\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 JavaScript reference and tutorial sites, such as the \l{W3Schools JavaScript Reference} (JavaScript Objects @@ -51,6 +30,47 @@ specific to the browser environment. In the case of the W3Schools link above, th Reference} section generally covers the standard, while the \c{Browser Objects Reference} and \c{HTML DOM Objects Reference} sections are browser specific (and thus not applicable to QML). +\section1 Type annotations and assertions + +Function declarations in QML documents can, and should, contain type +annotations. Type annotations are appended to the declaration of arguments and +to the function itself, for annotating the return type. The following function +takes an \c int and a \c string parameter, and returns a \c QtObject: + +\qml +function doThings(a: int, b: string) : QtObject { ... } +\endqml + +Type annotations help tools like \l{Qt Creator} and \l{qmllint Reference}{qmllint} to make sense +of the code and provide better diagnostics. Moreover, they make functions easier +to use from C++. See +\l {qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++} +for more information. + +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 { + property color parentColor: (parent as Rectangle)?.color || "red" +} +\endqml + +The optional chaining (\c{?.}) avoids throwing an exception if the parent is +actually not a rectangle. In that case "red" is chosen as \c parentColor. + +Since Qt 6.7 type annotations are always enforced when calling functions. Values +are coerced to the required types as necessary. Previously, type annotations were +ignored by the interpreter and the JIT compiler, but enforced by \l{qmlcachegen} +and \l{qmlsc} when compiling to C++. This could lead to differences in behavior in +some corner cases. In order to explicitly request the old behavior of the +interpreter and JIT you can add the following to your QML document: + +\qml +pragma FunctionSignatureBehavior: Ignored +\endqml \section1 QML Global Object @@ -69,7 +89,7 @@ QML engine can be found in the \l{List of JavaScript Objects and Functions}. Note that QML makes the following modifications to native objects: \list -\li An \l {String::arg}{arg()} function is added to the \l String prototype. +\li An \l {string}{arg()} function is added to the \c String prototype. \li Locale-aware conversion functions are added to the \l Date and \l Number prototypes. \endlist diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc index 7da2cd22fe..ef5376cb54 100644 --- a/src/qml/doc/src/javascript/imports.qdoc +++ b/src/qml/doc/src/javascript/imports.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-javascript-imports.html \title Importing JavaScript Resources in QML @@ -64,7 +40,7 @@ objects such as \c Date and \c Math). The functions defined in an imported JavaScript file are available to objects defined in the importing QML document, via the \c{"Qualifier.functionName(params)"} syntax. Functions in JavaScript resources -may take parameters whose type can be any of the supported QML basic types or +may take parameters whose types can be any QML value types or object types, as well as normal JavaScript types. The normal \l{qtqml-cppintegration-data.html}{data type conversion rules} will apply to parameters and return values when calling such functions from QML. @@ -95,13 +71,49 @@ 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 "factorial.js" as MathFunctions +.import "filename.js" as Qualifier \endcode +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 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 +qualifier (that is, as \tt{Qualifier.functionName(params)}). + +Sometimes it is desirable to have the functions made available in the importing +context without needing to qualify them. In this case ECMAScript modules and the +JavaScript \c import statement should be used without the \c as qualifier. + +For example, the QML code below left calls \c showCalculations() in \c script.mjs, +which in turn can call \c factorial() in \c factorial.mjs, as it has included +\c factorial.mjs using \c import. + +\table +\row +\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0 +\li \snippet qml/integrating-javascript/includejs/script.mjs 0 +\row +\li \snippet qml/integrating-javascript/includejs/factorial.mjs 0 +\endtable + +The \l{QtQml::Qt::include()} {Qt.include()} function includes one JavaScript +file from another without using ECMAScript modules and without qualifying the +import. It makes all functions and variables from the other file available in +the current file's namespace, but ignores all pragmas and imports defined in +that file. This is not a good idea as a function call should never modify the +caller's context. + +\l{QtQml::Qt::include()} {Qt.include()} is deprecated and should be avoided. It +will be removed in a future version of Qt. + \section2 Importing a QML Module from a JavaScript Resource A JavaScript resource may import a QML module in the following fashion: @@ -109,42 +121,25 @@ A JavaScript resource may import a QML module in the following fashion: .import TypeNamespace MajorVersion.MinorVersion as Qualifier \endcode -For example: +Below you can see an example that also shows how to use the QML types from a +module imported in javascript: + \code .import Qt.test 1.0 as JsQtTest + +var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3 \endcode In particular, this may be useful in order to access functionality provided -via a singleton type; see qmlRegisterSingletonType() for more information. - -\note The .import syntax doesn't work for scripts used in the \l {WorkerScript} - -\section1 Including a JavaScript Resource from Another JavaScript Resource - -When a JavaScript file is imported, it must be imported with a qualifier. The -functions in that file are then accessible from the importing script via the -qualifier (that is, as \tt{Qualifier.functionName(params)}). Sometimes it is -desirable to have the functions made available in the importing context without -needing to qualify them, and in this circumstance the \l{QtQml::Qt::include()} -{Qt.include()} function may be used to include one JavaScript file from another. -This copies all functions from the other file into the current file's -namespace, but ignores all pragmas and imports defined in that file. +via a singleton type; see QML_SINGLETON for more information. -For example, the QML code below left calls \c showCalculations() in \c script.js, -which in turn can call \c factorial() in \c factorial.js, as it has included -\c factorial.js using \l {QtQml::Qt::include()}{Qt.include()}. - -\table -\row -\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0 -\li \snippet qml/integrating-javascript/includejs/script.js 0 -\row -\li \snippet qml/integrating-javascript/includejs/factorial.js 0 -\endtable +Your JavaScript resource by default can access all imports of the component +that imports the resource. It does not have access to the componpents's imports +if it is declared as a stateless library (using \c{.pragma library}) or contains +an explicit \c{.import} statment. -Notice that calling \l {QtQml::Qt::include()}{Qt.include()} copies all functions -from \c factorial.js into the \c MyScript namespace, which means the QML -component can also access \c factorial() directly as \c MyScript.factorial(). +\note The .import syntax doesn't work for scripts used in \l {WorkerScript} +\sa {Defining JavaScript Resources in QML} */ diff --git a/src/qml/doc/src/javascript/memory.qdoc b/src/qml/doc/src/javascript/memory.qdoc new file mode 100644 index 0000000000..54f48f48df --- /dev/null +++ b/src/qml/doc/src/javascript/memory.qdoc @@ -0,0 +1,211 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! + +\page qtqml-javascript-memory.html +\title Memory Management in the JavaScript Engine +\brief Describes how the JavaScript Engine manages memory. + +\section1 Introduction + +This document describes the \e dynamic memory management of the JavaScript +Engine in QML. It is a rather technical, in depth description. You only need +to read this if you care about the exact characteristics of JavaScript memory +management in QML. In particular, it can be helpful if you're trying to +optimize your application for maximum performance. + +\note By compiling your QML code to C++ using the \l{Qt Quick Compiler} +you can avoid much of the JavaScript heap usage. The generated C++ code uses the +familiar C++ stack and heap for storing objects and values. The +\l{JavaScript Host Environment}, however, always uses some JavaScript-managed +memory, no matter if you use it or not. If you use features that cannot be +compiled to C++, the engine will fall back to interpretation or JIT compilation +and use JavaScript objects stored on the JavaScript heap, though. + +\section1 Basic Principles + +The JavaScript engine in QML has a dedicated memory manager that requests +address space in units of multiple pages from the operating system. Objects, +strings, and other managed values created in JavaScript are then placed in this +address space, using the JavaScript engine's own allocation scheme. The +JavaScript engine does not use the C library's malloc() and free(), nor the +default implementations of C++'s new and delete to allocate memory for +JavaScript objects. + +Requests for address space are generally done with mmap() on Unix-like systems +and with VirtualAlloc() on windows. There are several platform-specific +implementations of those primitives. Address space reserved this way is not +immediately committed to physical memory. Rather, the operating system notices +when a page of memory is actually accessed and only then commits it. Therefore, +the address space is practically free and having a lot of it gives the +JavaScript memory manager the leverage it needs to place objects in an efficient +way on the JavaScript heap. Furthermore, there are platform-specific techniques +to tell the operating system that a chunk of address space, though still +reserved, does not have to be mapped into physical memory for the time being. +The operating system can then decommit the memory as needed and use it for other +tasks. Crucially, most operating systems do not guarantee immediate action on +such a decommit request. They will only decommit the memory when it is actually +needed for something else. On Unix-like systems we generally use madvise() for +this. Windows has specific flags to VirtualFree() to do the equivalent. + +\note There are memory profiling tools that do not understand this mechanism and +over-report JavaScript memory usage. + +All values stored on the JavaScript heap are subject to garbage collection. +None of the values are immediately "deleted" when they go out of scope or are +otherwise "dropped". Only the garbage collector may remove values from the +JavaScript heap and return memory (see \l{Garbage Collection} below for how +this works). + +\section1 QObject-based Types + +QObject-based types, and in particular everything you can phrase as a QML +element, are allocated on the C++ heap. Only a small wrapper around the pointer +is placed on the JavaScript heap when a QObject is accessed from JavaScript. +Such a wrapper, however, can own the QObject it points to. See +\l{QJSEngine::ObjectOwnership}. If the wrapper owns the object, it will be +deleted when the wrapper is garbage-collected. You can then also manually +trigger the deletion by calling the destroy() method on it. destroy() internally +calls \l{QObject::deleteLater()}. It will therefore not immediately delete the +object, but wait for the next event loop iteration. + +QML-declared \e properties of objects are stored on the JavaScript heap. They +live as long as the object they belong to lives. Afterwards they are removed the +next time the garbage collector runs. + +\section1 Object Allocation + +In JavaScript, any structured type is an object. This includes function objects, +arrays, regular expressions, date objects and much more. QML has a number of +internal object types, such as the above mentioned QObject wrapper. Whenever +an object is created, the memory manager locates some storage for it on the +JavaScript heap. + +JavaScript strings are also managed values, but their string data is not +allocated on the JavaScript heap. Similar to QObject wrappers, the heap objects +for strings are just thin wrappers around a pointer to string data. + +When allocating memory for an object, the size of the object is first rounded up +to 32 byte alignment. Each 32 byte piece of address space is called a "slot". +For objects smaller than a "huge size" threshold, the memory manager performs +a series of attempts to place the object in memory: +\list +\li The memory manager keeps linked lists of previously freed pieces of heap, + called "bins". Each bin holds pieces of heap with a fixed per-bin size in + slots. If the bin for the right size is not empty, it picks the first entry + and places the object there. +\li The memory that hasn't been used yet is managed via a bumper allocator. A + bumper pointer points to the byte beyond the occupied address space. If + there is still enough unused address space, the bumper is increased + accordingly, and the object is placed in unused space. +\li A separate bin is kept for previously freed pieces of heap of varying sizes + larger than the specific sizes mentioned above. The memory manager + traverses this list and tries to find a piece it can split to accommodate + the new object. +\li The memory manager searches the lists of specifically sized bins + larger than the object to be allocated and tries to split one of those. +\li Finally, if none of the above works, the memory manager reserves more + address space and allocates the object using the bumper allocator. +\endlist + +Huge objects are handled by their own allocator. For each of those one or more +separate memory pages are obtained from the OS and managed separately. + +Additionally, each new chunk of address space the memory manager obtains from +the OS gets a header that holds a number of flags for each slot: +\list +\li \e{object}: The first slot occupied by an object is flagged with this bit. +\li \e{extends}: Any further slots occupied by an object are flagged with this + bit. +\li \e{mark}: When the garbage collector runs, it sets this bit if the object is + still in use. +\endlist + +\section1 Internal Classes + +In order to minimize the required storage for metadata on what members +an object holds, the JavaScript engine assigns an "internal class" to each +object. Other JavaScript engines call this "hidden class" or "shape". +Internal classes are deduplicated and kept in a tree. If a property is +added to an object, the children of the current internal class are checked to +see if the same object layout has occurred before. If so, we can use the +resulting internal class right away. Otherwise we have to create a new one. + +Internal classes are stored in their own section of the JavaScript heap that +otherwise works the same way as the general object allocation described above. +This is because internal classes have to be kept alive while the objects using +them are collected. Internal classes are then collected in a separate pass. + +The actual property attributes stored in internal classes are \e not kept on +the JavaScript heap, though, but rather managed using new and delete. + +\section1 Garbage Collection + +The garbage collector used in the JavaScript engine is a non-moving, +stop-the-world Mark and Sweep design. In the \e mark phase we traverse all the +known places where live references to objects can be found. In particular: + +\list +\li JavaScript globals +\li Undeletable parts of QML and JavaScript compilation units +\li The JavaScript stack +\li The persistent value storage. This is where QJSValue and similar classes + keep references to JavaScript objects. +\endlist + +For any object found in those places the mark bits are set recursively for +anything it references. + +In the \e sweep phase the garbage collector then traverses the whole heap and +frees any objects not marked before. The resulting released memory is sorted +into the bins to be used for further allocations. If a chunk of address space +is completely empty, it is decommitted, but the address space is retained +(see \l{Basic Principles} above). If the memory usage grows again, the same +address space is re-used. + +The garbage collector is triggered either manually by calling the \l [QML] {Qt::}{gc()} function +or by a heuristic that takes the following aspects into account: + +\list +\li The amount of memory managed by object on the JavaScript heap, but not + directly allocated on the JavaScript heap, such as strings and internal + class member data. A dynamic threshold is maintained for those. If it is + surpassed, the garbage collector runs and the threshold is increased. If + the amount of managed external memory falls far below the threshold, the + threshold is decreased. +\li The total address space reserved. The internal memory allocation on the + JavaScript heap is only considered after at least some address space has + been reserved. +\li The additional address space reservation since the last garbage collector + run. If the amount of address space is more than double the amount of + used memory after the last garbage collector run, we run the garbage + collector again. +\endlist + +\section1 Analyzing Memory Usage + +In order to observe the development of both the address space and the number +of objects allocated in it, it is best to use a specialized tool. The +\l{Qt Creator: QML Profiler}{QML Profiler} provides a visualization that +helps here. More generic tools cannot see what the JavaScript memory manager +does within the address space it reserves and may not even notice that part +of the address space is not committed to physical memory. + +Another way to debug memory usage are the +\l{QLoggingCategory}{logging categories} \e{qt.qml.gc.statistics} and +\e{qt.qml.gc.allocatorStats}. If you enable the \e{Debug} level for +qt.qml.gc.statistics, the garbage collector will print some information every +time it runs: + +\list +\li How much total address space is reserved +\li How much memory was in use before and after the garbage collection +\li How many objects of various sizes were allocated so far +\endlist + +The \e{Debug} level for qt.qml.gc.allocatorStats prints more detailed +statistics that also include how the garbage collector was triggered, timings +for the mark and sweep phases and a detailed breakdown of memory usage by bytes +and chunks of address space. + +*/ diff --git a/src/qml/doc/src/javascript/number.qdoc b/src/qml/doc/src/javascript/number.qdoc index 288232255c..a37fd8051b 100644 --- a/src/qml/doc/src/javascript/number.qdoc +++ b/src/qml/doc/src/javascript/number.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype Number @@ -58,21 +34,32 @@ If \a locale is not specified, the default locale will be used. The following example shows a number formatted for the German locale: - \code + \qml import QtQuick 2.0 Text { text: "The value is: " + Number(4742378.423).toLocaleString(Qt.locale("de_DE")) } - \endcode + \endqml + + You can customize individual fields of the \a{locale} to tightly control + the output: + \qml + let locale = Qt.locale("de_DE"); + let a = Number(1000).toLocaleString(locale)); // a == 1.000,00 + locale.numberOptions = Locale.OmitGroupSeparator; + let b = Number(1000).toLocaleString(locale)); // b == 1000,00 + \endqml You can apply toLocaleString() directly to constants, provided the decimal is included in the constant, e.g. - \code + \qml 123.0.toLocaleString(Qt.locale("de_DE")) // OK 123..toLocaleString(Qt.locale("de_DE")) // OK 123.toLocaleString(Qt.locale("de_DE")) // fails - \endcode + \endqml + + \sa {QtQml::Locale}{Locale} */ /*! @@ -93,12 +80,14 @@ If \a locale is not supplied the default locale will be used. For example, using the German locale: - \code + \qml var german = Qt.locale("de_DE"); var d; d = Number.fromLocaleString(german, "1234,56") // d == 1234.56 d = Number.fromLocaleString(german, "1.234,56") // d == 1234.56 d = Number.fromLocaleString(german, "1234.56") // throws exception d = Number.fromLocaleString(german, "1.234") // d == 1234.0 - \endcode + \endqml + + \sa {QtQml::Locale}{Locale} */ diff --git a/src/qml/doc/src/javascript/qmlglobalobject.qdoc b/src/qml/doc/src/javascript/qmlglobalobject.qdoc index bba796f9ea..1bd03fad54 100644 --- a/src/qml/doc/src/javascript/qmlglobalobject.qdoc +++ b/src/qml/doc/src/javascript/qmlglobalobject.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-javascript-qmlglobalobject.html \title QML Global Object @@ -31,100 +7,27 @@ The QML JavaScript host environment implements the following host objects and functions. -These are built in and can be used from any JavaScript code loaded in QML, without +They are built-in, so you can use them from any JavaScript code loaded in QML, without additional imports: \list -\li The \l{QmlGlobalQtObject}{Qt object}: This object is specific to QML, and provides helper methods +\li The \l{QmlGlobalQtObject}{Qt object}: A QML object that offers helper methods and properties specific to the QML environment. -\li qsTr(), qsTranslate(), qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions: - These functions are specific to QML, and provide \l{Overview of the Translation Process}{translation capabilities} to the QML environment. -\li gc() function: This function is specific to QML, and provides a way to manually trigger garbage collection. -\li print() function: This function is specific to QML, and provides a simple way to output information to the console. -\li The \l{Console API}{console object}: This object implements a subset of the \l{http://getfirebug.com/wiki/index.php/Console_API}{FireBug Console API}. -\li \l{XMLHttpRequest}, DOMException: These objects implement a subset of the \l{http://www.w3.org/TR/XMLHttpRequest/}{W3C XMLHttpRequest specification}. -\endlist - -\note The \l {QJSEngine::}{globalObject()} function cannot be used to modify -the global object of a \l QQmlEngine. For more information about this, see +\li \l {Qt::}{qsTr()}, \l {Qt::}{qsTranslate()}, \l {Qt::}{qsTrId()}, \l {Qt::}{QT_TR_NOOP()()}, + \l {Qt::}{QT_TRANSLATE_NOOP()}, \l {Qt::}{QT_TRID_NOOP()} functions: + QML functions that let you translate \l{Mark Strings for Translation} + {strings} and \l{Mark Translatable Data Text Strings}{string literals} in the + QML environment. +\li gc() function: A QML function that manually triggers garbage collection. +\li print() function: A QML function that prints output to the console. +\li The \l{Console API}{console object}: Implements a subset of the + \l{http://getfirebug.com/wiki/index.php/Console_API}{FireBug Console API}. +\li \l{XMLHttpRequest}, DOMException: Implements a subset of the + \l{http://www.w3.org/TR/XMLHttpRequest/}{W3C XMLHttpRequest specification}. +\endlist + +\note You cannot use the \l {QJSEngine::}{globalObject()} function to change +the global object of a \l QQmlEngine. For more information, see \l {JavaScript Environment Restrictions}. -\target XMLHttpRequest -\section1 XMLHttpRequest - -The XMLHttpRequest object, which can be used to asynchronously obtain -data from over a network. - -The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard} -as many popular web browsers with following exceptions: -\list -\li QML's XMLHttpRequest does not enforce the same origin policy. -\endlist - -Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset -of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web -browser. The following objects and properties are supported by the QML implementation: - -\table -\header -\li \b {Node} -\li \b {Document} -\li \b {Element} -\li \b {Attr} -\li \b {CharacterData} -\li \b {Text} - -\row -\li -\list -\li nodeName -\li nodeValue -\li nodeType -\li parentNode -\li childNodes -\li firstChild -\li lastChild -\li previousSibling -\li nextSibling -\li attributes -\endlist - -\li -\list -\li xmlVersion -\li xmlEncoding -\li xmlStandalone -\li documentElement -\endlist - -\li -\list -\li tagName -\endlist - -\li -\list -\li name -\li value -\li ownerElement -\endlist - -\li -\list -\li data -\li length -\endlist - -\li -\list -\li isElementContentWhitespace -\li wholeText -\endlist - -\endtable - -The \l{Qt Quick Examples - XMLHttpRequest}{XMLHttpRequest example} demonstrates -how to use the XMLHttpRequest object to make a request and read the response -headers. - */ diff --git a/src/qml/doc/src/javascript/qtjavascript.qdoc b/src/qml/doc/src/javascript/qtjavascript.qdoc index ad93d9d9ac..d226b4428e 100644 --- a/src/qml/doc/src/javascript/qtjavascript.qdoc +++ b/src/qml/doc/src/javascript/qtjavascript.qdoc @@ -1,36 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \group qtjavascript - \title Scripting Classes and Overviews - - \brief Classes for embedding JavaScript in Qt/C++ applications. -*/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtjavascript.html diff --git a/src/qml/doc/src/javascript/resources.qdoc b/src/qml/doc/src/javascript/resources.qdoc index 60f97c2007..d60101806a 100644 --- a/src/qml/doc/src/javascript/resources.qdoc +++ b/src/qml/doc/src/javascript/resources.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-javascript-resources.html \title Defining JavaScript Resources in QML diff --git a/src/qml/doc/src/javascript/string.qdoc b/src/qml/doc/src/javascript/string.qdoc deleted file mode 100644 index f896af3378..0000000000 --- a/src/qml/doc/src/javascript/string.qdoc +++ /dev/null @@ -1,50 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \qmltype String - \inqmlmodule QtQml - \brief The String object represents a string value. - - The QML String object extends the JS String object with - the arg() function. - - \sa {ECMA-262}{ECMAScript Language Specification} -*/ - -/*! - \qmlmethod string String::arg(value) - - Returns a copy of this string with the lowest numbered place marker replaced by value, - i.e., %1, %2, ..., %99. The following example prints "There are 20 items" - - \code - var message = "There are %1 items" - var count = 20 - console.log(message.arg(count)) - \endcode -*/ diff --git a/src/qml/doc/src/javascript/topic.qdoc b/src/qml/doc/src/javascript/topic.qdoc index 0c06e14b4c..2302f90fbe 100644 --- a/src/qml/doc/src/javascript/topic.qdoc +++ b/src/qml/doc/src/javascript/topic.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-javascript-topic.html \title Integrating QML and JavaScript @@ -48,6 +24,25 @@ See the documentation page titled \l{qtqml-javascript-expressions.html}{JavaScript Expressions in QML Documents} for more information about using JavaScript expressions in QML. +\section1 Dynamic QML Object Creation from JavaScript + +QML supports the dynamic creation of objects from within JavaScript. This is +useful to delay instantiation of objects until necessary, thereby improving +application startup time. It also allows visual objects to be dynamically +created and added to the scene in reaction to user input or other events. This +functionality can be used in two main ways. + +Object can be created dynamically from JavaScript in an imperative way using +\l{qtqml-javascript-dynamicobjectcreation.html}{dynamic creation of objects}. +This can be useful, for example, when QML is used as an application scripting +language. + +\note When creating user interfaces, the preferred way of creating objects +dynamically is to use declarative constructs as these integrate best with the +QML engine and tooling. Various types exist to enable this functionality such +as the \l{Loader}, \l{Instantiator}, \l{Repeater} types. + + \section1 JavaScript Resources Application logic defined in JavaScript functions may be separated into @@ -81,4 +76,15 @@ These limitations and extensions are documented in the description of the \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} provided by the QML engine. +There is also an in depth description of the +\l{qtqml-javascript-memory.html}{memory management} employed by the JavaScript +engine. + +\section1 Configuring the JavaScript engine + +For specific use cases you may want to override some of the parameters the +JavaScript engine uses for handling memory and compiling JavaScript. See +\l{qtqml-javascript-finetuning.html}{Configuring the JavaScript engine} for +more information on these parameters. + */ diff --git a/src/qml/doc/src/javascript/xmlhttprequest.qdoc b/src/qml/doc/src/javascript/xmlhttprequest.qdoc new file mode 100644 index 0000000000..b8624073c5 --- /dev/null +++ b/src/qml/doc/src/javascript/xmlhttprequest.qdoc @@ -0,0 +1,301 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype XMLHttpRequest + \inqmlmodule QtQml + \brief Object for sending requests to a server. + + The \c XMLHttpRequest object allows scripts to perform HTTP client functionality, + such as submitting form data or loading data asynchronously from a server. + + The \c XMLHttpRequest API is a partial implementation of the + \l {https://www.w3.org/TR/2014/WD-XMLHttpRequest-20140130/}{W3C XHR Level 1 standard} + with the following exception: + \list + \li It does not enforce the same origin policy. + \endlist + + \section1 Sending requests + + Use the following steps to send a request using the \c XMLHttpRequest API: + \list 1 + \li Create a \c XMLHttpRequest object. + \li Assign a callback function to the \l {XMLHttpRequest::onreadystatechange}{onreadystatechange} signal handler. + \li Call \l {XMLHttpRequest::open}{open()} with the appropriate HTTP method and URL to request. + \li Call \l {XMLHttpRequest::send}{send()} + \endlist + + The callback function handles the HTTP response for a request. + It's a good practice to check if the \l{XMLHttpRequest::readyState}{readyState} is \c DONE in the handler, + before you use one of the following methods to read the response: + \list + \li \l {XMLHttpRequest::response}{response} + \li \l {XMLHttpRequest::responseText}{responseText} + \li \l {XMLHttpRequest::responseXML}{responseXML} + \endlist + + The following example demonstrates how to send a request and read the response: + + \snippet qml/XHRForm.qml 0 + + The earlier snippet connects the button's clicked signal to an external \c sendRequest function. + A resource URL is passed as the first argument, and a callback function to handle UI updates is passed as the second. + The \c sendRequest function, which exists in an external \c request.js file, can be implemented like this: + + \snippet qml/xmlhttprequest.js 0 + + The earlier snippet follows the four simple steps mentioned at the beginning. + It instantiates the \c XMLHttpRequest object first, and assigns a callback function to handle the response. + It also calls \l {XMLHttpRequest::open}{open()} with an HTTP method and URL, before it sends the request to the server. + Notice that the second argument to \c sendRequest is called at the end of \l {XMLHttpRequest::onreadystatechange}{onreadystatechange}, + in order to handle UI updates based on the HTTP response. + + Set the \c QML_XHR_DUMP environment variable to \c 1 if you want to debug a request. + This will log the following information: + \list + \li Method type (GET or POST), URL, and body of sent requests. + \li URL and body of responses received. + \li Network error, if any. + \endlist + + \section1 Accessing local files + + By default, you cannot use the \c XMLHttpRequest object to read files from your local file system. + If you wish to use this feature to access local files, you can set the following environment variables to \c 1. + \list + \li QML_XHR_ALLOW_FILE_READ + \li QML_XHR_ALLOW_FILE_WRITE + \endlist + \warning Use this feature only if you know that the application runs trusted QML and JavaScript code. + + \section1 responseXML document + + The \c responseXML XML DOM tree currently supported by QML is a reduced subset of + the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web browser. + The following objects and properties are supported by the QML implementation: + + \table + \header + \li \b {Node} + \li \b {Document} + \li \b {Element} + \li \b {Attr} + \li \b {CharacterData} + \li \b {Text} + + \row + \li + \list + \li nodeName + \li nodeValue + \li nodeType + \li parentNode + \li childNodes + \li firstChild + \li lastChild + \li previousSibling + \li nextSibling + \li attributes + \endlist + + \li + \list + \li xmlVersion + \li xmlEncoding + \li xmlStandalone + \li documentElement + \endlist + + \li + \list + \li tagName + \endlist + + \li + \list + \li name + \li value + \li ownerElement + \endlist + + \li + \list + \li data + \li length + \endlist + + \li + \list + \li isElementContentWhitespace + \li wholeText + \endlist + + \endtable +*/ + +/*! + \qmlmethod void XMLHttpRequest::abort() + + Cancels the current request. + + It changes the \l {XMLHttpRequest::readyState}{readyState} property to be \c XMLHttpRequest.UNSENT and emits the \c readystatechange signal. +*/ + +/*! + \qmlmethod string XMLHttpRequest::getAllResponseHeaders() + + Returns a \c String of headers received from the last response. + + The following is an example response header: + \code + content-encoding: gzip + content-type: text/html; charset=UTF-8 + date: Mon, 06 Feb 2023 09:00:08 GMT + expires: Mon, 13 Feb 2023 09:00:08 GMT + last-modified: Thu, 17 Oct 2019 07:18:26 GMT + \endcode + + \sa {XMLHttpRequest::getResponseHeader}{getResponseHeader()} +*/ + +/*! + \qmlmethod string XMLHttpRequest::getResponseHeader(headerName) + + Returns either the \a headerName value from the last response, or an empty \c String, if the \a headerName is missing. + + \sa {XMLHttpRequest::getAllResponseHeaders}{getAllResponseHeaders()} +*/ + +/*! + \qmlmethod void XMLHttpRequest::open(method, url, async) + + Specify the HTTP \a method you want the request to use, as well as the \a url you wish to request. + You should make sure to always call this function before \l {XMLHttpRequest::send}{send()}. + An optional third parameter \a async can be used to decide whether the request should be asynchronous or not. + The default value is \c true. + + Emits the \c readystatechange signal, which calls the \l {XMLHttpRequest::onreadystatechange}{onreadystatechange} handler with + the \l {XMLHttpRequest::readyState}{readyState} property set to \c XMLHttpRequest.OPENED. +*/ + +/*! + \qmlmethod void XMLHttpRequest::send(data) + + Sends the request to the server. + You can use the optional argument \a data to add extra data to the body of the request. + This can be useful for POST requests, where you typically want the request to contain extra data. + + The \l {XMLHttpRequest::readyState}{readyState} property is updated once a response has been received from the server, + and while the response is being processed. It will first be set to \c HEADERS_RECEIVED, then to \c LOADING, + and finally \c DONE, once the response has been fully processed. + The \c readystatechange signal is emitted every time \l {XMLHttpRequest::readyState}{readyState} is updated. +*/ + +/*! + \qmlmethod void XMLHttpRequest::setRequestHeader(header, value) + + Adds a new header to the next request you wish to send. + This is a key-value pair, which has the name \a header and the corresponding \a value. +*/ + +/*! + \qmlmethod void XMLHttpRequest::overrideMimeType(mime) + \since 6.6 + + Forces the \c XMLHttpRequest to interpret the data received in the next HTTP response, + as if it had the MIME type \a mime, rather than the one provided by the server. +*/ + +/*! + \qmlproperty function XMLHttpRequest::onreadystatechange + + Choose a callback function you want to get invoked whenever the \l {XMLHttpRequest::readyState}{readyState} of the \c XMLHttpRequest object changes. + + \sa {XMLHttpRequest::readyState}{readyState} +*/ + +/*! + \qmlproperty enumeration XMLHttpRequest::readyState + \readonly + + Indicates the current state of the \c XMLHttpRequest object. + + The value can be one of the following: + \value XMLHttpRequest.UNSENT The request is not initialized, which is the state before calling \l {XMLHttpRequest::open}{open()}. + \value XMLHttpRequest.OPENED The request is initialized, meaning \l {XMLHttpRequest::open}{open()} was previously called, but no further progress. + \value XMLHttpRequest.HEADERS_RECEIVED Received a reply from the sever, but the request is not fully processed yet. + \value XMLHttpRequest.LOADING Downloading data from the server. + \value XMLHttpRequest.DONE Finished processing the request. + + \sa {XMLHttpRequest::onreadystatechange}{onreadystatechange} +*/ + +/*! + \qmlproperty string XMLHttpRequest::responseURL + \readonly + \since 6.6 + + Returns the url that was used to retrieve the response data, after any redirects have occurred. +*/ + +/*! + \qmlproperty string XMLHttpRequest::responseText + \readonly + + Returns a \c String containing the data received from the last response. + + \sa {XMLHttpRequest::responseXML}{responseXML} +*/ + +/*! + \qmlproperty var XMLHttpRequest::responseXML + \readonly + + Returns either a \c Document, or \c null, if the response content cannot be parsed as XML or HTML. + See the \l {responseXML document}{responseXML document} section for more information. + + \sa {XMLHttpRequest::responseText}{responseText} +*/ + +/*! + \qmlproperty var XMLHttpRequest::response + \readonly + + Returns either a \c String, an \c ArrayBuffer, or a \c Document, + depending on the \l {XMLHttpRequest::responseType}{responseType} of the last request. + + \sa {XMLHttpRequest::responseType}{responseType}, {XMLHttpRequest::responseText}{responseText}, {XMLHttpRequest::responseXML}{responseXML} +*/ + +/*! + \qmlproperty string XMLHttpRequest::responseType + + Returns a \c String describing the content type of the last response received. + \list + \li If the response type is "text" or an empty \c String, the response content is a UTF-16 encoded \c String. + \li If the response type is "arraybuffer", it means that the response content is an \c ArrayBuffer containing binary data. + \li If the response type is "json", the response content should be a JSON \c Document. + \li If the response type is "document", it means that the response content is an XML \c Document, which can be safely read with the \l {XMLHttpRequest::responseXML}{responseXML} property. + \endlist + + \sa {XMLHttpRequest::response}{response} +*/ + +/*! + \qmlproperty int XMLHttpRequest::status + \readonly + + Returns the status code for the last response received. + + \sa {XMLHttpRequest::statusText}{statusText} +*/ + +/*! + \qmlproperty string XMLHttpRequest::statusText + \readonly + + Returns a \c String that has the status message associated with the status code for the last response received. + + \sa {XMLHttpRequest::status}{status} +*/ diff --git a/src/qml/doc/src/qmldiskcache.qdoc b/src/qml/doc/src/qmldiskcache.qdoc new file mode 100644 index 0000000000..90d9aee723 --- /dev/null +++ b/src/qml/doc/src/qmldiskcache.qdoc @@ -0,0 +1,120 @@ +// Copyright (C) 2019 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmldiskcache.html +\title The QML Disk Cache +\brief QML documents are generally pre-compiled or cached after compilation. + +You should define your QML modules using \l{qt_add_qml_module} that makes sure +that the \l{Qt Quick Compiler} processes your QML and JavaScript files ahead of +time. Also, it guarantees optimum performance at run time. The +\l{Qt Quick Compiler} generates byte code for +each function and binding. This byte code can be used by the QML interpreter, +and the Just-in-time (JIT) compiler in the QML engine. In addition, the +\l{Qt Quick Compiler} generates native code for suitable functions and +bindings. The native code can be executed directly, which results in better +performance than interpreting or just-in-time compiling the byte code. Both, +byte code and native code are then compiled into your binary. + +When using \l{qmake} you can specify \c{CONFIG += qtquickcompiler} to +give similar treatment to QML and JavaScript files added as resources to your +project. \l{Qt Creator} has a setting that allows passing +\c{CONFIG += qtquickcompiler} to the qmake command line. By default, it is +enabled for release and profile builds. \l{qmake} cannot pass as much +information to the \l{Qt Quick Compiler} as CMake. Therefore, the compilation +will contain less native code. + +You should make sure to load your QML documents from the resource file system +where possible. Otherwise the QML engine won't be able to find the code compiled +ahead of time. + +If no byte code or native code can be found for a QML document at run time, or +if the code is found but cannot be used, the QML engine compiles the document +into a byte code representation on the fly. The compiling process can be time +consuming, and the result will contain only byte code. Subsequent loads of the +same document will yield the same byte code. The QML engine can optimize this +step by caching the result of the compilation. It stores the byte code in a +cache file and later loads the cache file instead of re-compiling when the same +QML document is requested again. Usually, the cache files are stored in a +subdirectory \c{qmlcache} of the system's cache directory, as denoted by +QStandardPaths::CacheLocation. + +Checks are in place to make sure that any cache files and any code compiled +ahead of time are only loaded if all of the following conditions are met: +\list + \li The Qt version has not changed + \li The source code in the original file has not changed + \li The QML debugger is not running +\endlist + +Only the \c{QML_FORCE_DISK_CACHE} variable (see below) overrides only the +condition regarding the QML debugger. The other environment variables do not +influence these conditions. + +The primary way of fine tuning the behavior regarding ahead of time compiled +code and caching is via the environment variable \c{QML_DISK_CACHE}. This +variable takes a comma-separated list of options, for example: + +\badcode +QML_DISK_CACHE=aot,qmlc-read +\endcode + +The available options are as follows: + +\table + \header + \li Option + \li Description + \row + \li aot-native + \li Load the compilation units compiled ahead of time and allow + execution of any native code found in them. + \row + \li aot-bytecode + \li Load the compilation units compiled ahead of time and allow + interpretation and just-in-time compilation of byte code found + in them. + \row + \li aot + \li Shorthand for \c{aot-native,aot-bytecode}. + \row + \li qmlc-read + \li Load any cached compilation units for QML and JavaScript files from + the host file system and allow interpretation and just-in-time + compilation of byte code found in them. + \row + \li qmlc-write + \li When compiling a QML or JavaScript file on the fly, create a cache + file afterward. The cache file can be loaded when the same + document is requested again. + \row + \li qmlc + \li Shorthand for \c{qmlc-read,qmlc-write}. +\endtable + +Furthermore, you can use the following environment variables: + +\table + \header + \li Environment Variable + \li Description + \row + \li \c{QML_DISABLE_DISK_CACHE} + \li Disables the disk cache and forces re-compilation from source for + all QML and JavaScript files. \c{QML_DISABLE_DISK_CACHE} overrides + \c{QML_DISK_CACHE}. + \row + \li \c{QML_FORCE_DISK_CACHE} + \li Enables the disk cache even when debugging QML. You cannot use the + JavaScript debugger this way. It may fail to stop at breakpoints, + for example. You can still use the QML inspector to explore the + object hierarchy, though. \c{QML_FORCE_DISK_CACHE} overrides + \c{QML_DISABLE_DISK_CACHE} and \c{QML_DISK_CACHE}. + \row + \li \c{QML_DISK_CACHE_PATH} + \li Specifies a custom location where the cache files shall be stored + instead of using the default location. +\endtable + +*/ diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index 969dd51433..470d4598fc 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -1,29 +1,688 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \macro QML_ELEMENT + \relates QQmlEngine + + Declares the enclosing type or namespace to be available in QML, using its + class or namespace name as the QML element name. + + For example, this makes the C++ class \c Slider available as a QML type + named \c Slider. All its properties, invokable methods and enums are exposed. + + \code + class Slider : public QObject + { + Q_OBJECT + QML_ELEMENT + Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged FINAL) + // ... + public: + enum Slippiness { + Dry, Wet, Icy + }; + Q_ENUM(Slippiness) + + Q_INVOKABLE void slide(Slippiness slippiness); + + // ... + } + \endcode + + You can use the build system to register the type in the type namespace + \e {com.mycompany.qmlcomponents} with major version \c 1. + For qmake, specify the following in your project file: + + \badcode + CONFIG += qmltypes + QML_IMPORT_NAME = com.mycompany.qmlcomponents + 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: + + \qml + import com.mycompany.qmlcomponents 1.0 + + Slider { + value: 12 + Component.onCompleted: slide(Slider.Icy) + + // ... + } + \endqml + + You can also make namespaces tagged with Q_NAMESPACE available this way, in + order to expose any enums tagged with Q_ENUM_NS they contain: + + \code + namespace MyNamespace { + Q_NAMESPACE + QML_ELEMENT + + enum MyEnum { + Key1, + Key2, + }; + Q_ENUM_NS(MyEnum) + } + \endcode + + In QML, you can then use the enums: + + \qml + Component.onCompleted: console.log(MyNamespace.Key2) + \endqml + + \b{NOTE:} When classes have the same name but are located in different namespaces using + \l QML_ELEMENT on both of them will cause a conflict. + Make sure to use \l QML_NAMED_ELEMENT() for one of them instead. + + \include {qualified-class-name.qdocinc} {class name must be qualified} + + \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT(), + Q_REVISION(), QML_ADDED_IN_VERSION() +*/ + +/*! + \macro QML_NAMED_ELEMENT(name) + \relates QQmlEngine + + Declares the enclosing type or namespace to be available in QML, using \a name + as the element name. Otherwise behaves the same as QML_ELEMENT. + + \code + class SqlEventDatabase : public QObject + { + Q_OBJECT + QML_NAMED_ELEMENT(EventDatabase) + + // ... + }; + \endcode + + \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_ELEMENT +*/ + +/*! + \macro QML_ANONYMOUS + \relates QQmlEngine + + Declares the enclosing type to be available, but anonymous in QML. The type + cannot be created or used 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 +*/ + +/*! + \macro QML_INTERFACE + \relates QQmlEngine + + This macro registers the enclosing C++ type in the QML system as an interface. + + Types registered as an interface in QML should also declare themselves as an + interface with the \l {The Meta-Object System}{meta object system}. For + example: + + \code + struct FooInterface + { + QML_INTERFACE + public: + virtual ~FooInterface(); + virtual void doSomething() = 0; + }; + + Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface") + \endcode + + When registered with QML in this way, they can be used as property types: + + Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo) + + When you assign a \l QObject sub-class to this property, the QML engine does + the interface cast to \c FooInterface* automatically. + + Interface types are implicitly anonymous and uncreatable in QML. + + \b{NOTE:} When inheriting from types using QML_INTERFACE, use \l QML_IMPLEMENTS_INTERFACES + instead of \l Q_INTERFACES. + + \sa QML_IMPLEMENTS_INTERFACES(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_ANONYMOUS +*/ + +/*! + \macro QML_IMPLEMENTS_INTERFACES(interfaces) + \relates QQmlEngine + + This macro tells Qt which QML \a interfaces the class implements. + This macro should only be used for interfacing with classes using \l QML_INTERFACE, use \l Q_INTERFACES otherwise. + It's required in order for declarative registration via \l QML_ELEMENT to + function properly. + + \sa QML_INTERFACE, Q_INTERFACES +*/ + +/*! + \macro QML_UNCREATABLE(reason) + \relates QQmlEngine + + Declares that the enclosing type shall not be creatable from QML. This takes + effect if the type is available in QML, by having a \l QML_ELEMENT or + \l QML_NAMED_ELEMENT() macro. The \a reason will be emitted as error message if an + attempt to create the type from QML is detected. + + Some QML types are implicitly uncreatable, in particular types exposed with + \l QML_ANONYMOUS or namespaces exposed with \l QML_ELEMENT or + \l QML_NAMED_ELEMENT(). + + Since Qt 6.0 you can use "" instead of a reason to use a standard message + instead. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS +*/ + +/*! + \macro QML_SINGLETON + \relates QQmlEngine + + Declares the enclosing type to be a singleton in QML. This only takes effect + if the type is a \l Q_OBJECT and is available in QML (by having a + \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro). By default, each QQmlEngine + will try to create a singleton instance using either the type's default + constructor or a static factory function of the signature + \c{T *create(QQmlEngine *, QJSEngine *)} when the type is first accessed. + If both do exist and are accessible, the default constructor is preferred. + If there is no default constructor and no factory function the singleton is + inaccessible. The QML engine generally assumes ownership of the singleton and + will delete it when the engine itself is destroyed. You can prevent this by + calling QJSEngine::setObjectOwnership() on the singleton. + + In order to declare a default-constructible class as singleton, all you have + to do is add \l QML_SINGLETON: + + \code + class MySingleton : public QObject + { + Q_OBJECT + QML_ELEMENT + QML_SINGLETON + // Q_PROPERTY( ... ) + public: + // members, Q_INVOKABLE functions, etc. + }; + \endcode + + If the singleton class is not default-constructible, but you can modify it, + you can add a factory function to it, in order to make it accessible: + + \code + class MySingleton : public QObject + { + Q_OBJECT + QML_ELEMENT + QML_SINGLETON + // Q_PROPERTY( ... ) + + public: + static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine) + { + MySingleton *result = nullptr; + // Create the object using some custom constructor or factory. + // The QML engine will assume ownership and delete it, eventually. + return result; + } + + // members, Q_INVOKABLE functions, etc + }; + \endcode + + If you cannot modify the class and it does not have a default constructor or a + suitable factory function, you can provide a \l QML_FOREIGN wrapper to define + the factory function: + + \code + struct SingletonForeign + { + Q_GADGET + QML_FOREIGN(MySingleton) + QML_SINGLETON + QML_NAMED_ELEMENT(MySingleton) + public: + + static MySingleton *create(QQmlEngine *, QJSEngine *engine) + { + MySingleton *result = nullptr; + // Create the instance using some custom constructor or factory. + // The QML engine will assume ownership and delete it, eventually. + return result; + } + }; + \endcode + + Finally, if you want to provide one specific singleton object, the creation of + which you cannot control, you can return that from a factory function. This is + a replacement for the \l qmlRegisterSingletonInstance function. + If you were calling + + \code + qmlRegisterSingletonInstance("MyModule", 1, 0, "MySingleton", myObject); + \endcode + + with myObject being of type \c{MySingleton *}, you can do the following + instead: + + \code + struct SingletonForeign + { + Q_GADGET + QML_FOREIGN(MySingleton) + QML_SINGLETON + QML_NAMED_ELEMENT(MySingleton) + public: + + // Initialize this using myObject where you would previously + // call qmlRegisterSingletonInstance(). + inline static MySingleton *s_singletonInstance = nullptr; + + static MySingleton *create(QQmlEngine *, QJSEngine *engine) + { + // The instance has to exist before it is used. We cannot replace it. + Q_ASSERT(s_singletonInstance); + + // The engine has to have the same thread affinity as the singleton. + Q_ASSERT(engine->thread() == s_singletonInstance->thread()); + + // There can only be one engine accessing the singleton. + if (s_engine) + Q_ASSERT(engine == s_engine); + else + s_engine = engine; + + // Explicitly specify C++ ownership so that the engine doesn't delete + // the instance. + QJSEngine::setObjectOwnership(s_singletonInstance, + QJSEngine::CppOwnership); + return s_singletonInstance; + } + + private: + inline static QJSEngine *s_engine = nullptr; + }; + \endcode + + This way, the pre-existing class \c MySingleton is declared to be a QML + singleton, called \c MySingleton. You can specify an instance for it any time + before it is used by setting the \c s_singletonInstance member. None of this + requires modification of \c MySingleton itself. + + \note This pattern doesn't work if either the singleton is accessed by + multiple QML engines, or if the QML engine accessing it has a different thread + affinity than the singleton object itself. As shown above, you can check the + parameters to the \c create() method for identity and thread affinity of the + engine in order to assert on that. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), + qmlRegisterSingletonInstance(), QQmlEngine::singletonInstance(), {Singletons in QML} +*/ + +/*! + \macro QML_ADDED_IN_VERSION(MAJOR, MINOR) + \relates QQmlEngine + + Declares that the enclosing type or namespace was added in the specified + \a{MAJOR}.\a{MINOR} version. The version is assumed to be in line with any + revisions given by \l Q_REVISION() macros on methods, slots, or signals, + and any REVISION() attributes on properties declared with \l Q_PROPERTY(). + + \l QML_ADDED_IN_VERSION() only takes effect if the type or namespace is + available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), + \l QML_ANONYMOUS, or \l QML_INTERFACE macro. + + If the QML module the type belongs to is imported with a lower version than + the one determined this way, the QML type is invisible. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT +*/ + +/*! + \macro QML_ADDED_IN_MINOR_VERSION(VERSION) + \relates QQmlEngine + \deprecated [6.7] Use QML_ADDED_IN_VERSION and specify the full version + + Declares that the enclosing type or namespace was added in the specified minor + \a VERSION, relative to the module major version. The minor version is assumed + to be in line with any revisions given by \l Q_REVISION() macros on methods, + slots, or signals, and any REVISION() attributes on properties declared with + \l Q_PROPERTY(). + + \l QML_ADDED_IN_MINOR_VERSION() only takes effect if the type or namespace is + available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), + \l QML_ANONYMOUS, or \l QML_INTERFACE macro. + + If the QML module the type belongs to is imported with a lower version than + the one determined this way, the QML type is invisible. + + \sa QML_ADDED_IN_VERSION, QML_ELEMENT, QML_NAMED_ELEMENT +*/ + +/*! + \macro QML_REMOVED_IN_VERSION(MAJOR, MINOR) + \relates QQmlEngine + + Declares that the enclosing type or namespace was removed in the specified + \a{MAJOR}.\a{MINOR} version. This is primarily useful when replacing the + implementation of a QML type. If a corresponding \l QML_ADDED_IN_VERSION() + is present on a different type or namespace of the same QML name, then the + removed type is used when importing versions of the module lower than + \a{MAJOR}.\a{MINOR}, and the added type is used when importing + versions of the module greater or equal \a{MAJOR}.\a{MINOR}. + + \l QML_REMOVED_IN_VERSION() only takes effect if type or namespace is + available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), + \l QML_ANONYMOUS, or \l QML_INTERFACE macro. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT +*/ + +/*! + \macro QML_REMOVED_IN_MINOR_VERSION(VERSION) + \relates QQmlEngine + \deprecated [6.7] Use QML_REMOVED_IN_VERSION and specify the full version + + Declares that the enclosing type or namespace was removed in the specified + minor \a VERSION, relative to the module major version. This is primarily + useful when replacing the implementation of a QML type. If a corresponding + \l QML_ADDED_IN_VERSION() is present on a different type or namespace of + the same QML name, then the removed type is used when importing versions of + the module lower than \a VERSION, and the added type is used when importing + versions of the module greater or equal \a VERSION. + + \l QML_REMOVED_IN_MINOR_VERSION() only takes effect if type or namespace is + available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), + \l QML_ANONYMOUS, or \l QML_INTERFACE macro. + + \sa QML_REMOVED_IN_VERSION, QML_ELEMENT, QML_NAMED_ELEMENT +*/ + +/*! + \macro QML_EXTRA_VERSION(MAJOR, MINOR) + \relates QQmlEngine + + Declare that the type should also be available in version \a{MAJOR}.\a{MINOR}. + This can be helpful if a type should be available in multiple major versions. + + Types are automatically registered for: + \list + \li The major version they were introduced in, see \l{QML_ADDED_IN_VERSION}. + \li Any major versions any their members were introduced in. + \li The current major version of their module, unless they were + \l{QML_REMOVED_IN_VERSION} before that. + \endlist + + Notably, they are not automatically registered in any \l{PAST_MAJOR_VERSIONS} + between the above. You can use QML_EXTRA_VERSION to manually register your + types in further major versions. + + \note Keeping multiple \l{PAST_MAJOR_VERSIONS} around is computationally + expensive. + + \sa QML_ELEMENT, QML_ADDED_IN_VERSION +*/ + +/*! + \macro QML_ATTACHED(ATTACHED_TYPE) + \relates QQmlEngine + + Declares that the enclosing type attaches \a ATTACHED_TYPE as an + \l {Attached Properties and Attached Signal Handlers} + {attached property} to other types. This takes effect if the type + is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro. + + \include {qualified-class-name.qdocinc} {class name must be qualified} + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(), + {Providing Attached Properties} +*/ + +/*! + \macro QML_EXTENDED(EXTENDED_TYPE) + \relates QQmlEngine + + Declares that the enclosing type uses \a EXTENDED_TYPE as an extension to + provide further properties, methods, and enumerations in QML. This takes + effect if the type is exposed to QML using a \l QML_ELEMENT or + \l QML_NAMED_ELEMENT() macro. + + \warning Members of \a EXTENDED_TYPE are implicitly treated as FINAL. + + \include {qualified-class-name.qdocinc} {class name must be qualified} + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED_NAMESPACE(), + {Registering Extension Objects} +*/ + +/*! + \macro QML_EXTENDED_NAMESPACE(EXTENDED_NAMESPACE) + \relates QQmlEngine + + Declares that the enclosing type uses \a EXTENDED_NAMESPACE as an extension to + provide further enumerations in QML. This takes effect if the type + is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro. + The enumerations need to be exposed to the metaobject system for this to work. + + For example, give the following C++ code + \code + namespace MyNamespace { + Q_NAMESPACE + enum MyEnum { MyEnumerator = 10 }; + Q_ENUM_NS(MyEnum) + } + + class QmlType : public QObject + { + Q_OBJECT + QML_ELEMENT + QML_EXTENDED_NAMESPACE(MyNamespace) + } + \endcode + + we can access the enum in QML: + \qml + QmlType { + property int i: QmlType.MyEnumerator // i will be 10 + } + \endqml + + \note EXTENDED_NAMESPACE can also be a QObject or QGadget; in that case - and in contrast to + QML_EXTENDED, which also exposes methods and properties - only its enumerations + are exposed. + + \note \a EXTENDED_NAMESPACE must have a metaobject; i.e. it must either be a namespace which + contains the Q_NAMESPACE macro or a QObject/QGadget. + + \include {qualified-class-name.qdocinc} {class name must be qualified} + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED(), + {Registering Extension Objects}, Q_ENUM, Q_ENUM_NS +*/ + +/*! + \macro QML_FOREIGN(FOREIGN_TYPE) + \relates QQmlEngine + + Declares that any \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), \l QML_ANONYMOUS, + \l QML_INTERFACE, \l QML_UNCREATABLE(), \l QML_SINGLETON, + \l QML_ADDED_IN_VERSION(), \l QML_REMOVED_IN_VERSION(), + \l QML_ADDED_IN_MINOR_VERSION(), \l QML_REMOVED_IN_MINOR_VERSION(), + \l QML_EXTENDED(), or \l QML_EXTENDED_NAMESPACE() macros + in the enclosing C++ type do not apply to the enclosing type but instead to + \a FOREIGN_TYPE. The enclosing type still needs to be registered with the + \l {The Meta-Object System}{meta object system} using a \l Q_GADGET or + \l Q_OBJECT macro. + + This is useful for registering types that cannot be amended to add the macros, + for example because they belong to 3rdparty libraries. + To register a namespace, see \l QML_FOREIGN_NAMESPACE(). + + \note You may want to use \l QML_NAMED_ELEMENT() instead of \l QML_ELEMENT. + With QML_ELEMENT, the element is named after the struct it is contained in, + not the foreign type. The \l {Foreign objects integration} chapter in + \l {Writing advanced QML Extensions with C++} demonstrates this. + + \note QML_ATTACHED() can currently not be redirected like this. It has to be + specificed in the same type that implements qmlAttachedProperties(). + + \include {qualified-class-name.qdocinc} {class name must be qualified} + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_FOREIGN_NAMESPACE() +*/ + +/*! + \macro QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE) + \relates QQmlEngine + + Declares that any \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), \l QML_ANONYMOUS, + \l QML_INTERFACE, \l QML_UNCREATABLE(), \l QML_SINGLETON, + \l QML_ADDED_IN_VERSION(), \l QML_REMOVED_IN_VERSION(), + \l QML_ADDED_IN_MINOR_VERSION(), or \l QML_REMOVED_IN_MINOR_VERSION() + macros in the enclosing C++ namespace do not apply to the enclosing type but + instead to \a FOREIGN_NAMESPACE. The enclosing namespace still needs to be + registered with the \l {The Meta-Object System}{meta object system} using a + \l Q_NAMESPACE macro. + + This is useful for registering namespaces that cannot be amended to add the macros, + for example because they belong to 3rdparty libraries. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_FOREIGN() +*/ + +/*! + \macro QML_UNAVAILABLE + \relates QQmlEngine + + This macro declares the enclosing type to be unavailable in QML. It registers + an internal dummy type called \c QQmlTypeNotAvailable as \l QML_FOREIGN() + type, using any further QML macros you specify. + + Normally, the types exported by a module should be fixed. However, if a C++ + type is not available, you should at least "reserve" the QML type name, and + give the user of the unavailable type a meaningful error message. + + Example: + + \code + #ifdef NO_GAMES_ALLOWED + struct MinehuntGame + { + Q_GADGET + QML_NAMED_ELEMENT(Game) + QML_UNAVAILABLE + QML_UNCREATABLE("Get back to work, slacker!"); + }; + #else + class MinehuntGame : public QObject + { + Q_OBJECT + QML_NAMED_ELEMENT(Game) + // ... + }; + #endif + \endcode + + This will cause any QML which attempts to use the "Game" type to produce an + error message: + + \badcode + fun.qml: Get back to work, slacker! + Game { + ^ + \endcode + + Using this technique, you only need a \l Q_GADGET struct to customize the error + message, not a full-blown \l QObject. Without \l QML_UNCREATABLE(), + \l QML_UNAVAILABLE still results in a more specific error message than the usual + "is not a type" for completely unknown types. + + \include {qualified-class-name.qdocinc} {class name must be qualified} + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_FOREIGN() +*/ + +/*! + \macro QML_SEQUENTIAL_CONTAINER(VALUE_TYPE) + \relates QQmlEngine + + This macro declares the enclosing or referenced type as a sequential container + managing a sequence of \a VALUE_TYPE elements. \a VALUE_TYPE can be an actual + \l{QML Value Types}{value type} or a pointer to an + \l{QML Object Types}{object type}. You will rarely be able to add this macro + to the actual container declaration since containers are usually templates. + You should use \l{QML_FOREIGN} to attach the type registration to a template + instantiation. Using this technique you can, for example, declare sequential + containers like this: + + \code + class IntDequeRegistration + { + Q_GADGET + QML_FOREIGN(std::deque<int>) + QML_ANONYMOUS + QML_SEQUENTIAL_CONTAINER(int) + }; + \endcode + + After this, you can use the container like a JavaScript array in QML. + + \code + class Maze + { + Q_OBJECT + Q_ELEMENT + // 0: North, 1: East, 2: South, 3: West + Q_PROPERTY(std::deque<int> solution READ solution CONSTANT FINAL) + [...] + } + \endcode + + \code + Item { + Maze { + id: maze + } + + function showSolution() { + maze.solution.forEach([...]) + } + } + \endcode + + \note For \l{QML Value Types} \l{QList} is automatically registered as + sequential container. For \l{QML Object Types} \l{QQmlListProperty} is. + You don't have to add these registrations. + + \note You cannot currently give the container a custom name. Any argument + passed to \l{QML_NAMED_ELEMENT} is ignored. The automatically registered + sequential containers are available under the familiar \e{list<...>} names, + for example \e{list<QtObject>} or \e{list<font>}. + + \include {qualified-class-name.qdocinc} {class name must be qualified} + + \sa QML_ANONYMOUS, QML_FOREIGN() +*/ /*! \macro QML_DECLARE_TYPE() @@ -41,7 +700,8 @@ Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which declares that the \a Type supports \l {Attached Properties and Attached Signal Handlers} - {attached properties}. + {attached properties}. QML_DECLARE_TYPEINFO() is not necessary if \a Type contains the + QML_ATTACHED macro. */ /*! @@ -58,7 +718,7 @@ /*! - \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + \fn template <typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) \relates QQmlEngine This template function registers the C++ type in the QML system with @@ -106,11 +766,12 @@ QML written to previous versions to continue to work, even if more advanced versions of some of its types are available. - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), + {Choosing the Correct Integration Method Between C++ and QML} */ /*! - \fn int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) + \fn template<typename T, int metaObjectRevision> int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) \relates QQmlEngine This template function registers the specified revision of a C++ type in the QML system with @@ -129,7 +790,7 @@ */ /*! - \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) + \fn template <typename T> int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) \relates QQmlEngine This template function registers the C++ type in the QML system with @@ -143,12 +804,12 @@ Returns the QML type id. - \sa qmlRegisterTypeNotAvailable(), + \sa QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(), {Choosing the Correct Integration Method Between C++ and QML} */ /*! - \fn int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + \fn template <typename T, typename E> int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) \relates QQmlEngine This template function registers the C++ type and its extension object in the @@ -158,12 +819,12 @@ Returns the QML type id. - \sa qmlRegisterType(), {Registering Extension Objects} + \sa QML_EXTENDED(), qmlRegisterType(), {Registering Extension Objects} */ /*! - \fn int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason) + \fn template <typename T, typename E> int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason) \relates QQmlEngine This template function registers the C++ type and its extension @@ -180,7 +841,7 @@ Returns the QML type id. - \sa qmlRegisterUncreatableType() + \sa QML_EXTENDED(), QML_UNCREATABLE(), qmlRegisterUncreatableType() */ /*! @@ -209,7 +870,7 @@ Key1, Key2, }; - Q_ENUMS(MyEnum) + Q_ENUM_NS(MyEnum) } //... @@ -220,6 +881,8 @@ \code Component.onCompleted: console.log(MyNamespace.Key2) \endcode + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE() */ /*! @@ -235,6 +898,8 @@ the \a parser provided. Returns the QML type id. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED() */ /*! @@ -269,22 +934,22 @@ Without this, a generic "Game is not a type" message would be given. - \sa qmlRegisterUncreatableType(), + \sa QML_UNAVAILABLE, qmlRegisterUncreatableType(), {Choosing the Correct Integration Method Between C++ and QML} */ /*! - \fn int qmlRegisterType() + \fn template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor) \relates QQmlEngine - \overload - This template function registers the C++ type in the QML - system. Instances of this type cannot be created from the QML - system. + This template function registers the C++ type in the QML system as an anonymous type. The + resulting QML type does not have a name. Therefore, instances of this type cannot be created from + the QML system. You can, however, access instances of the type when they are exposed as properties + of other types. - This function should be used when the type will not be referenced by name. - Specifically, it has to be used for C++ types that are used as the left-hand - side of a property binding. + Use this function when the type will not be referenced by name, specifically for C++ types that + are used on the left-hand side of a property binding. To indicate to which module the type belongs + use \a uri and \a versionMajor. For example, consider the following two classes: @@ -344,15 +1009,16 @@ \code qmlRegisterType<Foo>("App", 1, 0, "Foo"); - qmlRegisterType<Bar>(); + qmlRegisterAnonymousType<Bar>("App", 1); \endcode As the \c Foo type is instantiated in QML, it must be registered - with the version of \l qmlRegisterType() that takes an import URI. + with the version of \l qmlRegisterType() that takes an element name. Returns the QML type id. - \sa {Choosing the Correct Integration Method Between C++ and QML} + \since 5.14 + \sa QML_ANONYMOUS, {Choosing the Correct Integration Method Between C++ and QML} */ /*! @@ -386,10 +1052,12 @@ the interface cast to \c FooInterface* automatically. Returns the QML type id. + + \sa QML_INTERFACE */ /*! - \fn int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QJSValue (*callback)(QQmlEngine *, QJSEngine *)) + \fn int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue(QQmlEngine *, QJSEngine *)> callback) \relates QQmlEngine This function may be used to register a singleton type provider \a callback in a particular \a uri @@ -444,11 +1112,11 @@ } \endqml - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML} */ /*! - \fn template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true) + \fn template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create) \relates QQmlEngine The form of this template function is: @@ -463,15 +1131,24 @@ If \a create is true and type \e T is a valid attaching type, this creates and returns a new attached object instance. - Returns 0 if type \e T is not a valid attaching type, or if \a create is false and no + Returns \nullptr if type \e T is not a valid attaching type, or if \a create is false and no attachment object instance has previously been created for \a attachee. - \sa {Providing Attached Properties} + \sa QML_ATTACHED(), {Providing Attached Properties} +*/ + +/*! + \fn QObject *qmlExtendedObject(const QObject *base) + \relates QQmlEngine + + This function returns the extension object that belongs to \a base, if there is any. + Otherwise it returns \c nullptr. + \sa QML_EXTENDED */ /*! - \fn int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *(*callback)(QQmlEngine *, QJSEngine *)) + \fn template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject*(QQmlEngine *, QJSEngine *)> callback) \relates QQmlEngine This function may be used to register a singleton type provider \a callback in a particular \a uri @@ -487,8 +1164,7 @@ A QObject singleton type may be referenced via the type name with which it was registered, and this typename may be used as the target in a \l Connections type or otherwise used as any other type id would. - One exception to this is that a QObject singleton type property may not be aliased (because the - singleton type name does not identify an object within the same component as any other item). + One exception to this is that a QObject singleton type property may not be aliased. \b{NOTE:} A QObject singleton type instance returned from a singleton type provider is owned by the QML engine unless the object has explicit QQmlEngine::CppOwnership flag set. @@ -502,7 +1178,7 @@ Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged) public: - SingletonTypeExample(QObject* parent = 0) + SingletonTypeExample(QObject *parent = nullptr) : QObject(parent), m_someProperty(0) { } @@ -538,7 +1214,7 @@ Alternatively, you can use a C++11 lambda: \code - qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * { + qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * { Q_UNUSED(engine) Q_UNUSED(scriptEngine) @@ -561,7 +1237,7 @@ } \endqml - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML} */ /*! @@ -608,9 +1284,106 @@ That can be done by adding a pragma Singleton statement among the imports of the type's QML file. In addition the type must be defined in a qmldir file with a singleton keyword and the qmldir must be imported by the QML files using the singleton. + + \sa QML_SINGLETON */ /*! + \fn int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject) + \relates QQmlEngine + \since 5.14 + + This function is used to register a singleton object \a cppObject, with a + particular \a uri and \a typeName. Its version is a combination of \a + versionMajor and \a versionMinor. + + Installing a singleton type into a URI allows you to provide arbitrary + functionality (methods and properties) to QML code without requiring + individual instances of the type to be instantiated by the client. + + Use this function to register an object of the given type T as a singleton + type. + + A QObject singleton type may be referenced via the type name with which it + was registered; in turn this type name may be used as the target in a \l + Connections type, or like any other type ID. However, there's one + exception: a QObject singleton type property can't be aliased because the + singleton type name does not identify an object within the same component + as any other item. + + \note \a cppObject must outlive the QML engine in which it is used. + Moreover, \cppObject must have the same thread affinity as the engine. If + you want separate singleton instances for multiple engines, you need to use + \l {qmlRegisterSingletonType}. See \l{Threads and QObjects} for more + information about thread safety. + + \b{NOTE:} qmlRegisterSingleton can only be used when all types of that module are registered procedurally. + + Usage: + \code + // First, define your QObject which provides the functionality. + class SingletonTypeExample : public QObject + { + Q_OBJECT + Q_PROPERTY(int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged) + + public: + explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {} + + Q_INVOKABLE int doSomething() + { + setSomeProperty(5); + return m_someProperty; + } + + int someProperty() const { return m_someProperty; } + void setSomeProperty(int val) { + if (m_someProperty != val) { + m_someProperty = val; + emit somePropertyChanged(val); + } + } + + signals: + void somePropertyChanged(int newValue); + + private: + int m_someProperty = 0; + }; + \endcode + + \code + // Second, create an instance of the object + + // allocate example before the engine to ensure that it outlives it + QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample); + QQmlEngine engine; + + // Third, register the singleton type provider with QML by calling this + // function in an initialization function. + qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get()); + \endcode + + + In order to use the registered singleton type in QML, you must import the + URI with the corresponding version. + \qml + import QtQuick 2.0 + import Qt.example.qobjectSingleton 1.0 + Item { + id: root + property int someValue: MyApi.someProperty + + Component.onCompleted: { + console.log(MyApi.doSomething()) + } + } + \endqml + + \sa QML_SINGLETON, qmlRegisterSingletonType + */ + +/*! \fn int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName); \relates QQmlEngine @@ -628,20 +1401,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 @@ -681,5 +1459,154 @@ Returns -1 if no matching type was found or one of the given parameters was invalid. - \sa qmlRegisterType(), qmlRegisterSingletonType() + \note: qmlTypeId tries to make modules available, even if they were not accessed by any + engine yet. This can introduce overhead the first time a module is accessed. Trying to + find types from a module which does not exist always introduces this overhead. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), qmlRegisterSingletonType() +*/ + +/*! + \macro QML_VALUE_TYPE(name) + \relates QQmlEngine + + Declares the enclosing type or namespace to be available in QML, using \a name + as the name. The type has to be a value type and the name has to be lower case. + + \code + class MyValueType + { + Q_GADGET + QML_VALUE_TYPE(myValueType) + + // ... + }; + \endcode + + \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT +*/ + +/*! + \macro QML_CONSTRUCTIBLE_VALUE + \since 6.5 + \relates QQmlEngine + + Marks the surrounding value type as constructible. That is, any \l Q_INVOKABLE + constructors of the type that take exactly one argument can be used when + assigning a JavaScript value to a property of this type. + + You can declare a constructible value type as follows: + + \code + class MyValueType + { + Q_GADGET + QML_VALUE_TYPE(myValueType) + QML_CONSTRUCTIBLE_VALUE + public: + Q_INVOKABLE MyValueType(double d); + + // ... + }; + \endcode + + With the above type, the following QML code will produce a \c MyValueType + value using the given constructor and assign it to the property. + + \qml + QtObject { + property myValueType v: 5.4 + } + \endqml + + You can also construct lists of values this way: + + \qml + QtObject { + property list<myValueType> v: [5.4, 4.5, 3.3] + } + \endqml + + If you make value types \l{ValueTypeBehavior}{addressable}, you can + use such a type in a \l{Type annotations and assertions}{type assertion} + to explicitly construct it: + + \qml + pragma ValueTypeBehavior: Addressable + + QtObject { + function process(d: real) { + let v = d as myValueType; + // v is a myValueType now, not a number + } + } + \endqml + + \sa QML_VALUE_TYPE +*/ + +/*! + \macro QML_STRUCTURED_VALUE + \since 6.5 + \relates QQmlEngine + + Marks the surrounding value type as structured. Structured value types can + and will preferably be constructed property-by-property from a JavaScript + object. A structured value type, however is always \l QML_CONSTRUCTIBLE_VALUE, + too. This means, you can still provide \l Q_INVOKABLE constructors in order to + handle construction from primitive types. + + You can declare a structured value type as follows: + + \code + class MyValueType + { + Q_GADGET + QML_VALUE_TYPE(myValueType) + QML_STRUCTURED_VALUE + Q_PROPERTY(double d READ d WRITE setD) + Q_PROPERTY(string e READ e WRITE setE) + + // ... + }; + \endcode + + Then you can populate a property of this type as follows: + + \qml + QtObject { + property myValueType v: ({d: 4.4, e: "a string"}) + } + \endqml + + The extra parentheses are necessary to disambiguate the JavaScript object + from what might be interpreted as a JavaScript code block. + + You can also construct lists of values this way: + + \qml + QtObject { + property list<myValueType> v: [ + {d: 4.4, e: "a string"}, + {d: 7.1, e: "another string"} + ] + } + \endqml + + If you make value types \l{ValueTypeBehavior}{addressable}, you can + use such a type in a \l{Type annotations and assertions}{type assertion} + to explicitly construct it: + + \qml + pragma ValueTypeBehavior: Addressable + + QtObject { + function process(d: real) { + let v = {d: d, e: objectName} as myValueType; + // v is a myValueType now + } + } + \endqml + + \sa QML_VALUE_TYPE QML_CONSTRUCTIBLE_VALUE */ diff --git a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc index 2de4eb0c18..df609fb3b9 100644 --- a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc @@ -1,53 +1,45 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-documents-definetypes.html \title Defining Object Types through QML Documents \brief Description of how a QML document is a reusable type definition -One of the core features of QML is that it enables QML object types to be easily defined in a lightweight manner through QML documents to suit the needs of individual QML applications. The standard \l {Qt Quick} module provides various types like \l Rectangle, \l Text and \l Image for building a QML application; beyond these, you can easily define your own QML types to be reused within your application. This ability to create your own types forms the building blocks of any QML application. +One of the core features of QML is that it enables QML object types to be +easily defined in a lightweight manner through QML documents to suit the needs +of individual QML applications. The standard \l {Qt Quick} module provides +various types like \l Rectangle, \l Text and \l Image for building a QML +application; beyond these, you can easily define your own QML types to be +reused within your application. This ability to create your own types forms the +building blocks of any QML application. \section1 Defining an Object Type with a QML File \section2 Naming Custom QML Object Types -To create an object type, a QML document should be placed into a text file named as \e <TypeName>.qml where \e <TypeName> is the desired name of the type. The type name has the following requirements: +To create an object type, a QML document should be placed into a text file +named as \e <TypeName>.qml where \e <TypeName> is the desired name of the type. +The type name has the following requirements: \list \li It must be comprised of alphanumeric characters or underscores. \li It must begin with an uppercase letter. \endlist -This document is then automatically recognized by the engine as a definition of a QML type. Additionally, a type defined in this manner is automatically made available to other QML files within the same directory as the engine searches within the immediate directory when resolving QML type names. +This document is then automatically recognized by the engine as a definition of +a QML type. Additionally, a type defined in this manner is automatically made +available to other QML files within the same 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 -For example, below is a document that declares a \l Rectangle with a child \l MouseArea. The document has been saved to file named \c SquareButton.qml: +For example, below is a document that declares a \l Rectangle with a child \l +MouseArea. The document has been saved to file named \c SquareButton.qml: \qml // SquareButton.qml @@ -65,7 +57,10 @@ Rectangle { } \endqml -Since the file is named \c SquareButton.qml, \b {this can now be used as a type named \c SquareButton by any other QML file within the same directory}. For example, if there was a \c myapplication.qml file in the same directory, it could refer to the \c SquareButton type: +Since the file is named \c SquareButton.qml, \b {this can now be used as a type +named \c SquareButton by any other QML file within the same directory}. For +example, if there was a \c myapplication.qml file in the same directory, it +could refer to the \c SquareButton type: \qml // myapplication.qml @@ -76,23 +71,80 @@ SquareButton {} \image documents-definetypes-simple.png -This creates a 100 x 100 red \l Rectangle with an inner \l MouseArea, as defined in \c SquareButton.qml. When this \c myapplication.qml document is loaded by the engine, it loads the SquareButton.qml document as a component and instantiates it to create a \c SquareButton object. +This creates a 100 x 100 red \l Rectangle with an inner \l MouseArea, as +defined in \c SquareButton.qml. When this \c myapplication.qml document is +loaded by the engine, it loads the SquareButton.qml document as a component and +instantiates it to create a \c SquareButton object. + +The \c SquareButton type encapsulates the tree of QML objects declared in \c +SquareButton.qml. When the QML engine instantiates a \c SquareButton object +from this type, it is instantiating an object from the \l Rectangle tree +declared in \c SquareButton.qml. + +\note the letter case of the file name is significant on some (notably UNIX) +filesystems. It is recommended the file name case matches the case of the +desired QML type name exactly - for example, \c Box.qml and not \c BoX.qml - +regardless of the platform to which the QML type will be deployed. + +\section2 Inline Components + +Sometimes, it can be inconvenient to create a new file for a type, for +instance when reusing a small delegate in multiple views. If you don't actually +need to expose the type, but only need to create an instance, +\l{QtQml::Component}{Component} is an option. +But if you want to declare properties with the component types, or if you +want to use it in multiple files, \c Component is not an option. In that case, +you can use \e {inline components}. Inline components declare a new component +inside of a file. The syntax for that is +\code +component <component name> : BaseType { + // declare properties and bindings here +} +\endcode + +Inside the file which declares the inline component, the type can be referenced +simply by its name. + +\snippet qml/qml-documents/Images.qml document + +In other files, it has to be prefixed with the name of its containing component. -The \c SquareButton type encapsulates the tree of QML objects declared in \c SquareButton.qml. When the QML engine instantiates a \c SquareButton object from this type, it is instantiating an object from the \l Rectangle tree declared in \c SquareButton.qml. +\snippet qml/qml-documents/LabeledImageBox.qml document -\note the letter case of the file name is significant on some (notably UNIX) filesystems. It is recommended the file name case matches the case of the desired QML type name exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the QML type will be deployed. +\note Inline components don't share their scope with the component they are +declared in. In the following example, when \c A.MyInlineComponent in file +B.qml gets created, a ReferenceError will occur, as \c root does not exist as +an id in B.qml. +It is therefore advisable not to reference objects in an inline component +which are not part of it. + +\snippet qml/qml-documents/A.qml document +\snippet qml/qml-documents/B.qml document + +\note Inline components cannot be nested. \section2 Importing Types Defined Outside the Current Directory If \c SquareButton.qml was not in the same directory as \c myapplication.qml, -the \c SquareButton type would need to be specifically made available through an \e import statement in \c myapplication.qml. It could be imported from a relative path on the file system, or as an installed module; see \l {QML Modules}{module} for more details. +the \c SquareButton type would need to be specifically made available through +an \e import statement in \c myapplication.qml. It could be imported from a +relative path on the file system, or as an installed module; see \l {QML +Modules}{module} for more details. \section1 Accessible Attributes of Custom Types -The \b {root object} definition in a .qml file \b {defines the attributes that are available for a QML type}. All properties, signals and methods that belong to this root object - whether they are custom declared, or come from the QML type of the root object - are externally accessible and can be read and modified for objects of this type. +The \b {root object} definition in a .qml file \b {defines the attributes that +are available for a QML type}. All properties, signals and methods that belong +to this root object - whether they are custom declared, or come from the QML +type of the root object - are externally accessible and can be read and +modified for objects of this type. -For example, the root object type in the \c SquareButton.qml file above is \l Rectangle. This means any properties defined by the \l Rectangle type can be modified for a \c SquareButton object. The code below defines three \c SquareButton objects with customized values for some of the properties of the root \l Rectangle object of the \c SquareButton type: +For example, the root object type in the \c SquareButton.qml file above is \l +Rectangle. This means any properties defined by the \l Rectangle type can be +modified for a \c SquareButton object. The code below defines three \c +SquareButton objects with customized values for some of the properties of the +root \l Rectangle object of the \c SquareButton type: \qml // application.qml @@ -107,7 +159,12 @@ Column { \image documents-definetypes-attributes.png -The attributes that are accessible to objects of the custom QML type include any \l{Defining Property Attributes}{custom properties}, \l{Defining Method Attributes}{methods} and \l{Defining Signal Attributes}{signals} that have additionally been defined for an object. For example, suppose the \l Rectangle in \c SquareButton.qml had been defined as follows, with additional properties, methods and signals: +The attributes that are accessible to objects of the custom QML type include +any \l{Defining Property Attributes}{custom properties}, \l{Defining Method +Attributes}{methods} and \l{Defining Signal Attributes}{signals} that have +additionally been defined for an object. For example, suppose the \l Rectangle +in \c SquareButton.qml had been defined as follows, with additional properties, +methods and signals: \qml // SquareButton.qml @@ -131,12 +188,14 @@ Rectangle { MouseArea { id: mouseArea anchors.fill: parent - onClicked: root.buttonClicked(mouse.x, mouse.y) + onClicked: (mouse)=> root.buttonClicked(mouse.x, mouse.y) } } \endqml -Any \c SquareButton object could make use of the \c pressed property, \c buttonClicked signal and \c randomizeColor() method that have been added to the root \l Rectangle: +Any \c SquareButton object could make use of the \c pressed property, \c +buttonClicked signal and \c randomizeColor() method that have been added to the +root \l Rectangle: \qml // application.qml @@ -145,7 +204,7 @@ import QtQuick 2.0 SquareButton { id: squareButton - onButtonClicked: { + onButtonClicked: (xPos, yPos)=> { console.log("Clicked", xPos, yPos) randomizeColor() } @@ -154,7 +213,12 @@ SquareButton { } \endqml -Note that any of the \c id values defined in \c SquareButton.qml are not accessible to \c SquareButton objects, as id values are only accessible from within the component scope in which a component is declared. The \c SquareButton object definition above cannot refer to \c mouseArea in order to refer to the \l MouseArea child, and if it had an \c id of \c root rather than \c squareButton, this would not conflict with the \c id of the same value for the root object defined in \c SquareButton.qml as the two would be declared within separate scopes. - - +Note that any of the \c id values defined in \c SquareButton.qml are not +accessible to \c SquareButton objects, as id values are only accessible from +within the component scope in which a component is declared. The \c +SquareButton object definition above cannot refer to \c mouseArea in order to +refer to the \l MouseArea child, and if it had an \c id of \c root rather than +\c squareButton, this would not conflict with the \c id of the same value for +the root object defined in \c SquareButton.qml as the two would be declared +within separate scopes. */ diff --git a/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc index d762621d6c..2107522cf0 100644 --- a/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-documents-networktransparency.html \title Resource Loading and Network Transparency @@ -51,7 +27,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/documents/scope.qdoc b/src/qml/doc/src/qmllanguageref/documents/scope.qdoc index 7ecf0b0a0a..0bbbcae178 100644 --- a/src/qml/doc/src/qmllanguageref/documents/scope.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/scope.qdoc @@ -1,33 +1,10 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-documents-scope.html \title Scope and Naming Resolution \brief overview of scope and naming resolution +\ingroup explanations-programminglanguages QML property bindings, inline functions, and imported JavaScript files all run in a JavaScript scope. Scope controls which variables an expression can diff --git a/src/qml/doc/src/qmllanguageref/documents/structure.qdoc b/src/qml/doc/src/qmllanguageref/documents/structure.qdoc index 666039c73a..72a6e08407 100644 --- a/src/qml/doc/src/qmllanguageref/documents/structure.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/structure.qdoc @@ -1,38 +1,15 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-documents-structure.html \title Structure of a QML Document \brief Description of the structure of QML documents -A QML document is a self contained piece of QML source code that consists of two parts: +A QML document is a self contained piece of QML source code that consists of three parts: \list + \li An optional list of pragmas \li Its \e import statements \li A single root object declaration \endlist @@ -43,6 +20,307 @@ QML documents are always encoded in UTF-8 format. +\section1 Pragmas + +Pragmas are instructions to the QML engine itself that can be used to specify +certain characteristics of objects in the current file or to modify how the +engine interprets code. The following pragmas are exaplained in details below. + +\list +\li \c Singleton +\li \c ListPropertyAssignBehavior +\li \c ComponentBehavior +\li \c FunctionSignatureBehavior +\li \c NativeMethodBehavior +\li \c ValueTypeBehavior +\li \c Translator +\endlist + +\section2 Singleton + +\c{pragma Singleton} declares the component defined in the QML document as +singleton. Singletons are created only once per QML engine. In order to use +a QML-declared singleton you also have to register it with its module. See +\l{qt_target_qml_sources} for how to do this with CMake. + +\section2 ListPropertyAssignBehavior + +With this pragma you can define how assignments to list properties shall be +handled in components defined in the QML document. By default, assigning to a +list property appends to the list. You can explicitly request this behavior +using the value \c{Append}. Alternatively, you can request the contents of list +properties to always be replaced using \c{Replace}, or replaced if the property +is not the default property using \c{ReplaceIfNotDefault}. For example: + +\qml +pragma ListPropertyAssignBehavior: ReplaceIfNotDefault +\endqml + +\note The same declaration can also be given for C++-defined types, by adding +the \l{QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND}, +\l{QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE}, and +\l{QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT} macros to the +class declaration. + +\section2 ComponentBehavior + +You may have multiple components defined in the same QML file. The root +scope of the QML file is a component, and you may additionally have +elements of type \l QQmlComponent, explicitly or implicitly created +as properties, or inline components. Those components are nested. Each +of the inner components is within one specific outer component. Most of +the time, IDs defined in an outer component are accessible within all +its nested inner components. You can, however, create elements from a +component in any a different context, with different IDs available. +Doing so breaks the assumption that outer IDs are available. Therefore, +the engine and the QML tooling cannot generally know in advance what +type, if any, such IDs will resolve to at run time. + +With the ComponentBehavior pragma you can restrict all inner components +defined in a file to only create objects within their original context. +If a component is bound to its context, you can safely use IDs from +outer components in the same file within the component. QML tooling will +then assume the outer IDs with their specific types to be available. + +In order to bind the components to their context specify the \c{Bound} +argument: + +\qml +pragma ComponentBehavior: Bound +\endqml + +This implies that, in case of name clashes, IDs defined outside a bound +component override local properties of objects created from the +component. Otherwise it wouldn't actually be safe to use the IDs since +later versions of a module might add more properties to the component. +If the component is not bound, local properties override IDs defined +outside the component, but not IDs defined inside the component. + +The example below prints the \e r property of the ListView object with +the id \e color, not the \e r property of the rectangle's color. + +\qml +pragma ComponentBehavior: Bound +import QtQuick + +ListView { + id: color + property int r: 12 + model: 1 + + delegate: Rectangle { + Component.onCompleted: console.log(color.r) + } +} +\endqml + +The default value of \c ComponentBehavior is \c{Unbound}. You can also +specify it explicitly. In a future version of Qt the default will change +to \c{Bound}. + +Delegate components bound to their context don't receive their own +private contexts on instantiation. This means that model data can only +be passed via \l{Required Properties}{required properties} in this case. +Passing model data via context properties will not work. This concerns +delegates to e.g. \l{Instantiator}, \l{Repeater}, \l{ListView}, +\l{TableView}, \l{GridView}, \l{TreeView} and in general anything that +uses \l{DelegateModel} internally. + +For example, the following will \e{not} work: + +\qml +pragma ComponentBehavior: Bound +import QtQuick + +ListView { + delegate: Rectangle { + color: model.myColor + } +} +\endqml + +The \c{delegate} property of \l{ListView} is a component. Therefore, a +\l{Component} is implicitly created around the \l{Rectangle} here. That +component is bound to its context. It doesn't receive the context property +\c{model} provided by \l{ListView}. To make it work, you'd have to write +it this way: + +\qml +pragma ComponentBehavior: Bound +import QtQuick + +ListView { + delegate: Rectangle { + required property color myColor + color: myColor + } +} +\endqml + +You can nest components in a QML file. The pragma holds for all components in +the file, no matter how deeply nested. + +\section2 FunctionSignatureBehavior + +With this pragma you can change the way type annotations on functions +are handled. Since Qt 6.7 type annotations are enforced when calling +functions. Before, only the \l{QML script compiler} enforced the type +annotations. The interpreter and JIT compiler ignored them. Always +enforcing the type annotations is a behavior change in comparison to +earlier versions since you could call functions with mismatched +arguments before. + +Specifying \c{Ignored} as value makes the QML engine and the +\l{QML script compiler} ignore any type annotations and therefore +restores the pre-6.7 behavior of the interpreter and JIT. As a result +less code is compiled to C++ ahead of time, and more code has to be +interpreted or JIT-compiled. + +Specifying \c{Enforced} as value explicitly states the default: Type +annotations are always enforced. + +\sa {Type annotations and assertions} + +\section2 NativeMethodBehavior + +Calling C++ methods with \c this objects different from the one they were +retrieved from is broken, due to historical reasons. The original object is +used as \c this object. You can allow the given \c this object to be used by +setting \c {pragma NativeMethodBehavior: AcceptThisObject}. Specifying +\c RejectThisObject keeps the historical behavior. + +An example of this can be found under \l {C++ methods and the 'this' object}. + +\section2 ValueTypeBehavior + +With this pragma you can change the way value types and sequences are handled. + +Usually lower case names cannot be type names in JavaScript code. This is a +problem because value type names are lower case. You can specify \c{Addressable} +as value for this pragma to change this. If \c{Addressable} is specified a +JavaScript value can be explicitly coerced to a specific, named, value type. This is +done using the \c as operator, like you would do with object types. Furthermore, +you can also check for value types using the \c instanceof operator: + +\qml +pragma ValueTypeBehavior: Addressable +import QtQml + +QtObject { + property var a + property real b: (a as rect).x + property bool c: a instanceof rect + + property var rect // inaccessible. "rect" is a type name. +} +\endqml + +Since \c rect in the above example is now a type name, it will shadow any +properties called \c{rect}. + +Explicitly casting to the desired type helps tooling. It can allow the +\l{Qt Quick Compiler} generate efficient code where it otherwise would not be +able to. You can use \l{qmllint Reference}{qmllint} to find such occurrences. + +There is also a \c{Inaddressable} value you can use to explicitly specify the +default behavior. + +Another attribute to the \c{ValueTypeBehavior} pragma is \c{Assertable}, +introduced in Qt 6.8. Due to a mistake in Qt 6.6 and 6.7 the \c{a as rect} above +not only checks whether \c{a} is a \c{rect} but also constructs a \c{rect} if +\c{a} is of a compatible type. This is obviously not what a type assertion +should do. Specifying \c{Assertable} prevents this behavior and restricts type +assertions for value types to only check for the type. You should always specify +it if you are going to use value types with \c{as}. In any case, if the +type assertion for a value type fails, the result is \c{undefined}. + +\c{instanceof} does not have this problem since it only checks for inheritance, +not for all possible type coercions. + +\note Using \c{as} with the \c{int} and \c{double} types is not advisable since by +JavaScript rules, the result of any calculation is a floating point number, even +if it happens to hold the same value as its integer equivalent. Conversely, any +integer constant you declare in JavaScript is not a double by QML's type mapping +rules. Furthermore, \c{int} and \c{double} are reserved words. You can only +address these types via type namespaces. + +Value types and sequences are generally treated as references. This means, if +you retrieve a value type instance from a property into a local value, and then +change the local value, the original property is also changed. Furthermore, +if you write the original property explicitly, the local value is also updated. +This behavior is rather unintuitive in many places, and you should not rely on +it. The \c{Copy} and \c{Reference} values for the \c{ValueTypeBehavior} pragma +are experimental options to change this behavior. You should not use them. +Specifying \c{Copy} causes all value types to be treated as actual copies. +Specifying \c{Reference} explicitly states the default behavior. + +Rather than using \c{Copy} you should explicitly re-load references to value +types and sequences any time they can have been affected by side effects. Side +effects can happen whenever you call a function or imperatively set a property. +\l qmllint provides guidance on this. For example, in the following code +the variable \c f is affected by side effects after writing \c width. This is +because there may be a binding in a derived type or in a \c Binding element +that updates \c font when \c width is changed. + +\qml +import QtQuick +Text { + function a() : real { + var f = font; + width = f.pixelSize; + return f.pointSize; + } +} +\endqml + +In order to address this, you can avoid holding \c f across the write operation +on \c width: + +\qml +import QtQuick +Text { + function a() : real { + var f = font; + width = f.pixelSize; + f = font; + return f.pointSize; + } +} +\endqml + +This, in turn can be shortened to: + +\qml +import QtQuick +Text { + function a() : real { + width = font.pixelSize; + return font.pointSize; + } +} +\endqml + +You might assume that re-retrieving the \c font property is costly, but actually +the QML engine automatically refreshes value type references each time you read +from them. So this is not more expensive than the first version, but a clearer +way to express the same operations. + +\sa {Type annotations and assertions} + +\section2 Translator + +With this pragma you can set the context for the translations in the file. + +\qml +pragma Translator: myTranslationContext +\endqml + +\qml +pragma Translator: "myTranslationContext" +\endqml + +For more information on internationalization with QML, see \l{QML: Use qsTr()}{Use qsTr}. + \section1 Imports A document must import the necessary modules or type namespaces to enable the diff --git a/src/qml/doc/src/qmllanguageref/documents/topic.qdoc b/src/qml/doc/src/qmllanguageref/documents/topic.qdoc index 47130ce39e..3b07bf0c16 100644 --- a/src/qml/doc/src/qmllanguageref/documents/topic.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/topic.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-documents-topic.html \title QML Documents @@ -44,9 +20,9 @@ code. Since Qt 5.4, a document can also have the file extension \c ".ui.qml". The QML engine handles these files like standard .qml files and ignores the \c .ui part -of the extension. Qt Creator handles those files as -\l{Qt Creator: Qt Quick UI Forms}{UI forms} for the Qt Quick Designer. The files -can contain only a subset of the QML language that is defined by Qt Creator. +of the extension. Qt Design Studio handles those files as +\l{Qt Design Studio: UI Files}{UI files}. The files can contain only a subset +of the QML language features. \section1 Structure of a QML Document diff --git a/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc index 32ba948359..1bbc51bf2a 100644 --- a/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-modules-cppplugins.html @@ -34,9 +10,8 @@ The \l{QQmlEngine}{QML engine} loads C++ plugins for QML. Such plugins are usually provided in a QML extension module, and can - provide types for use by clients in QML documents which import the module. - A module requires at least one type registered in order to be considered - valid. + provide types for use by clients in QML documents that import the module. + A module requires at least one registered type to be considered valid. \include qqmlextensionplugin.qdocinc diff --git a/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc index 914a40599c..93461f1ed7 100644 --- a/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-modules-identifiedmodules.html \title Identified Modules @@ -35,8 +11,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 +20,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 @@ -171,27 +153,25 @@ An identified module has several restrictions upon it: \li the module must register its types into the module identifier type namespace \li the module may not register types into any other module's namespace -\li clients must specify a version when importing the module \endlist For example, if an identified module is installed into -\c{$QML2_IMPORT_PATH/ExampleModule}, the module identifier directive must be: +\c{$QML_IMPORT_PATH/ExampleModule}, the module identifier directive must be: \code module ExampleModule \endcode If the strict module is installed into -\c{$QML2_IMPORT_PATH/com/example/CustomUi}, the module identifier directive +\c{$QML_IMPORT_PATH/com/example/CustomUi}, the module identifier directive must be: \code module com.example.CustomUi \endcode Clients will then be able to import the above module with the following import -statement (assuming that the module registers types into version 1.0 of its -namespace): +statement: \qml -import com.example.CustomUi 1.0 +import com.example.CustomUi \endqml */ diff --git a/src/qml/doc/src/qmllanguageref/modules/legacymodules.qdoc b/src/qml/doc/src/qmllanguageref/modules/legacymodules.qdoc index a84f8f07a1..51bb424d22 100644 --- a/src/qml/doc/src/qmllanguageref/modules/legacymodules.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/legacymodules.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-modules-legacymodules.html diff --git a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc index 0faad43f4f..ac82d8136e 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-modules-qmldir.html \title Module Definition qmldir Files @@ -43,240 +19,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 -plugin <Name> [<Path>] - \endcode - \li Declares a plugin to be made available by the module. - - \list - \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{Writing a qmltypes file}{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 -# <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. - -\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 @@ -376,128 +399,34 @@ The \c CustomButton type used above would come from the definition specified in the \c CustomButton21.qml file, and the JavaScript resource identified by the \c MathFunctions identifier would be defined in the \c mathfuncs.js file. -\section1 Writing a qmltypes File +\section1 Type Description Files QML modules may refer to one or more type information files in their \c qmldir file. These usually have the \c .qmltypes extension and are read by external tools to gain information about -types defined in plugins. +types defined in C++ and typically imported via plugins. As such qmltypes files have no effect on the functionality of a QML module. Their only use is to allow tools such as Qt Creator to provide code completion, error checking and other functionality to users of your module. -Any module that uses plugins should also ship a type description file. +Any module that defines QML types in C++ should also ship a type description +file. The best way to create a qmltypes file for your module is to generate it -using the \c qmlplugindump tool that is provided with Qt. +using the build system and the \l QML_ELEMENT macros. If you follow the +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, you could run -\code -qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes -\endcode -to generate type information for your module. Afterwards, add the line +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 \code -typeinfo mymodule.qmltypes +typeinfo plugins.qmltypes \endcode to \c /tmp/imports/My/Module/qmldir to register it. -While the qmldump tool covers most cases, it does not work if: -\list -\li The plugin uses a \c{QQmlCustomParser}. The component that uses - the custom parser will not get its members documented. -\li The plugin can not be loaded. In particular if you cross-compiled - the plugin for a different architecture, qmldump will not be able to - load it. -\endlist - -In case you have to create a qmltypes file manually or need to adjust -an existing one, this is the file format: - -\qml -import QtQuick.tooling 1.1 - -// There always is a single Module object that contains all -// Component objects. -Module { - // A Component object directly corresponds to a type exported - // in a plugin with a call to qmlRegisterType. - Component { - - // The name is a unique identifier used to refer to this type. - // It is recommended you simply use the C++ type name. - name: "QQuickAbstractAnimation" - - // The name of the prototype Component. - prototype: "QObject" - - // The name of the default property. - defaultProperty: "animations" - - // The name of the type containing attached properties - // and methods. - attachedType: "QQuickAnimationAttached" - - // The list of exports determines how a type can be imported. - // Each string has the format "URI/Name version" and matches the - // arguments to qmlRegisterType. Usually types are only exported - // once, if at all. - // If the "URI/" part of the string is missing that means the - // type should be put into the package defined by the URI the - // module was imported with. - // For example if this module was imported with 'import Foo 4.8' - // the Animation object would be found in the package Foo and - // QtQuick. - exports: [ - "Animation 4.7", - "QtQuick/Animation 1.0" - ] - - // The meta object revisions for the exports specified in 'exports'. - // Describes with revisioned properties will be visible in an export. - // The list must have exactly the same length as the 'exports' list. - // For example the 'animations' propery described below will only be - // available through the QtQuick/Animation 1.0 export. - exportMetaObjectRevisions: [0, 1] - - Property { - name: "animations"; - type: "QQuickAbstractAnimation" - // defaults to false, whether this property is read only - isReadonly: true - // defaults to false, whether the type of this property was a pointer in C++ - isPointer: true - // defaults to false: whether the type actually is a QQmlListProperty<type> - isList: true - // defaults to 0: the meta object revision that introduced this property - revision: 1 - } - Property { name: "loops"; type: "int" } - Property { name: "name"; type: "string" } - Property { name: "loopsEnum"; type: "Loops" } - - Enum { - name: "Loops" - values: { - "Infinite": -2, - "OnceOnly": 1 - } - } - - // Signal and Method work the same way. The inner Parameter - // declarations also support the isReadonly, isPointer and isList - // attributes which mean the same as for Property - Method { name: "restart" } - Signal { name: "started"; revision: 2 } - Signal { - name: "runningChanged" - Parameter { type: "bool" } - Parameter { name: "foo"; type: "bool" } - } - } -} -\endqml - */ diff --git a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc index 01e81e7c19..771d520f8a 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc +++ b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc @@ -1,21 +1,36 @@ -QQmlExtensionPlugin is a plugin interface that makes it possible to +\l QQmlEngineExtensionPlugin is a plugin interface that lets you create QML extensions that can be loaded dynamically into QML applications. These extensions allow custom QML types to be made available to the QML engine. To write a QML extension plugin: \list 1 -\li Subclass QQmlExtensionPlugin - \list - \li Use the Q_PLUGIN_METADATA() macro to register the plugin with - the Qt meta object system - \li Override the \l{QQmlExtensionPlugin::}{registerTypes()} method - and call qmlRegisterType() to register the types to be exported - by the plugin - \endlist -\li Write a project file for the plugin -\li Create a \l{Module Definition qmldir Files}{qmldir file} to - describe the plugin +\li Subclass \l QQmlEngineExtensionPlugin and use the Q_PLUGIN_METADATA() macro + to register the plugin with the Qt meta object system. +\li Use the \l QML_ELEMENT and \l QML_NAMED_ELEMENT() macros to declare + QML types. +\li Configure your build file. + + CMake: + \badcode + qt_add_qml_module(<target> + URI <my.import.name> + VERSION 1.0 + QML_FILES <app.qml> + NO_RESOURCE_TARGET_PATH + ) + \endcode + + qmake: + \badcode + CONFIG += qmltypes + QML_IMPORT_NAME = <my.import.name> + QML_IMPORT_MAJOR_VERSION = <version> + \endcode +\li If you're using qmake, create a + \l {Module Definition qmldir Files} {qmldir file} to describe the plugin. + Note that CMake will, by default, automatically generate the + \l {Module Definition qmldir Files} {qmldir file}. \endlist QML extension plugins are for either application-specific or library-like @@ -23,72 +38,27 @@ 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. -\section1 TimeExample QML extension plugin +\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. -Suppose there is a new \c TimeModel C++ class that should be made available -as a new QML type. It provides the current time through \c hour and \c minute -properties. - -\snippet qmlextensionplugins/plugin.cpp 0 -\dots - -To make this type available, we create a plugin class named \c QExampleQmlPlugin -which is a subclass of \l QQmlExtensionPlugin. It overrides the -\l{QQmlExtensionPlugin::}{registerTypes()} method in order to register the \c TimeModel -type using qmlRegisterType(). It also uses the Q_PLUGIN_METADATA() macro in the class -definition to register the plugin with the Qt meta object system using a unique -identifier for the plugin. - -\snippet qmlextensionplugins/plugin.cpp plugin - -This registers the \c TimeModel class with version \c{1.0} of this plugin library, as -a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is -imported correctly by any QML components that use this plugin. The -\l{Defining QML Types from C++} article has more information about registering C++ -types into the runtime. - -\section1 Project settings for the plugin - -Additionally, the project file (\c .pro) defines the project as a plugin library, -specifies it should be built into the \c imports/TimeExample directory, and registers -the plugin target name and various other details: +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 +called "my.module", you would add the forward declaration in global scope: \code -TEMPLATE = lib -CONFIG += qt plugin -QT += qml - -DESTDIR = imports/TimeExample -TARGET = qmlqtimeexampleplugin -SOURCES += qexampleqmlplugin.cpp +void qml_register_types_my_module(); \endcode -\section1 Plugin definition in the qmldir - -Finally, a \l{Module Definition qmldir Files}{qmldir file} is required -in the \c imports/TimeExample directory to describe the plugin and the types that it -exports. The plugin includes a \c Clock.qml file along with the \c qmlqtimeexampleplugin -that is built by the project (as shown above in the \c .pro file) so both of these -need to be specified in the \c qmldir file: +Then add the following snippet of code in the implementation of any function +that's part of the same binary as the registration: -\quotefile qmlextensionplugins/imports/TimeExample/qmldir - -To make things easier for this example, the TimeExample source directory is in -\c{imports/TimeExample}, and we build -\l{Source, Build, and Install Directories}{in-source}. However, the structure -of the source directory is not so important, as the \c qmldir file can specify -paths to installed QML files. - -What is important is the name of the directory that the qmldir is installed -into. When the user imports our module, the QML engine uses the -\l{Contents of a Module Definition qmldir File}{module identifier} -(\c TimeExample) to find the plugin, and so the directory in which it is -installed must match the module identifier. - -Once the project is built and installed, the new \c Time component is -accessible by any QML component that imports the \c TimeExample -module - -\snippet qmlextensionplugins/plugins.qml 0 - -The full source code is available in the \l {qmlextensionplugins}{plugins example}. +\code +volatile auto registration = &qml_register_types_my_module; +Q_UNUSED(registration); +\endcode diff --git a/src/qml/doc/src/qmllanguageref/modules/topic.qdoc b/src/qml/doc/src/qmllanguageref/modules/topic.qdoc index 3462e474c2..449acb3f81 100644 --- a/src/qml/doc/src/qmllanguageref/modules/topic.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/topic.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-modules-topic.html diff --git a/src/qml/doc/src/qmllanguageref/qmlreference.qdoc b/src/qml/doc/src/qmllanguageref/qmlreference.qdoc index 901a4a57fe..7f92129fcf 100644 --- a/src/qml/doc/src/qmllanguageref/qmlreference.qdoc +++ b/src/qml/doc/src/qmllanguageref/qmlreference.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qmlreference.html @@ -38,7 +14,7 @@ In addition, QML heavily uses Qt, which allows types and other Qt features to be accessible directly from QML applications. This reference guide describes the features of the QML language. Many of the -QML types in the guide originate from the \l{Qt QML} or \l{Qt Quick} +QML types in the guide originate from the \l{Qt Qml} or \l{Qt Quick} modules. \list @@ -73,17 +49,20 @@ modules. \li \l{qtqml-javascript-resources.html}{Defining JavaScript Resources In QML} \li \l{qtqml-javascript-imports.html}{Importing JavaScript Resources In QML} \li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} + \li \l{qtqml-javascript-finetuning.html}{Configuring the JavaScript engine} \endlist \li \l{qtqml-typesystem-topic.html}{The QML Type System} \list - \li \l{qtqml-typesystem-basictypes.html}{Basic Types} + \li \l{qtqml-typesystem-valuetypes.html}{QML Value Types} \li \l{qtqml-typesystem-topic.html#javascript-types}{JavaScript Types} \li \l{qtqml-typesystem-objecttypes.html}{QML Object Types} \list \li \l{qtqml-documents-definetypes.html}{Defining Object Types from QML} \li \l{qtqml-cppintegration-definetypes.html}{Defining Object Types from C++} \endlist + \li \l{qtqml-typesystem-sequencetypes.html}{QML Sequence Types} + \li \l{qtqml-typesystem-namespaces.html}{QML Namespaces} \endlist \li \l{qtqml-modules-topic.html}{QML Modules} diff --git a/src/qml/doc/src/qmllanguageref/syntax/basics.qdoc b/src/qml/doc/src/qmllanguageref/syntax/basics.qdoc index 9eb8f72cf2..ce2e48d41a 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/basics.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/basics.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-syntax-basics.html \title QML Syntax Basics @@ -48,7 +24,7 @@ A QML document may have one or more imports at the top of the file. An import can be any one of: \list -\li a versioned namespace into which types have been registered (e.g., by a plugin) +\li a QML Module \li a relative directory which contains type-definitions as QML documents \li a JavaScript file \endlist @@ -57,10 +33,9 @@ JavaScript file imports must be qualified when imported, so that the properties The generic form of the various imports are as follows: \list -\li \tt{import Namespace VersionMajor.VersionMinor} -\li \tt{import Namespace VersionMajor.VersionMinor as SingletonTypeIdentifier} -\li \tt{import "directory"} -\li \tt{import "file.js" as ScriptIdentifier} +\li \tt{import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]} +\li \tt{import "<Directory>"} +\li \tt{import "<JavaScriptFile>" [as <ScriptIdentifier>]} \endlist Examples: diff --git a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc index 7ec8a4ff34..f653ba452b 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-syntax-directoryimports.html \title Importing QML Document Directories @@ -51,6 +27,11 @@ filenames of the QML documents. Only filenames beginning with an uppercase letter and ending with ".qml" will be exposed as types if no \c qmldir file is specified in the directory. +Directory Imports rank below any +\l{qtqml-modules-identifiedmodules.html}{module imports} in precedence. If the +same name is defined in a module and in a directory that are both imported into +the same namespace, only the module's type is made available. + \section2 An Example Consider the following QML project directory structure. Under the top level directory \c myapp, @@ -104,11 +85,30 @@ as an installed module is imported with a unique identifier string rather than a file system path. +\section1 The Implicit Import + +The directory a QML document resides in is automatically imported. You do +not have to explicitly import \c{"."} or similar. + +\note You should make sure that the qmldir file that specifies the module a QML +document belongs to resides in the same directory as the QML document itself. +Otherwise the implicit import is different from the module the document belongs +to. Then, for example, another QML document may be a singleton in the context of +the module, but not a singleton in the context of the implicit import. This is a +frequent source of mistakes. + + \section1 Remotely Located Directories 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 \l{The Implicit Import}{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 57e0ba1a14..c19ac3eeec 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-syntax-imports.html \title Import Statements @@ -36,12 +12,10 @@ resources and component directories are used within a QML document. The types which may be used within a document depends on which modules, resources and directories are imported by the document. -\section2 Import Types - There are three different types of imports. Each import type has a slightly different syntax, and different semantics apply to different import types. -\section3 Module (Namespace) Imports +\section2 Module (Namespace) Imports The most common type of import is a module import. Clients can import \l{qtqml-modules-identifiedmodules.html}{QML modules} which register QML object @@ -49,7 +23,7 @@ types and JavaScript resources into a given namespace. The generic form of a module import is as follows: \code -import <ModuleIdentifier> <Version.Number> [as <Qualifier>] +import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>] \endcode \list @@ -59,7 +33,9 @@ import <ModuleIdentifier> <Version.Number> [as <Qualifier>] \li The \c <Version.Number> is a version of the form \c {MajorVersion.MinorVersion} which specifies which definitions of various object types and JavaScript resources will be made available due - to the import. + to the import. It can be omitted, in which case the latest version of the + module is imported. It is also possible to only omit the minor version. + Then the latest minor version of the given major version is imported. \li The \c <Qualifier> is an optional local namespace identifier into which the object types and JavaScript resources provided by the module will be installed, if given. If omitted, the object types and JavaScript @@ -69,7 +45,7 @@ import <ModuleIdentifier> <Version.Number> [as <Qualifier>] An example of an unqualified module import is as follows: \code -import QtQuick 2.0 +import QtQuick \endcode This import allows the use of all of the types provided by the \c QtQuick @@ -77,7 +53,7 @@ module without needing to specify a qualifier. For example, the client code to create a rectangle is as follows: \qml -import QtQuick 2.0 +import QtQuick Rectangle { width: 200 @@ -86,9 +62,16 @@ Rectangle { } \endqml +An example of an unqualified import with version would be +\code +import QtQuick 2.10 +\endcode +In that case, any types defined in QtQuick 2.11 and higher or in any higher major +version, like 6.0, would not be available to the file. + An example of a qualified module import is as follows: \code -import QtQuick 2.0 as Quick +import QtQuick as Quick \endcode This import allows multiple modules which provide conflicting type names to be @@ -100,7 +83,7 @@ An example of client code which creates a rectangle after using a qualified module import is as follows: \qml -import QtQuick 2.0 as Quick +import QtQuick as Quick Quick.Rectangle { width: 200 @@ -127,17 +110,17 @@ Rectangle { In this case, the engine will emit an error and refuse to load the file. -\section4 Non-module Namespace Imports +\section3 C++ Module Imports -Types can also be registered into namespaces directly via the various -registration functions in C++ (such as qmlRegisterType()). The types which -have been registered into a namespace in this way may be imported by importing -the namespace, as if the namespace was a module identifier. +Usually, C++ types are declared using the QML_ELEMENT and QML_NAMED_ELEMENT() +macros and registered via the build system using QML_IMPORT_NAME and +QML_IMPORT_MAJOR_VERSION. The import name and version given this way form a +module that can be imported to access the types. This is most common in client applications which define their own QML object -types in C++ and register them with the QML type system manually. +types in C++. -\section4 Importing into a Qualified Local Namespace +\section3 Importing into a Qualified Local Namespace The \c import statement may optionally use the \c as keyword to specify that the types should be imported into a particular document-local namespace. If a @@ -149,7 +132,7 @@ references to types from the \c QtQuick module must be prefixed with the \c CoreItems name: \qml -import QtQuick 2.0 as CoreItems +import QtQuick as CoreItems CoreItems.Rectangle { width: 100; height: 100 @@ -171,7 +154,7 @@ two modules can be imported into different namespaces to ensure the code is referring to the correct type: \qml -import QtQuick 2.0 as CoreItems +import QtQuick as CoreItems import "../textwidgets" as MyModule CoreItems.Rectangle { @@ -187,7 +170,7 @@ way that multiple modules can be imported into the global namespace. For example \snippet qml/imports/merged-named-imports.qml imports -\section3 Directory Imports +\section2 Directory Imports A directory which contains QML documents may also be imported directly in a QML document. This provides a simple way for QML types to be segmented into @@ -213,7 +196,7 @@ section about \l{Importing into a Qualified Local Namespace}. For more information about directory imports, please see the in-depth documentation about \l{qtqml-syntax-directoryimports.html}{directory imports}. -\section3 JavaScript Resource Imports +\section2 JavaScript Resource Imports JavaScript resources may be imported directly in a QML document. Every JavaScript resource must have an identifier by which it is accessed. @@ -226,7 +209,7 @@ import "<JavaScriptFile>" as <Identifier> Note that the \c <Identifier> must be unique within a QML document, unlike the local namespace qualifier which can be applied to module imports. -\section4 JavaScript Resources from Modules +\section3 JavaScript Resources from Modules Javascript files can be provided by modules, by adding identifier definitions to the \c qmldir file which specifies the module. @@ -244,8 +227,8 @@ module by importing the module and using the identifier associated with a declared resource: \qml -import QtQuick 2.0 -import projects.MyQMLProject.MyFunctions 1.0 +import QtQuick +import projects.MyQMLProject.MyFunctions Item { Component.onCompleted: { SystemFunctions.cleanUp(); } @@ -257,9 +240,9 @@ resource identifiers must be prefixed with the namespace qualifier in order to be used: \qml -import QtQuick 2.0 -import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs -import org.example.Functions 1.0 as TheirFuncs +import QtQuick +import projects.MyQMLProject.MyFunctions as MyFuncs +import org.example.Functions as TheirFuncs Item { Component.onCompleted: { @@ -269,7 +252,7 @@ Item { } \endqml -\section4 Further Information +\section3 Further Information For more information about JavaScript resources, please see the documentation about \l{qtqml-javascript-resources.html} @@ -289,15 +272,28 @@ default locations to be searched by the engine. By default, this list contains: \list \li The directory of the current file -\li The location specified by QLibraryInfo::Qml2ImportsPath -\li Paths specified by the \c QML2_IMPORT_PATH environment variable +\li The location specified by QLibraryInfo::QmlImportsPath +\li Paths specified by the \c QML_IMPORT_PATH environment variable \li The qrc:/qt-project.org/imports path inside the resources. +\li The qrc:/qt/qml path inside the resources (since Qt 6.5). \endlist Additional import paths can be added through QQmlEngine::addImportPath() or the -\c QML2_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. +\c QML_IMPORT_PATH environment variable. When running the +\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 +is a semicolon (;), on other platforms it is a colon (:). This means that you +cannot specify resource paths or URLs in QML_IMPORT_PATH, as they contain +colons themselves. However, you can add resource paths and URLs by calling +QQmlEngine::addImportPath() programatically. + +\note It is recommended that applications and libraries put their modules +under "qrc:/qt/qml". This happens by default when the module is created +with \l{qt_add_qml_module}{qt_add_qml_module()} and \l{QTP0001} is +enabled. \section1 Debugging diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc index 2bb1fcac61..2b1803042e 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-syntax-objectattributes.html @@ -56,6 +32,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 @@ -73,7 +50,7 @@ by referring to \c myTextInput.text. Now, both items will display the same text: \qml -import QtQuick 2.0 +import QtQuick Column { width: 200; height: 200 @@ -112,7 +89,7 @@ Alternatively, a custom property of an object type may be defined in an object declaration in a QML document with the following syntax: \code - [default] property <propertyType> <propertyName> + [default] [required] [readonly] property <propertyType> <propertyName> \endcode In this way an object declaration may \l {Defining Object Types from QML} @@ -121,10 +98,13 @@ state more easily. Property names must begin with a lower case letter and can only contain letters, numbers and underscores. \l {JavaScript Reserved Words} -{JavaScript reserved words} are not valid property names. The \c default -keyword is optional, and modifies the semantics of the property being declared. -See the upcoming section on \l {Default Properties}{default properties} for -more information about the \c default property modifier. +{JavaScript reserved words} are not valid property names. The \c default, +\c required, and \c readonly keywords are optional, and modify the semantics +of the property being declared. +See the upcoming sections on \l {Default Properties}{default properties}, +\l {Required Properties}{required properties} and, +\l {Read-Only Properties}{read-only properties} for more information +about their respective meaning. Declaring a custom property implicitly creates a value-change \l{Signal attributes}{signal} for that property, as well as an associated @@ -147,7 +127,7 @@ Rectangle { \section4 Valid Types in Custom Property Definitions -Any of the \l {QML Basic Types} aside from the \l enumeration type can be used +Any of the \l {QML Value Types} aside from the \l enumeration type can be used as custom property types. For example, these are all valid property declarations: \qml @@ -161,11 +141,11 @@ Item { (Enumeration values are simply whole number values and can be referred to with the \l int type instead.) -Some basic types are provided by the \c QtQuick module and thus cannot be used -as property types unless the module is imported. See the \l {QML Basic Types} +Some value types are provided by the \c QtQuick module and thus cannot be used +as property types unless the module is imported. See the \l {QML Value Types} documentation for more details. -Note the \l var basic type is a generic placeholder type that can hold any +Note the \l var value type is a generic placeholder type that can hold any type of value, including lists and objects: \code @@ -220,7 +200,7 @@ definition becomes: An example of property value initialization follows: \qml -import QtQuick 2.0 +import QtQuick Rectangle { color: "red" @@ -242,7 +222,7 @@ assignment operator, as shown below: An example of imperative value assignment follows: \qml -import QtQuick 2.0 +import QtQuick Rectangle { id: rect @@ -282,7 +262,7 @@ also known as \l{Property Binding}{property bindings}. Here is an example that shows both kinds of values being assigned to properties: \qml -import QtQuick 2.0 +import QtQuick Rectangle { // both of these are static value assignments on initialization @@ -326,7 +306,7 @@ even though properties of the \c color type store colors and not strings, you are able to assign the string \c "red" to a color property, without an error being reported. -See \l {QML Basic Types} for a list of the types of properties that are +See \l {QML Value Types} for a list of the types of properties that are supported by default. Additionally, any available \l {QML Object Types} {QML object type} may also be used as a property type. @@ -347,7 +327,7 @@ used to hold a list of \l State type objects. The code below initializes the value of this property to a list of three \l State objects: \qml -import QtQuick 2.0 +import QtQuick Item { states: [ @@ -361,7 +341,7 @@ Item { If the list contains a single item, the square brackets may be omitted: \qml -import QtQuick 2.0 +import QtQuick Item { states: State { name: "running" } @@ -372,20 +352,20 @@ A \l list type property may be specified in an object declaration with the following syntax: \code - [default] property list<<objectType>> propertyName + [default] property list<<ObjectType>> propertyName \endcode and, like other property declarations, a property initialization may be combined with the property declaration with the following syntax: \code - [default] property list<<objectType>> propertyName: <value> + [default] property list<<ObjectType>> propertyName: <value> \endcode An example of list property declaration follows: \qml -import QtQuick 2.0 +import QtQuick Rectangle { // declaration without initialization @@ -427,11 +407,10 @@ Text { } \endcode -Grouped property types are basic types which have subproperties. Some of these -basic types are provided by the QML language, while others may only be used if -the Qt Quick module is imported. See the documentation about -\l{QML Basic Types} for more information. - +Grouped property types are types which have subproperties. If a grouped property +type is an object type (as opposed to a value type), the property that holds it +must be read-only. This is to prevent you from replacing the object the +subproperties belong to. \section3 Property Aliases @@ -464,22 +443,24 @@ Unlike an ordinary property, an alias has the following restrictions: must be provided when the alias is first declared. \li It cannot refer to \l {Attached Properties and Attached Signal Handlers} {attached properties}. -\li It cannot refer to grouped properties; the following code will not work: +\li It cannot refer to properties inside a hierarchy with depth 3 or greater. The + following code will not work: \code - property alias color: rectangle.border.color + property alias color: myItem.myRect.border.color - Rectangle { - id: rectangle + Item { + id: myItem + property Rectangle myRect } \endcode - However, aliases to \l {QML Basic Types}{value type} properties do work: + However, aliases to properties that are up to two levels deep will work. + \code - property alias rectX: object.rectProperty.x + property alias color: rectangle.border.color - Item { - id: object - property rect rectProperty + Rectangle { + id: rectangle } \endcode \endlist @@ -489,7 +470,7 @@ which is connected to the \c text object of the \l Text child: \qml // Button.qml -import QtQuick 2.0 +import QtQuick Rectangle { property alias buttonText: textItem.text @@ -517,16 +498,6 @@ the other way around. \section4 Considerations for Property Aliases -Aliases are only activated once a component has been fully initialized. An -error is generated when an uninitialized alias is referenced. Likewise, -aliasing an aliasing property will also result in an error. - -\snippet qml/properties.qml alias complete - -When importing a \l{QML Object Types}{QML object type} with a property alias in -the root object, however, the property appear as a regular Qt property and -consequently can be used in alias references. - It is possible for an aliasing property to have the same name as an existing property, effectively overwriting the existing property. For example, the following QML type has a \c color alias property, named the same as the @@ -540,6 +511,57 @@ Internally, however, the rectangle can correctly set its \c color property and refer to the actual defined property rather than the alias. +\section4 Property Aliases and Types + +Property aliases cannot have explicit type specifications. The type of a +property alias is the \e declared type of the property or object it refers to. +Therefore, if you create an alias to an object referenced via id with extra +properties declared inline, the extra properties won't be accessible through +the alias: + +\qml +// MyItem.qml +Item { + property alias inner: innerItem + + Item { + id: innerItem + property int extraProperty + } +} +\endqml + +You cannot initialize \a inner.extraProperty from outside of this component, as +inner is only an \a Item: + +\qml +// main.qml +MyItem { + inner.extraProperty: 5 // fails +} +\endqml + +However, if you extract the inner object into a separate component with a +dedicated .qml file, you can instantiate that component instead and have all +its properties available through the alias: + +\qml +// MainItem.qml +Item { + // Now you can access inner.extraProperty, as inner is now an ExtraItem + property alias inner: innerItem + + ExtraItem { + id: innerItem + } +} + +// ExtraItem.qml +Item { + property int extraProperty +} +\endqml + \section3 Default Properties An object definition can have a single \e default property. A default property @@ -553,12 +575,12 @@ property \c someText: \qml // MyLabel.qml -import QtQuick 2.0 +import QtQuick Text { default property var someText - text: "Hello, " + someText.text + text: `Hello, ${someText.text}` } \endqml @@ -589,10 +611,73 @@ This is because the default property of \l Item is its \c data property, and any items added to this list for an \l Item are automatically added to its list of \l {Item::children}{children}. -Default properties can be useful for reassigning the children of an item. See -the \l{TabWidget Example}, which uses a default property to -automatically reassign children of the TabWidget as children of an inner -ListView. See also \l {Extending QML}. +Default properties can be useful for reassigning the children of an item. +For example: + +\qml +Item { + default property alias content: inner.children + + Item { + id: inner + } +} +\endqml + +By setting the default property \e alias to \c {inner.children}, any object +assigned as a child of the outer item is automatically reassigned as a child +of the inner item. + +\warning Setting the values of a an element's default list property can be done implicitly or +explicitly. Within a single element's definition, these two methods must not be mixed as that leads +to undefined ordering of the elements in the list. + +\qml +Item { + // Use either implicit or explicit assignement to the default list property but not both! + Rectangle { width: 40 } // implicit + data: [ Rectangle { width: 100 } ] // explicit +} +\endqml + +\section3 Required Properties + +An object declaration may define a property as required, using the \c required +keyword. The syntax is +\code + required property <propertyType> <propertyName> +\endcode + +As the name suggests, required properties must be set when an instance of the object +is created. Violation of this rule will result in QML applications not starting if it can be +detected statically. In case of dynamically instantiated QML components (for instance via +\l {QtQml::Qt::createComponent()}{Qt.createComponent()}), violating this rule results in a +warning and a null return value. + +It's possible to make an existing property required with +\code + required <propertyName> +\endcode +The following example shows how to create a custom Rectangle component, in which the color +property always needs to be specified. +\qml +// ColorRectangle.qml +Rectangle { + required color +} +\endqml + +\note You can't assign an initial value to a required property from QML, as that would go +directly against the intended usage of required properties. + +Required properties play a special role in model-view-delegate code: +If the delegate of a view has required properties whose names match with +the role names of the view's model, then those properties will be initialized +with the model's corresponding values. +For more information, visit the \l{Models and Views in Qt Quick} page. + +See \l{QQmlComponent::createWithInitialProperties}, \l{QQmlApplicationEngine::setInitialProperties} +and \l{QQuickView::setInitialProperties} for ways to initialize required properties from C++. \section3 Read-Only Properties @@ -600,12 +685,12 @@ An object declaration may define a read-only property using the \c readonly keyword, with the following syntax: \code - readonly property <propertyType> <propertyName> : <initialValue> + readonly property <propertyType> <propertyName> : <value> \endcode -Read-only properties must be assigned a value on initialization. After a -read-only property is initialized, it no longer possible to give it a value, -whether from imperative code or otherwise. +Read-only properties must be assigned a static value or a binding expression on +initialization. After a read-only property is initialized, you cannot change +its static value or binding expression anymore. For example, the code in the \c Component.onCompleted block below is invalid: @@ -613,7 +698,7 @@ For example, the code in the \c Component.onCompleted block below is invalid: Item { readonly property int someNumber: 10 - Component.onCompleted: someNumber = 20 // doesn't work, causes an error + Component.onCompleted: someNumber = 20 // TypeError: Cannot assign to read-only property } \endqml @@ -635,6 +720,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. @@ -670,7 +757,7 @@ For example, the \e onClicked signal handler below is declared within the clicked, causing a console message to be printed: \qml -import QtQuick 2.0 +import QtQuick Item { width: 100; height: 100 @@ -692,7 +779,7 @@ signal for an object type may be defined in an object declaration in a QML document with the following syntax: \code - signal <signalName>[([<type> <parameter name>[, ...]])] + signal <signalName>[([<parameterName>: <parameterType>[, ...]])] \endcode Attempting to declare two signals or methods with the same name in the same @@ -703,17 +790,26 @@ may be hidden and become inaccessible.) Here are three examples of signal declarations: \qml -import QtQuick 2.0 +import QtQuick Item { signal clicked signal hovered() - signal actionPerformed(string action, var actionResult) + signal actionPerformed(action: string, actionResult: int) } \endqml +You can also specify signal parameters in property style syntax: + +\qml +signal actionCanceled(string action) +\endqml + +In order to be consistent with method declarations, you should prefer the +type declarations using colons. + If the signal has no parameters, the "()" brackets are optional. If parameters -are used, the parameter types must be declared, as for the \c string and \c var +are used, the parameter types must be declared, as for the \c string and \c int arguments for the \c actionPerformed signal above. The allowed parameter types are the same as those listed under \l {Defining Property Attributes} on this page. @@ -749,7 +845,7 @@ the \c SquareButton.qml file as shown below, with signals \c activated and Rectangle { id: root - signal activated(real xPosition, real yPosition) + signal activated(xPosition: real, yPosition: real) signal deactivated property int side: 100 @@ -757,8 +853,8 @@ Rectangle { MouseArea { anchors.fill: parent - onPressed: root.activated(mouse.x, mouse.y) onReleased: root.deactivated() + onPressed: mouse => root.activated(mouse.x, mouse.y) } } \endqml @@ -770,11 +866,17 @@ provided by the client: \qml // myapplication.qml SquareButton { - onActivated: console.log("Activated at " + xPosition + "," + yPosition) onDeactivated: console.log("Deactivated!") + onActivated: (xPosition, yPosition) => { + console.log(`Activated at ${xPosition}, ${yPosition}`) + } } \endqml +Signal handlers don't have to declare their parameter types because the signal +already specifies them. The arrow function syntax shown above does not support +type annotations. + See the \l {Signal and Handler Event System} for more details on use of signals. @@ -789,12 +891,12 @@ implicitly available through the fact that \l TextInput has a \c onTextChanged signal handler to be called whenever this property changes: \qml -import QtQuick 2.0 +import QtQuick TextInput { text: "Change this!" - onTextChanged: console.log("Text has changed to:", text) + onTextChanged: console.log(`Text has changed to: ${text}`) } \endqml @@ -814,7 +916,7 @@ registering it as a Q_SLOT of the class. Alternatively, a custom method can be added to an object declaration in a QML document with the following syntax: \code - function <functionName>([<parameterName>[, ...]]) { <body> } + function <functionName>([<parameterName>[: <parameterType>][, ...]]) [: <returnType>] { <body> } \endcode Methods can be added to a QML type in order to define standalone, reusable @@ -822,7 +924,8 @@ blocks of JavaScript code. These methods can be invoked either internally or by external objects. Unlike signals, method parameter types do not have to be declared as they -default to the \c var type. +default to the \c var type. You should, however, declare them in order to +help qmlcachegen generate more performant code, and to improve maintainability. Attempting to declare two methods or signals with the same name in the same type block is an error. However, a new method may reuse the name of an existing @@ -833,11 +936,11 @@ Below is a \l Rectangle with a \c calculateHeight() method that is called when assigning the \c height value: \qml -import QtQuick 2.0 +import QtQuick Rectangle { id: rect - function calculateHeight() { + function calculateHeight(): real { return rect.width / 2; } @@ -852,20 +955,20 @@ can then refer to the received \c newX and \c newY parameters to reposition the text: \qml -import QtQuick 2.0 +import QtQuick Item { width: 200; height: 200 MouseArea { anchors.fill: parent - onClicked: label.moveTo(mouse.x, mouse.y) + onClicked: mouse => label.moveTo(mouse.x, mouse.y) } Text { id: label - function moveTo(newX, newY) { + function moveTo(newX: real, newY: real) { label.x = newX; label.y = newY; } @@ -904,7 +1007,7 @@ ListView. This can be used by each individual delegate object to determine whether it is the currently selected item in the view: \qml -import QtQuick 2.0 +import QtQuick ListView { width: 240; height: 320 @@ -928,15 +1031,16 @@ been fully created, its \c Component.onCompleted signal handler will automatically be invoked to populate the model: \qml -import QtQuick 2.0 +import QtQuick ListView { width: 240; height: 320 model: ListModel { id: listModel Component.onCompleted: { - for (var i = 0; i < 10; i++) - listModel.append({"Name": "Item " + i}) + for (let i = 0; i < 10; i++) { + append({ Name: `Item ${i}` }) + } } } delegate: Text { text: index } @@ -961,7 +1065,7 @@ attached properties. This time, the delegate is an \l Item and the colored \l Rectangle is a child of that item: \qml -import QtQuick 2.0 +import QtQuick ListView { width: 240; height: 320 @@ -971,7 +1075,7 @@ ListView { Rectangle { width: 100; height: 30 - color: ListView.isCurrentItem ? "red" : "yellow" // WRONG! This won't work. + color: ListView.isCurrentItem ? "red" : "yellow" // WRONG! This won't work. } } } @@ -986,14 +1090,13 @@ it cannot access the \c isCurrentItem attached property as \qml ListView { - //.... delegate: Item { id: delegateItem width: 100; height: 30 Rectangle { width: 100; height: 30 - color: delegateItem.ListView.isCurrentItem ? "red" : "yellow" // correct + color: delegateItem.ListView.isCurrentItem ? "red" : "yellow" // correct } } } @@ -1030,12 +1133,12 @@ Text { property int textType: MyText.TextType.Normal - font.bold: textType == MyText.TextType.Heading - font.pixelSize: textType == MyText.TextType.Heading ? 24 : 12 + font.bold: textType === MyText.TextType.Heading + font.pixelSize: textType === MyText.TextType.Heading ? 24 : 12 } \endqml -More information on enumeration usage in QML can be found in the \l {QML Basic Types} \l enumeration documentation. +More information on enumeration usage in QML can be found in the \l {QML Value Types} \l enumeration documentation. The ability to declare enumerations in QML was introduced in Qt 5.10. diff --git a/src/qml/doc/src/qmllanguageref/syntax/propertybinding.qdoc b/src/qml/doc/src/qmllanguageref/syntax/propertybinding.qdoc index a5ad6af4a2..65e3b95f8e 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/propertybinding.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/propertybinding.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-syntax-propertybinding.html @@ -128,6 +104,9 @@ loops - it could indicate that the binding is being used for more than describin property relationships. Complex bindings can reduce code performance, readability, and maintainability. It may be a good idea to redesign components that have complex bindings, or at least factor the binding out into a separate function. +As a general rule, users should not rely on the evaluation order of bindings. + +\sa {Positioning with Anchors} \target qml-javascript-assignment diff --git a/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc index cd73ccc025..b40181b49c 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-syntax-signals.html @@ -59,9 +35,9 @@ receiving this signal should be \c onClicked. In the example below, whenever the button is clicked, the \c onClicked handler is invoked, applying a random color to the parent \l Rectangle: -\qml \QtMinorVersion -import QtQuick 2.\1 -import QtQuick.Controls 2.\1 +\qml +import QtQuick +import QtQuick.Controls Rectangle { id: rect @@ -78,6 +54,13 @@ Rectangle { } \endqml +\note Even though signal handlers look a bit like JavaScript functions, you + should not call them directly. If you need to share code between signal + handlers and other functionality, refactor it into a separate function. + Otherwise always emit the signal if you want the signal handler to be + called. There can be multiple handlers, in different scopes, for the + same signal. + \section2 Property change signal handlers A signal is automatically emitted when the value of a QML property changes. @@ -85,10 +68,12 @@ This type of signal is a \e {property change signal} and signal handlers for these signals are written in the form \e on<Property>Changed, where \e <Property> is the name of the property, with the first letter capitalized. -For example, the \l MouseArea type has a \l {MouseArea::pressed}{pressed} property. To receive a notification whenever this property changes, write a signal handler named \c onPressedChanged: +For example, the \l MouseArea type has a \l {MouseArea::pressed}{pressed} property. +To receive a notification whenever this property changes, write a signal handler +named \c onPressedChanged: -\qml \QtMinorVersion -import QtQuick 2.\1 +\qml +import QtQuick Rectangle { id: rect @@ -104,6 +89,56 @@ Even though the \l TapHandler documentation does not document a signal handler named \c onPressedChanged, the signal is implicitly provided by the fact that the \c pressed property exists. +\section2 Signal parameters + +Signals might have parameters. To access those, you should assign a function to the handler. Both +arrow functions and anonymous functions work. + +For the following examples, consider a Status component with an errorOccurred signal (see +\l{Adding signals to custom QML types} for more information about how signals can be added to +QML components). + +\qml +// Status.qml +import QtQuick + +Item { + id: myitem + + signal errorOccurred(message: string, line: int, column: int) +} +\endqml + +\qml +Status { + onErrorOccurred: (mgs, line, col) => console.log(`${line}:${col}: ${msg}`) +} +\endqml + +\note The names of the formal parameters in the function do not have to match those in the +signal. + +If you do not need to handle all parameters, it is possible to omit trailing ones: +\qml +Status { + onErrorOccurred: message => console.log(message) +} +\endqml + +It is not possible to leave out leading parameters you are interested in, however you can use some +placeholder name to indicate to readers that they are not important: +\qml +Status { + onErrorOccurred: (_, _, col) => console.log(`Error happened at column ${col}`) +} +\endqml + +\note Instead of using a function, it is possible, but discouraged, to use a plain code block. In +that case all signal parameters get injected into the scope of the block. However, this can make +code difficult to read as it's unclear where the parameters come from, and results in slower +lookups in the QML engine. Injecting parameters in this way is deprecated, and will cause runtime +warnings if the parameter is actually used. + \section2 Using the Connections type In some cases it may be desirable to access a signal outside of the object that @@ -116,9 +151,9 @@ received by the root \l Rectangle instead, by placing the \c onClicked handler in a \l Connections object that has its \l {Connections::target}{target} set to the \c button: -\qml \QtMinorVersion -import QtQuick 2.\1 -import QtQuick.Controls 2.\1 +\qml +import QtQuick +import QtQuick.Controls Rectangle { id: rect @@ -133,7 +168,7 @@ Rectangle { Connections { target: button - onClicked: { + function onClicked() { rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1); } } @@ -151,8 +186,8 @@ For example, \l{Component::completed}{Component.onCompleted} is an attached signal handler. It is often used to execute some JavaScript code when its creation process is complete. Here is an example: -\qml \QtMinorVersion -import QtQuick 2.\1 +\qml +import QtQuick Rectangle { width: 200; height: 200 @@ -195,9 +230,9 @@ root \l Rectangle object has an \c activated signal, which is emitted whenever t child \l TapHandler is \c tapped. In this particular example the activated signal is emitted with the x and y coordinates of the mouse click: -\qml \QtMinorVersion +\qml // SquareButton.qml -import QtQuick 2.\1 +import QtQuick Rectangle { id: root @@ -209,8 +244,8 @@ Rectangle { TapHandler { id: handler - onTapped: root.activated(mouseXY.x, mouseXY.y) - onPressedChanged: mouseXY = handler.point.position + onTapped: root.activated(root.mouseXY.x, root.mouseXY.y) + onPressedChanged: root.mouseXY = handler.point.position } } \endqml @@ -220,7 +255,7 @@ Now any objects of the \c SquareButton can connect to the \c activated signal us \qml // myapplication.qml SquareButton { - onActivated: console.log("Activated at " + xPosition + "," + yPosition) + onActivated: (xPosition, yPosition) => console.log(`Activated at {xPosition}, ${yPosition}`) } \endqml @@ -237,8 +272,8 @@ signal to be received by a method instead of a signal handler. Below, the \c messageReceived signal is connected to three methods using the \c connect() method: -\qml \QtMinorVersion -import QtQuick 2.\1 +\qml +import QtQuick Rectangle { id: relay @@ -252,14 +287,14 @@ Rectangle { relay.messageReceived("Tom", "Happy Birthday") } - function sendToPost(person, notice) { - console.log("Sending to post: " + person + ", " + notice) + function sendToPost(person: string, notice: string) { + console.log(`Sending to post: ${person}, ${notice}`) } - function sendToTelegraph(person, notice) { - console.log("Sending to telegraph: " + person + ", " + notice) + function sendToTelegraph(person: string, notice: string) { + console.log(`Sending to telegraph: ${person}, ${notice}`) } - function sendToEmail(person, notice) { - console.log("Sending to email: " + person + ", " + notice) + function sendToEmail(person: string, notice: string) { + console.log(`Sending to email: ${person}, ${notice}`) } } \endqml @@ -289,8 +324,8 @@ Rectangle { By connecting signals to other signals, the \c connect() method can form different signal chains. -\qml \QtMinorVersion -import QtQuick 2.\1 +\qml +import QtQuick Rectangle { id: forwarder @@ -320,4 +355,65 @@ output: MouseArea clicked Send clicked \endcode -*/ + +\note Connections to function objects will stay alive as long as the sender of the signal is alive. +This behavior is analogous to the 3-argument version of QObject::connect() in C++. + +\qml +Window { + visible: true + width: 400 + height: 400 + + Item { + id: item + property color globalColor: "red" + + Button { + text: "Change global color" + onPressed: { + item.globalColor = item.globalColor === Qt.color("red") ? "green" : "red" + } + } + + Button { + x: 150 + text: "Clear rectangles" + onPressed: repeater.model = 0 + } + + Repeater { + id: repeater + model: 5 + Rectangle { + id: rect + color: "red" + width: 50 + height: 50 + x: (width + 2) * index + 2 + y: 100 + Component.onCompleted: { + if (index % 2 === 0) { + item.globalColorChanged.connect(() => { + color = item.globalColor + }) + } + } + } + } + } +} +\endqml + +In the contrived example above, the goal is to flip the color of every even rectangle to follow +some global color. To achieve this, for every even rectangle, a connection is made between the +globalColorChanged signal and a function to set the rectangle's color. This works as expected while +the rectangles are alive. However, once the clear button is pressed, the rectangles are gone but +the function handling the signal is still called every time the signal is emitted. This can be +seen by the error messages thrown by the function trying to run in the background when changing +the global color. + +In the current setup, the connections would only be destroyed once the item holding +globalColor is destroyed. To prevent the connections from lingering on, they can be explicitly +disconnected when the rectangles are being destroyed. + */ diff --git a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc index 5144fe219e..e0929f2879 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc @@ -1,681 +1,10 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-typesystem-basictypes.html \title QML Basic Types -\brief Description of basic types provided by the Qt QML module +\keyword QML Basic Types +\brief QML Value Types used to be called "Basic Types" -QML supports a number of basic types. - -A \e{basic type} is one that refers to a simple value, such as an \c int -or a \c string. This contrasts with a \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types}, -which refers to an object with properties, signals, methods and so on. Unlike an object type, -a basic type cannot be used to declare QML objects: it is not possible, for example, to declare an -\c int{} object or a \c size{} object. - -Basic types can be used to refer to: - -\list -\li A single value (e.g. \l int refers to a single number, \l var can refer to a single list of items) -\li A value that contains a simple set of property-value pairs (e.g. \l size refers to a value with \c width and \c height attributes) -\endlist - -When a variable or property holds a basic type and it is assigned to another -variable or property, then a copy of the value is made. In JavaScript, this -value is called a primitive value. - -\sa {qtqml-typesystem-topic.html}{The QML Type System} - - -\section1 Supported Basic Types - -Some basic types are supported by the engine by default and do not require an -\l {Import Statements}{import statement} to be used, while others do require -the client to import the module which provides them. -All of the basic types listed below may be used as a \c property type in a QML -document, with the following exceptions: -\list - \li \c list must be used in conjunction with a QML object type - \li \c enumeration cannot be used directly as the enumeration must be defined by a registered QML object type -\endlist - -\section2 Basic Types Provided By The QML Language - -The basic types supported natively in the QML language are listed below: -\annotatedlist qmlbasictypes - -\section2 Basic Types Provided By QML Modules - -QML modules may extend the QML language with more basic types. -For example, the basic types provided by the \c QtQuick module are listed below: -\annotatedlist qtquickbasictypes - -The \l{QtQml::Qt}{Qt} global object provides useful functions for manipulating values of basic types. - -Currently only QML modules which are provided by Qt may provide their -own basic types, however this may change in future releases of Qt QML. -In order to use types provided by a particular QML module, clients -must import that module in their QML documents. - -\section1 Property Change Behavior for Basic Types - -Some basic types have properties: for example, the \l font type has -\c pixelSize, \c family and \c bold properties. Unlike properties of -\l{qtqml-typesystem-topic.html#qml-object-types}{object types}, properties of -basic types do not provide their own property change signals. It is only possible -to create a property change signal handler for the basic type property itself: - -\code -Text { - // invalid! - onFont.pixelSizeChanged: doSomething() - - // also invalid! - font { - onPixelSizeChanged: doSomething() - } - - // but this is ok - onFontChanged: doSomething() -} -\endcode - -Be aware, however, that a property change signal for a basic type is emitted -whenever \e any of its attributes have changed, as well as when the property itself -changes. Take the following code, for example: - -\qml -Text { - onFontChanged: console.log("font changed") - - Text { id: otherText } - - focus: true - - // changing any of the font attributes, or reassigning the property - // to a different font value, will invoke the onFontChanged handler - Keys.onDigit1Pressed: font.pixelSize += 1 - Keys.onDigit2Pressed: font.b = !font.b - Keys.onDigit3Pressed: font = otherText.font -} -\endqml - -In contrast, properties of an \l{qtqml-typesystem-topic.html#qml-object-types}{object type} -emit their own property change signals, and a property change signal handler for an object-type -property is only invoked when the property is reassigned to a different object value. - -*/ - -/*! - \qmlbasictype int - \ingroup qmlbasictypes - \brief a whole number, e.g. 0, 10, or -20. - - The \c int type refers to a whole number, e.g. 0, 10, or -20. - - The possible \c int values range from around -2000000000 to around 2000000000, - although most types will only accept a reduced range (which they - mention in their documentation). - - Example: - \qml - Item { width: 100; height: 200 } - \endqml - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype bool - \ingroup qmlbasictypes - \brief a binary true/false value. - - The \c bool type refers to a binary true/false value. - - Example: - \qml - Item { - focus: true - clip: false - } - \endqml - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype real - \ingroup qmlbasictypes - - \brief a number with a decimal point. - - The \c real type refers to a number with decimal point, e.g. 1.2 or -29.8. - - Example: - \qml - Item { width: 100.45; height: 150.82 } - \endqml - - \b{Note:} In QML all reals are stored in double precision, \l - {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} - format. - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype double - \ingroup qmlbasictypes - - \brief a number with a decimal point, stored in double precision. - - The \c double type refers to a number with a decimal point and is stored in double precision, \l - {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format. - - Example: - \qml - Item { - property double number: 32155.2355 - } - \endqml - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype string - \ingroup qmlbasictypes - \brief a free form text string. - - The \c string type refers to a free form text string in quotes, e.g. "Hello world!". - - Example: - \qml - Text { text: "Hello world!" } - \endqml - - Strings have a \c length attribute that holds the number of - characters in the string. - - QML extends the JavaScript String type with a \l {String::arg}{arg()} function - to support value substitution. - - When integrating with C++, note that any QString value - \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically - converted into a \c string value, and vice-versa. - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype url - \ingroup qmlbasictypes - \brief a resource locator. - - The \c url type refers to a resource locator (like a file name, for example). It can be either - absolute, e.g. "http://qt-project.org", or relative, e.g. "pics/logo.png". A relative URL is - resolved relative to the URL of the containing component. - - For example, the following assigns a valid URL to the \l {Image::source} - property, which is of type \c url: - - \qml - Image { source: "pics/logo.png" } - \endqml - - When integrating with C++, note that any QUrl value - \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically - converted into a \c url value, and vice-versa. - - - \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 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 - will be preserved within properties of type \c url, to allow QML code to - construct precise URL values. An exception to this rule is the preemptive - decoding of directory-separator characters (\c '/') - these characters are decoded - to allow the URL to be correctly classified. - - For example, a local file containing a '#' character, which would normally be - interpreted as the beginning of the URL 'fragment' element, can be accessed by - encoding the characters of the file name: - - \qml - Image { source: encodeURIComponent("/tmp/test#1.png") } - \endqml - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - - -/*! - \qmlbasictype list - \ingroup qmlbasictypes - \brief a list of QML objects. - - The \c list type refers to a list of QML objects. - - A list value can be accessed in a similar way to a JavaScript array: - - \list - \li Values are assigned using the \c[] square bracket syntax with comma-separated values - \li The \c length property provides the number of items in the list - \li Values in the list are accessed using the \c [index] syntax - \endlist - - Values can be dynamically added to the list by using the \c push method, - as if it were a JavaScript Array - - A \c list can only store QML objects, and cannot contain any - \l {QML Basic Types}{basic type} values. (To store basic types within a - list, use the \l var type instead.) - - When integrating with C++, note that any QQmlListProperty value - \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically - converted into a \c list value, and vice-versa. - - - \section1 Using the list Type - - For example, the \l Item type has a \l {Item::}{states} list-type property that - can be assigned to and used as follows: - - \qml - import QtQuick 2.0 - - Item { - width: 100; height: 100 - - states: [ - State { name: "activated" }, - State { name: "deactivated" } - ] - - Component.onCompleted: { - console.log("Name of first state:", states[0].name) - for (var i = 0; i < states.length; i++) - console.log("state", i, states[i].name) - } - } - \endqml - - The defined \l State objects will be added to the \c states list - in the order in which they are defined. - - If the list only contains one object, the square brackets may be omitted: - - \qml - import QtQuick 2.0 - - Item { - width: 100; height: 100 - states: State { name: "activated" } - } - \endqml - - Note that objects cannot be individually added to or removed from - the list once created; to modify the contents of a list, it must be - reassigned to a new list. - - \note The \c list type is not recommended as a type for custom properties. - The \c var type should be used instead for this purpose as - lists stored by the \c var type can be manipulated with greater - flexibility from within QML. - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - - /*! - \qmlbasictype var - \ingroup qmlbasictypes - \brief a generic property type. - - The \c var type is a generic property type that can refer to any data type. - - It is equivalent to a regular JavaScript variable. - For example, var properties can store numbers, strings, objects, - arrays and functions: - - \qml - Item { - property var aNumber: 100 - property var aBool: false - property var aString: "Hello world!" - property var anotherString: String("#FF008800") - property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5) - property var aRect: Qt.rect(10, 10, 10, 10) - property var aPoint: Qt.point(10, 10) - property var aSize: Qt.size(10, 10) - property var aVector3d: Qt.vector3d(100, 100, 100) - property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })] - property var anObject: { "foo": 10, "bar": 20 } - property var aFunction: (function() { return "one"; }) - } - \endqml - - \section1 Change Notification Semantics - - It is important to note that changes in regular properties of JavaScript - objects assigned to a var property will \b{not} trigger updates of bindings - that access them. The example below will display "The car has 4 wheels" as - the change to the wheels property will not cause the reevaluation of the - binding assigned to the "text" property: - - \qml - Item { - property var car: new Object({wheels: 4}) - - Text { - text: "The car has " + car.wheels + " wheels"; - } - - Component.onCompleted: { - car.wheels = 6; - } - } - \endqml - - If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"} - then the text would be updated to say "The car has 6 wheels", since the - car property itself would be changed, which causes a change notification - to be emitted. - - \section1 Property Value Initialization Semantics - - The QML syntax defines that curly braces on the right-hand-side of a - property value initialization assignment denote a binding assignment. - This can be confusing when initializing a \c var property, as empty curly - braces in JavaScript can denote either an expression block or an empty - object declaration. If you wish to initialize a \c var property to an - empty object value, you should wrap the curly braces in parentheses. - - For example: - \qml - Item { - property var first: {} // nothing = undefined - property var second: {{}} // empty expression block = undefined - property var third: ({}) // empty object - } - \endqml - - In the previous example, the \c first property is bound to an empty - expression, whose result is undefined. The \c second property is bound to - an expression which contains a single, empty expression block ("{}"), which - similarly has an undefined result. The \c third property is bound to an - expression which is evaluated as an empty object declaration, and thus the - property will be initialized with that empty object value. - - Similarly, a colon in JavaScript can be either an object property value - assignment, or a code label. Thus, initializing a var property with an - object declaration can also require parentheses: - - \qml - Item { - property var first: { example: 'true' } // example is interpreted as a label - property var second: ({ example: 'true' }) // example is interpreted as a property - property var third: { 'example': 'true' } // example is interpreted as a property - Component.onCompleted: { - console.log(first.example) // prints 'undefined', as "first" was assigned a string - console.log(second.example) // prints 'true' - console.log(third.example) // prints 'true' - } - } - \endqml - - \sa {QML Basic Types} -*/ -/* - TODO Qt 5.1: see explanation in expressions.qdoc - \section1 Using Scarce Resources with the var Type - - A \c var type property can also hold an image or pixmap. - A \c var which contains a QPixmap or QImage is known as a - "scarce resource" and the declarative engine will attempt to - automatically release such resources after evaluation of any JavaScript - expression which requires one to be copied has completed. - - Clients may explicitly release such a scarce resource by calling the - "destroy" method on the \c var property from within JavaScript. They - may also explicitly preserve the scarce resource by calling the - "preserve" method on the \c var property from within JavaScript. - - This basic type is provided by the QML language. -*/ - -/*! - \obsolete - \qmlbasictype variant - \ingroup qmlbasictypes - \brief a generic property type. - - The \c variant type is a generic property type. It is obsolete and exists only to - support old applications; new applications should use \l var type - properties instead. - - A variant type property can hold any of the \l {QML Basic Types}{basic type} - values: - - \qml - Item { - property variant aNumber: 100 - property variant aString: "Hello world!" - property variant aBool: false - } - \endqml - - When integrating with C++, note that any QVariant value - \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically - converted into a \c variant value, and vice-versa. - - - \section1 Using Scarce Resources with the variant Type - - A \c variant type property can also hold an image or pixmap. - A \c variant which contains a QPixmap or QImage is known as a - "scarce resource" and the declarative engine will attempt to - automatically release such resources after evaluation of any JavaScript - expression which requires one to be copied has completed. - - Clients may explicitly release such a scarce resource by calling the - "destroy" method on the \c variant property from within JavaScript. They - may also explicitly preserve the scarce resource by calling the - "preserve" method on the \c variant property from within JavaScript. - - \section1 Storing Arrays and Objects - - The \c variant type can also hold: - - \list - \li An array of \l {QML Basic Types}{basic type} values - \li A map of key-value pairs with \l {QML Basic Types}{basic-type} values - \endlist - - For example, below is an \c items array and an \c attributes map. Their - contents can be examined using JavaScript \c for loops. Individual array - values are accessible by index, and individual map values are accessible - by key: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - for (var i = 0; i < items.length; i++) - console.log(items[i]) - - for (var prop in attributes) - console.log(prop, "=", attributes[prop]) - } - } - \endqml - - While this is a convenient way to store array and map-type values, you - must be aware that the \c items and \c attributes properties above are \e not - QML objects (and certainly not JavaScript object either) and the key-value - pairs in \c attributes are \e not QML properties. Rather, the \c items - property holds an array of values, and \c attributes holds a set of key-value - pairs. Since they are stored as a set of values, instead of as an object, - their contents \e cannot be modified individually: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - items[0] = 10 - console.log(items[0]) // This will still be '1'! - attributes.color = 'blue' - console.log(attributes.color) // This will still be 'red'! - } - } - \endqml - - Since it is not possible to individually add or remove items from a list or - object stored in a \c variant, the only way to modify its contents is to - reassign a new value. However, this is not efficient, as it causes the value - to be serialized and deserialized. - - Additionally, since \c items and \c attributes are not QML objects, changing - their individual values do not trigger property change notifications. If - the above example had \c onNumberChanged or \c onAnimalChanged signal - handlers, they would not have been called. If, however, the \c items or - \c attributes properties themselves were reassigned to different values, then - such handlers would be called. - - JavaScript programmers should also note that when a JavaScript object is - copied to an array or map property, the \e contents of the object (that is, - its key-value properties) are copied, rather than the object itself. The - property does not hold a reference to the original JavaScript object, and - extra data such as the object's JavaScript prototype chain is also lost in - the process. - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype enumeration - \ingroup qmlbasictypes - \brief a named enumeration value. - - The \c enumeration type refers to a named enumeration value. - - Each named value can be referred to as \c {<Type>.<value>}. For - example, the \l Text type has an \c AlignRight enumeration value: - - \qml - Text { horizontalAlignment: Text.AlignRight } - \endqml - - (For backwards compatibility, the enumeration value may also be - specified as a string, e.g. "AlignRight". This form is not - recommended for new code.) - - When integrating with C++, note that any \c enum value - \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically - converted into an \c enumeration value, and vice-versa. - - This basic type is provided by the QML language. Some enumeration values - are provided by the QtQuick import. - - \section1 Using the enumeration Type in QML - - The \c enumeration type is a representation of a C++ \c enum type. It is - not possible to refer to the \c enumeration type in QML itself; instead, the - \l int or \l var types can be used when referring to \c enumeration values - from QML code. - - For example: - - \qml - import QtQuick 2.0 - - Item { - // refer to Text.AlignRight using an int type - property int enumValue: textItem.horizontalAlignment - - signal valueEmitted(int someValue) - - Text { - id: textItem - horizontalAlignment: Text.AlignRight - } - - // emit valueEmitted() signal, which expects an int, with Text.AlignRight - Component.onCompleted: valueEmitted(Text.AlignRight) - } - \endqml - - \sa {QML Basic Types} - \sa {qtqml-syntax-objectattributes.html#enumeration-attributes}{Enumeration Attributes} +See \l{qtqml-typesystem-valuetypes.html} for the documentation of QML value types. */ diff --git a/src/qml/doc/src/qmllanguageref/typesystem/namespaces.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/namespaces.qdoc new file mode 100644 index 0000000000..0635dbd026 --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/typesystem/namespaces.qdoc @@ -0,0 +1,16 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! +\page qtqml-typesystem-namespaces.html +\title QML Namespaces +\brief Description of QML Namespaces + +A QML Namespace is a special kind of type that only exposes enumerations and cannot +be instantiated. A namespace can only be declared in C++, using the \l QML_ELEMENT or +\l QML_NAMED_ELEMENT macro inside a C++ namespace marked with \l{Q_NAMESPACE}. + +QML namespaces can be used to +\l{qtqml-cppintegration-definetypes.html#value-types-with-enumerations}{extract enumerations} +from other types. + +*/ diff --git a/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc index 5f089b5ebc..d4b09ab180 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-typesystem-objecttypes.html \title QML Object Types @@ -34,7 +10,7 @@ A QML object type is a type from which a QML object can be instantiated. In syntactic terms, a QML object type is one which can be used to declare an object by specifying the \e{type name} followed by a set of curly braces that -encompasses the attributes of that object. This differs from \e {basic types}, +encompasses the attributes of that object. This differs from \e {value types}, which cannot be used in the same way. For example, \l Rectangle is a QML object type: it can be used to create \c Rectangle type objects. This cannot be done with primitive types such as \c int and \c bool, which are used to hold simple @@ -48,6 +24,9 @@ and registering the type with the QML engine, as discussed in Note that in both cases, the type name must begin with an uppercase letter in order to be declared as a QML object type in a QML file. +For more information about C++ and the different QML integration methods, +see the +\l {Overview - QML and C++ Integration} {C++ and QML integration overview} page. \section1 Defining Object Types from QML @@ -119,7 +98,7 @@ See \l{qtqml-documents-scope.html}{Scope and Naming Resolution} for more details \section1 Defining Object Types from C++ C++ plugin writers and application developers may register types defined in C++ -through API provided by the Qt QML module. There are various registration +through API provided by the Qt Qml module. There are various registration functions which each allow different use-cases to be fulfilled. For more information about those registration functions, and the specifics of exposing custom C++ types to QML, see the documentation regarding diff --git a/src/qml/doc/src/qmllanguageref/typesystem/references.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/references.qdoc new file mode 100644 index 0000000000..5326759638 --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/typesystem/references.qdoc @@ -0,0 +1,53 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! +\page qtqml-typesystem-references.html +\title QML Value Type and Sequence References +\brief Description of QML value type and sequence references + +\l{QML Value Types} and \l{QML Sequence Types} are necessarily passed by value. +In contrast to \l{QML Object Types} they have no identity of themselves, but can +only be accessed as properties of other objects or values, or as values returned +from methods. Each such access implicitly creates a copy. Yet, in JavaScript +everything is an object. There is no such concept as a value type in JavaScript. +For example, if you execute \c{font.bold = true} in JavaScript, we expect the \c bold +property of \c font to be set, no matter what \c font is. But consider the following +code snippet: + +\qml +import QtQuick +Text { + onSomethingHappened: font.bold = true +} +\endqml + +In this case we know that \c font is a value type. Accessing it creates a local copy +by calling the getter of a \l{Q_PROPERTY}. We can then set the \c bold property on it, +but that would usually only affect the copy, not the original \l{Q_PROPERTY}. + +To overcome this problem, QML offers the concept of references. When you retrieve +an instance of a value or sequence type from a property, the QML engine remembers +the property along with the value itself. If the value is modified, it is written +back to the property. This produces the illusion of an object with separate identity +and makes the above case, along with many others, just work. + +This can be rather expensive, though. If a sequence is exposed as a Q_PROPERTY, +accessing any value in the sequence by index will cause the whole sequence data +to be read from the property. From this sequence data, a single element is then +retrieved. Similarly, modifying any value in the sequence causes the +sequence data to be read. Then the modification is performed and the modified +sequence is be written back to the property. A read operation can be relatively +cheap if the type in question is implicitly shared. A modification always incurs +at least one deep copy. + +If you return an instance of a sequence or value type from a \l Q_INVOKABLE function +you avoid such overhead. Return values are not attached to any property and won't be +written back. + +Sequences of object types are passed as \l{QQmlListProperty} by default. +\l{QQmlListProperty} is not an actual container, but only a view, or reference, to +some sequential storage. Therefore, \{QQmlListProperty} is not affected by this +effect. You can, however, register other sequence types for objects using +\l{QML_SEQUENTIAL_CONTAINER}. Those will be affected. + +*/ diff --git a/src/qml/doc/src/qmllanguageref/typesystem/sequencetypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/sequencetypes.qdoc new file mode 100644 index 0000000000..ca10f8c23b --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/typesystem/sequencetypes.qdoc @@ -0,0 +1,76 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! +\page qtqml-typesystem-sequencetypes.html +\title QML Sequence Types +\brief Description of QML sequence types + +For every \l{qtqml-typesystem-objecttypes.html}{object type} and +\l{qtqml-typesystem-valuetypes.html}{value type} a sequence type for storing +multiple instances of the type is automatically made available. You can use +the \c list keyword to create properties of sequence types: + +\qml +import QtQml + +QtObject { + property list<int> ints: [1, 2, 3, 4] + property list<Connection> connections: [ + Connection { + // ... + }, + Connection { + // ... + } + ] +} +\endqml + +Sequences of value types are implemented as \l{QList} and sequences of object +types are implemented as \l{QQmlListProperty}. + +Sequences in QML generally behave like the JavaScript \c Array type, with some +important differences which result from the use of a C++ storage type in the +implementation: + +\list 1 +\li Deleting an element from a sequence will result in a default-constructed + value replacing that element, rather than an \c undefined value. +\li Setting the \c length property of a sequence to a value larger + than its current value will result in the sequence being padded out to the + specified length with default-constructed elements rather than \c undefined + elements. +\li The Qt container classes support signed (rather than + unsigned) integer indexes; thus, attempting to access any index greater + than the maximum number \l qsizetype can hold will fail. +\endlist + +If you wish to remove elements from a sequence rather than simply replace +them with default constructed values, do not use the indexed delete operator +(\c{delete sequence[i]}) but instead use the \c {splice} function +(\c{sequence.splice(startIndex, deleteCount)}). + +In general any container recognizable by \l QMetaSequence can be passed from +C++ to QML via \l Q_PROPERTY or \l Q_INVOKABLE methods. This includes, but is +not limited to, all registered QList, QQueue, QStack, QSet, std::list, +std::vector that contain a type marked with \l Q_DECLARE_METATYPE. + +Using a sequence via \l QMetaSequence results in expensive data conversions. +To avoid the conversions you can register your own anonymous sequence types +using \l{QML_SEQUENTIAL_CONTAINER} from C++. Types registered this way behave +like the pre-defined sequence types and are stored as-is. However, they have +no QML names. + +\warning Sequences stored as a C++ container like \l QList or \c std::vector are +subject to the effects caused by \l{QML Value Type and Sequence References} and +should thus be handled with care. \l QQmlListProperty is not affected since +it is only a view for an underlying container. C++ standard containers such as +\c std::vector are not implicitly shared. Therefore, copying them always +produces a deep copy. Since a sequence read from a property always has to be +copied at least once, using such containers as QML sequences is rather +expensive, even if you don't modify them from QML. + +The QtQml module contains a few \l [QML] {QtQml#Sequence Types}{sequence types} +you may want to use. + +*/ diff --git a/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc index a5f730e8d4..b1c5bce891 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-typesystem-topic.html \title The QML Type System @@ -46,15 +22,44 @@ Wherever the type definitions come from, the engine will enforce type-safety for properties and instances of those types. -\section1 Basic Types +\section1 QML Value Types The QML language has built-in support for various primitive types including integers, double-precision floating point numbers, strings, and boolean values. Objects may have properties of these types, and values of these types may be passed as arguments to methods of objects. -See the \l{qtqml-typesystem-basictypes.html}{QML Basic Types} documentation for -more information about basic types. +See the \l{qtqml-typesystem-valuetypes.html}{QML Value Types} documentation for +more information about value types. + +\section1 QML Object Types + +A QML object type is a type from which a QML object can be instantiated. QML +object types are derived from \l QtObject, and are provided by QML modules. +Applications can import these modules to use the object types they provide. +The \c QtQuick module provides the most common object types needed to create +user interfaces in QML. + +Finally, every QML document implicitly defines a QML object type, which can be +re-used in other QML documents. See the documentation about +\l{qtqml-typesystem-objecttypes.html}{object types in the QML type system} for +in-depth information about object types. + +\section1 QML Sequence Types + +Sequence types can be used to store sequences of values or objects. + +See the documentation about +\l{qtqml-typesystem-sequencetypes.html}{sequence types in the QML type system} +for in-depth information about sequence types. + +\section1 QML Namespaces + +QML Namespaces can be used to expose enumerations from C++ namespaces. + +See the documentation about +\l{qtqml-typesystem-namespaces.html}{namespaces in the QML type system} +for in-depth information about namespaces. \section1 JavaScript Types @@ -64,7 +69,7 @@ JavaScript type can be created and stored using the generic \l var type. For example, the standard \c Date and \c Array types are available, as below: \qml -import QtQuick 2.0 +import QtQuick Item { property var theArray: [] @@ -82,17 +87,4 @@ Item { See \l {qtqml-javascript-expressions.html}{JavaScript Expressions in QML Documents} for more details. -\section1 QML Object Types - -A QML object type is a type from which a QML object can be instantiated. QML -object types are derived from \l QtObject, and are provided by QML modules. -Applications can import these modules to use the object types they provide. -The \c QtQuick module provides the most common object types needed to create -user interfaces in QML. - -Finally, every QML document implicitly defines a QML object type, which can be -re-used in other QML documents. See the documentation about -\l{qtqml-typesystem-objecttypes.html}{object types in the QML type system} for -in-depth information about object types. - */ diff --git a/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc new file mode 100644 index 0000000000..0bf849b155 --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc @@ -0,0 +1,606 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! +\page qtqml-typesystem-valuetypes.html +\title QML Value Types +\brief Description of QML value types + +QML supports built-in and custom value types. + +A \e{value type} is one that is conceptually passed by value rather than by +reference, such as an \c int or a \c string. This contrasts with +\l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types}. Object types +are passed by reference. If you assign an instance of an object type to two +different properties, both properties carry the same value. Modifying the object +is reflected in both properties. If you assign an instance of a value type to +two different properties, the properties carry separate values. If you modify +one of them, the other one stays the same. Value types are only conceptually +passed by value since it must still be possible to interact with them as if they +were JavaScript objects. To facilitate this, in reality they are passed as +\l{QML Value Type and Sequence References}{Value Type References} when you access +them from JavaScript code. + +Unlike an object type, a value type cannot be used to declare QML objects: +it is not possible, for example, to declare an \c int{} object or a \c size{} object. + +Value types can be used to refer to: + +\list +\li A single value (e.g. \l int refers to a single number) +\li A value that contains properties and methods (e.g. \l size refers to a value with \c width and \c height properties) +\li The generic type \l{var}. It can hold values of any other type but is itself a value type. +\endlist + +When a variable or property holds a value type and it is assigned to another +variable or property, then a copy of the value is made. + +\sa {qtqml-typesystem-topic.html}{The QML Type System} + + +\section1 Available Value Types + +Some value types are supported by the engine by default and do not require an +\l {Import Statements}{import statement} to be used, while others do require +the client to import the module which provides them. +All of the value types listed below may be used as a \c property type in a QML +document, with the following exceptions: +\list + \li \c void, which marks the absence of a value + \li \c list must be used in conjunction with an object or value type as element + \li \c enumeration cannot be used directly as the enumeration must be defined by a registered QML object type +\endlist + +\section2 Built-in Value Types Provided By The QML Language + +The built-in value types supported natively in the \l{The QML Reference}{QML language} are listed below: +\annotatedlist qmlvaluetypes + +\section2 Value Types Provided By QML Modules + +QML modules may extend the QML language with more value types. + +For instance, the value types provided by the \c QtQml module are: +\annotatedlist qtqmlvaluetypes + +The value types provided by the \c QtQuick module are: +\annotatedlist qtquickvaluetypes + +The \l{QtQml::Qt}{Qt} global object provides \l{globalqtobjecttypes}{useful functions} for manipulating values of value +types for the \l{Qt Qml} and \l{Qt Quick} modules. + +Other Qt modules will document their value types on their respective module pages. + +You may define your own value types as described in +\l{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++}. +In order to use types provided by a particular QML module, clients +must import that module in their QML documents. + +\section1 Property Change Behavior for Value Types + +Some value types have properties: for example, the \l font type has +\c pixelSize, \c family and \c bold properties. Unlike properties of +\l{qtqml-typesystem-topic.html#qml-object-types}{object types}, properties of +value types do not provide their own property change signals. It is only possible +to create a property change signal handler for the value type property itself: + +\code +Text { + // invalid! + onFont.pixelSizeChanged: doSomething() + + // also invalid! + font { + onPixelSizeChanged: doSomething() + } + + // but this is ok + onFontChanged: doSomething() +} +\endcode + +Be aware, however, that a property change signal for a value type is emitted +whenever \e any of its attributes have changed, as well as when the property itself +changes. Take the following code, for example: + +\qml +Text { + onFontChanged: console.log("font changed") + + Text { id: otherText } + + focus: true + + // changing any of the font attributes, or reassigning the property + // to a different font value, will invoke the onFontChanged handler + Keys.onDigit1Pressed: font.pixelSize += 1 + Keys.onDigit2Pressed: font.b = !font.b + Keys.onDigit3Pressed: font = otherText.font +} +\endqml + +In contrast, properties of an \l{qtqml-typesystem-topic.html#qml-object-types}{object type} +emit their own property change signals, and a property change signal handler for an object-type +property is only invoked when the property is reassigned to a different object value. + +*/ + +/*! + \qmlvaluetype int + \ingroup qmlvaluetypes + \brief a whole number, e.g. 0, 10, or -20. + + The \c int type refers to a whole number, e.g. 0, 10, or -20. + + The possible \c int values range from -2147483648 to 2147483647, + although most types will only accept a reduced range (which they + mention in their documentation). + + Example: + \qml + NumberAnimation { loops: 5 } + \endqml + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype bool + \ingroup qmlvaluetypes + \brief a binary true/false value. + + The \c bool type refers to a binary true/false value. + + Properties of type \c bool have \c false as their default value. + + Example: + \qml + Item { + focus: true + clip: false + } + \endqml + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype real + \ingroup qmlvaluetypes + + \brief a number with a decimal point. + + The \c real type refers to a number with decimal point, e.g. 1.2 or -29.8. + + Example: + \qml + Item { width: 100.45; height: 150.82 } + \endqml + + \note In QML all reals are stored in double precision, \l + {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} + format. + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype double + \ingroup qmlvaluetypes + + \brief a number with a decimal point, stored in double precision. + + The \c double type refers to a number with a decimal point and is stored in double precision, \l + {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format. It's the same as \c real. + + Properties of type \c double have \e {0.0} as their default value. + + Example: + \qml + Item { + property double number: 32155.2355 + } + \endqml + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype string + \ingroup qmlvaluetypes + \brief A free form text string. + + The \c string type refers to a free form text string in quotes, for example + "Hello world!". The QML language provides this value type by default. + + Example: + \qml + Text { text: "Hello world!" } + \endqml + + Properties of type \c string are empty by default. + + Strings have a \c length attribute that holds the number of characters in + the string. + + The string value type is backed by the C++ type QString. It extends the + JavaScript String primitive type in that it provides much of the same API, + plus some extra methods. For example, the QML string value type method + \c {arg()} supports value substitution: + + \qml + var message = "There are %1 items" + var count = 20 + console.log(message.arg(count)) + \endqml + + The example above prints "There are 20 items". + + The QML string value type supports most of the ECMAScript string features, + such as template (string) literals, string interpolation, multi-line + strings, and looping over strings. + + In general, QML string supports most JavaScript String methods, including + checking for inclusion using \c string.includes(), \c string.startsWith(), + and \c string.endsWith(); repeating a string using \c string.repeats(), and + slicing and splitting using \c string.slice() and \c string.split(). + + For more information about which version of ECMAScript QML supports, see + \l {JavaScript Host Environment} + + For more information about JavaScript String methods, see + \l {https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String} + {mdn JavaScript String} + + When integrating with C++, note that any QString value + \l{qtqml-cppintegration-data.html}{passed into QML from C++} is + automatically converted into a \c string value, and vice-versa. + + \sa {QML Value Types}, {ECMA-262}{ECMAScript Language Specification} +*/ + +/*! + \qmlvaluetype url + \ingroup qmlvaluetypes + \brief a resource locator. + + The \c url type refers to a resource locator (like a file name, for example). It can be either + absolute, e.g. "http://qt-project.org", or relative, e.g. "pics/logo.png". A relative URL is + resolved relative to the URL of the containing component. + + For example, the following assigns a valid URL to the \l {Image::source} + property, which is of type \c url: + + \qml + Image { source: "pics/logo.png" } + \endqml + + When integrating with C++, note that any QUrl value + \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically + converted into a \c url value, and vice-versa. + + Alternatively you may convert your \c url to a \l{https://developer.mozilla.org/en-US/docs/Web/API/URL}{URL} object + in order to access and modify its components: + \qml + var urlObject = new URL(url); + \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: URLs are not automatically resolved on assignment anymore. + The individual elements that use URLs have to resolve them themselves. + + \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 {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. + + For example, a local file containing a '#' character, which would normally be + interpreted as the beginning of the URL 'fragment' element, can be accessed by + encoding the characters of the file name: + + \qml + Image { source: encodeURIComponent("/tmp/test#1.png") } + \endqml + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + + +/*! + \qmlvaluetype list + \ingroup qmlvaluetypes + \brief a list of QML objects. + + The \c list type refers to a list of QML objects or values. + + Properties of type \c list are empty by default. + + A \c list can store QML objects or \l{QML Value Types}{value type} values. + + When integrating with C++, note that any QQmlListProperty value + \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically + converted into a \c list value, and vice-versa. + + Similarly any \c{QList<T>} of a registered value type \c{T} is automatically + converted into a \c list value, and vice-versa. + + \section1 Using the list Type + + For example, the \l Item type has a \l {Item::}{states} list-type property that + can be assigned to and used as follows: + + \qml + import QtQuick + + Item { + width: 100; height: 100 + + states: [ + State { name: "activated" }, + State { name: "deactivated" } + ] + + Component.onCompleted: { + console.log("Name of first state:", states[0].name) + for (var i = 0; i < states.length; i++) + console.log("state", i, states[i].name) + } + } + \endqml + + The defined \l State objects will be added to the \c states list + in the order in which they are defined. + + If the list only contains one object, the square brackets may be omitted: + + \qml + import QtQuick + + Item { + width: 100; height: 100 + states: State { name: "activated" } + } + \endqml + + You can also declare your own list properties in QML: + + \qml + import QtQml + + QtObject { + property list<int> intList: [1, 2, 3, 4] + property list<QtObject> objectList + } + \endqml + + Lists can be used much like JavaScript arrays. For example: + + \list + \li Values are assigned using the \c[] square bracket syntax with comma-separated values + \li The \c length property provides the number of items in the list + \li Values in the list are accessed using the \c [index] syntax + \li You can use \c{push()} to append entries + \li You can set the \c length property of the list to truncate or extend it. + \endlist + + However, you can \e{not} automatically extend the list by assigning to an + index currently out of range. Furthermore, if you insert \c null values + into a list of objects, those are converted to \c nullptr entries in + the underlying QQmlListProperty. + + A list of value types is different from a JavaScript array in one further + important aspect: Growing it by setting its length does not produce undefined + entries, but rather default-constructed instances of the value type. + + Similarly, growing a list of object types this way produces null entries, + rather than undefined entries. + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + + /*! + \qmlvaluetype var + \ingroup qmlvaluetypes + \brief a generic property type. + + The \c var type is a generic property type that can refer to any data type. + + It is equivalent to a regular JavaScript variable. + For example, var properties can store numbers, strings, objects, + arrays and functions: + + \qml + Item { + property var aNumber: 100 + property var aBool: false + property var aString: "Hello world!" + property var anotherString: String("#FF008800") + property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5) + property var aRect: Qt.rect(10, 10, 10, 10) + property var aPoint: Qt.point(10, 10) + property var aSize: Qt.size(10, 10) + property var aVector3d: Qt.vector3d(100, 100, 100) + property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })] + property var anObject: { "foo": 10, "bar": 20 } + property var aFunction: (function() { return "one"; }) + } + \endqml + + \section1 Change Notification Semantics + + It is important to note that changes in regular properties of JavaScript + objects assigned to a var property will \b{not} trigger updates of bindings + that access them. The example below will display "The car has 4 wheels" as + the change to the wheels property will not cause the reevaluation of the + binding assigned to the "text" property: + + \qml + Item { + property var car: new Object({wheels: 4}) + + Text { + text: "The car has " + car.wheels + " wheels"; + } + + Component.onCompleted: { + car.wheels = 6; + } + } + \endqml + + If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"} + then the text would be updated to say "The car has 6 wheels", since the + car property itself would be changed, which causes a change notification + to be emitted. + + \section1 Property Value Initialization Semantics + + The QML syntax defines that curly braces on the right-hand-side of a + property value initialization assignment denote a binding assignment. + This can be confusing when initializing a \c var property, as empty curly + braces in JavaScript can denote either an expression block or an empty + object declaration. If you wish to initialize a \c var property to an + empty object value, you should wrap the curly braces in parentheses. + + Properties of type \c var are \c {undefined} by default. + + For example: + \qml + Item { + property var first: {} // nothing = undefined + property var second: {{}} // empty expression block = undefined + property var third: ({}) // empty object + } + \endqml + + In the previous example, the \c first property is bound to an empty + expression, whose result is undefined. The \c second property is bound to + an expression which contains a single, empty expression block ("{}"), which + similarly has an undefined result. The \c third property is bound to an + expression which is evaluated as an empty object declaration, and thus the + property will be initialized with that empty object value. + + Similarly, a colon in JavaScript can be either an object property value + assignment, or a code label. Thus, initializing a var property with an + object declaration can also require parentheses: + + \qml + Item { + property var first: { example: 'true' } // example is interpreted as a label + property var second: ({ example: 'true' }) // example is interpreted as a property + property var third: { 'example': 'true' } // example is interpreted as a property + Component.onCompleted: { + console.log(first.example) // prints 'undefined', as "first" was assigned a string + console.log(second.example) // prints 'true' + console.log(third.example) // prints 'true' + } + } + \endqml + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype variant + \ingroup qmlvaluetypes + \brief a generic property type. + + The \c variant type is the same as the \c var type. Use \c var instead. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype void + \ingroup qmlvaluetypes + \brief The empty value type. + + The \c void type is exclusively used to type-annotate JavaScript functions + returning \c undefined. For example: + + \qml + function doThings() : void { console.log("hello") } + \endqml + + This is to help tooling analyze calls to such functions and compile them and + their callers to C++. + + You cannot declare \c void properties in QML. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype enumeration + \ingroup qmlvaluetypes + \brief a named enumeration value. + + The \c enumeration type refers to a named enumeration value. + + Each named value can be referred to as \c {<Type>.<value>}. For + example, the \l Text type has an \c AlignRight enumeration value: + + \qml + Text { horizontalAlignment: Text.AlignRight } + \endqml + + (For backwards compatibility, the enumeration value may also be + specified as a string, e.g. "AlignRight". This form is not + recommended for new code.) + + When integrating with C++, note that any \c enum value + \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically + converted into an \c enumeration value, and vice-versa. + + This value type is provided by the QML language. Some enumeration values + are provided by the QtQuick import. + + \section1 Using the enumeration Type in QML + + The \c enumeration type is a representation of a C++ \c enum type. It is + not possible to refer to the \c enumeration type in QML itself; instead, the + \l int or \l var types can be used when referring to \c enumeration values + from QML code. + + For example: + + \qml + import QtQuick 2.0 + + Item { + // refer to Text.AlignRight using an int type + property int enumValue: textItem.horizontalAlignment + + signal valueEmitted(int someValue) + + Text { + id: textItem + horizontalAlignment: Text.AlignRight + } + + // emit valueEmitted() signal, which expects an int, with Text.AlignRight + Component.onCompleted: valueEmitted(Text.AlignRight) + } + \endqml + + \sa {QML Value Types} + \sa {qtqml-syntax-objectattributes.html#enumeration-attributes}{Enumeration Attributes} +*/ diff --git a/src/qml/doc/src/qmllint/access-singleton-via-object.qdoc b/src/qml/doc/src/qmllint/access-singleton-via-object.qdoc new file mode 100644 index 0000000000..66a2f86b7c --- /dev/null +++ b/src/qml/doc/src/qmllint/access-singleton-via-object.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-access-singleton-via-object.html +\ingroup qmllint-warnings-and-errors + +\title access-singleton-via-object +\brief BRIEF + +\section1 access-singleton-via-object + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/alias-cycle.qdoc b/src/qml/doc/src/qmllint/alias-cycle.qdoc new file mode 100644 index 0000000000..561cedf416 --- /dev/null +++ b/src/qml/doc/src/qmllint/alias-cycle.qdoc @@ -0,0 +1,60 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-alias-cycle.html +\ingroup qmllint-warnings-and-errors + +\title Alias Cycle +\brief Alias property is part of an alias cycle. + +\section1 Alias Property Is Part Of An Alias Cycle + +\section2 What happened? +A \l{QML Object Attributes#property-aliases}{property alias} resolves to itself or to another +alias resolving to itself. + +Usually, \l{QML Object Attributes#property-aliases}{a property alias} should reference another +property either directly, or indirectly by passing through another alias property. + +If a property alias directly or indirectly references itself, then it forms an alias cycle. +The warning indicates that the current alias property is inside or references +an alias cycle, see \l{#example}{Example}. + +\section2 Why is this bad? +Instances of components with alias cycles will not be created at runtime: they will be null instead. + +\section2 Example +\qml +import QtQuick + +Item { + id: someId + property alias myself: someId.myself // not ok: referring to itself + + property alias cycle: someId.cycle2 // not ok: indirectly referring to itself + property alias cycle2: someId.cycle + + property alias indirect: someId.cycle // not ok: referring to alias indirectly referring to itself +} +\endqml +You can fix this warning by breaking up the alias cycles: +\qml +import QtQuick + +Item { + id: someId + Item { + id: anotherId + property string myself + property int cycle + } + property alias myself: anotherId.myself // ok: referring to a property + + property alias cycle: someId.cycle2 // ok: does not refer to itself anymore + property alias cycle2: anotherId.cycle // ok: not a cycle anymore + + property alias indirect: someId.cycle // ok: cycle does not form an alias cycle anymore +} +\endqml +*/ diff --git a/src/qml/doc/src/qmllint/attached-property-reuse.qdoc b/src/qml/doc/src/qmllint/attached-property-reuse.qdoc new file mode 100644 index 0000000000..15d81f6b94 --- /dev/null +++ b/src/qml/doc/src/qmllint/attached-property-reuse.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-attached-property-reuse.html +\ingroup qmllint-warnings-and-errors + +\title attached-property-reuse +\brief BRIEF + +\section1 attached-property-reuse + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/compiler.qdoc b/src/qml/doc/src/qmllint/compiler.qdoc new file mode 100644 index 0000000000..7b2eb22f41 --- /dev/null +++ b/src/qml/doc/src/qmllint/compiler.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-compiler.html +\ingroup qmllint-warnings-and-errors + +\title compiler +\brief BRIEF + +\section1 compiler + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/deferred-property-id.qdoc b/src/qml/doc/src/qmllint/deferred-property-id.qdoc new file mode 100644 index 0000000000..990322a88e --- /dev/null +++ b/src/qml/doc/src/qmllint/deferred-property-id.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-deferred-property-id.html +\ingroup qmllint-warnings-and-errors + +\title deferred-property-id +\brief BRIEF + +\section1 deferred-property-id + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/deprecated.qdoc b/src/qml/doc/src/qmllint/deprecated.qdoc new file mode 100644 index 0000000000..311796871a --- /dev/null +++ b/src/qml/doc/src/qmllint/deprecated.qdoc @@ -0,0 +1,23 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-deprecated.html +\ingroup qmllint-warnings-and-errors + +\title Deprecated +\brief A deprecated property or type was used. + +\section1 Deprecated Binding or Type + +\section2 What happened? +A deprecated type was instantiated, a deprecated property was used or a deprecated method was +called. + +\section2 Why is this bad? +Types, properties and methods can be deprecated for different reasons, please refer to the +documentation of the deprecated item to find out why they were deprecated. + +You can fix the deprecation warning by following the advice on the deprecation notice in the +documentation of the deprecated item. +*/ diff --git a/src/qml/doc/src/qmllint/duplicate-property-binding.qdoc b/src/qml/doc/src/qmllint/duplicate-property-binding.qdoc new file mode 100644 index 0000000000..4826a552ea --- /dev/null +++ b/src/qml/doc/src/qmllint/duplicate-property-binding.qdoc @@ -0,0 +1,122 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-duplicate-property-binding.html +\ingroup qmllint-warnings-and-errors + +\title Duplicate Bindings +\brief A property was bound multiple times. + +This warning category has multiple warnings: +\list + \li \l{Duplicate Interceptor On Property} + \li \l{Cannot Combine Value Source And Binding} + \li \l{Duplicate Value Source On Property} +\endlist + +\section1 Duplicate Interceptor On Property + +\section2 What happened? +One property has multiple \l{Property Modifier Types}{interceptors}. + +\section2 Why is this bad? +Setting multiple interceptors on the same property is unsupported by the QML engine. + +\section2 Example + +Lets use \l{Behavior} as interceptor twice on the same property: +\qml +import QtQuick + +Rectangle { + Behavior on width { + NumberAnimation { duration: 1000 } + } + Behavior on width { // not ok: Duplicate interceptor on property "width" [duplicate-property-binding] + NumberAnimation { duration: 2000 } + } +} +\endqml +You can fix this warning by removing all but one \l{Behavior}: +\qml +import QtQuick + +Rectangle { + Behavior on width { + NumberAnimation { duration: 2000 } + } +} +\endqml + +\b {See also} \l {Property Modifier Types}. + +\section1 Duplicate Value Source On Property + +\section2 What happened? +One property has multiple \l{Property Value Sources}{value sources}. + +\section2 Why is this bad? +The value sources will show unexpected behavior when combined. See \l{Example}{example} below. + +\section2 Example + +Lets use \l{NumberAnimation} as value source twice on the same property: +\qml +import QtQuick + +Rectangle { + NumberAnimation on x { to: 50; duration: 1000 } + NumberAnimation on x { to: 10; duration: 100 } // not ok: Duplicate value source on property "x" [duplicate-property-binding] + + onXChanged: console.log(x) +} +\endqml + +If you check the output of that program, you will see that the two NumberAnimation will interleave +each other, which is probably not the effect that was intended. +You can fix this warning by removing all but one \l{NumberAnimation}: +\qml +import QtQuick + +Rectangle { + NumberAnimation on x { to: 50; duration: 1000 } +} +\endqml + + +\section1 Cannot Combine Value Source And Binding + +\section2 What happened? +One property has a \l{Property Value Sources}{value source} and a binding on the same property. + +\section2 Why is this bad? +The binding will updated the property value before the value source starts updating this property. +This may lead to unexpected behavior, and is also harder to read. + +\section2 Example + +Lets use \l{NumberAnimation} as value source on the same property: +\qml +import QtQuick + +Rectangle { + NumberAnimation on x { to: 50; duration: 1000 } // not ok: Cannot combine value source and binding on property "x" [duplicate-property-binding] + x: 55 + + onXChanged: console.log(x) +} +\endqml + +If you check the output of that program, you will see that the \l{NumberAnimation} will animate +from 55 to 50, which would be easier to read with following code: +\qml +import QtQuick + +Rectangle { + NumberAnimation on x { from: 55; to: 50; duration: 1000 } // ok: intentions are clearer now! +} +\endqml + +*/ + diff --git a/src/qml/doc/src/qmllint/duplicated-name.qdoc b/src/qml/doc/src/qmllint/duplicated-name.qdoc new file mode 100644 index 0000000000..0cc4583cb4 --- /dev/null +++ b/src/qml/doc/src/qmllint/duplicated-name.qdoc @@ -0,0 +1,70 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-duplicated-name.html +\ingroup qmllint-warnings-and-errors + +\title Duplicated Name +\brief Multiple signals or properties share the same name in the same Component. + +This warning category has multiple warnings: +\list + \li \l{Duplicated Property Name} + \li \l{Duplicated Signal Name} +\endlist + +\section1 Duplicated Property Name + +\section2 What happened? +Multiple properties in the same QML component scope have the same name. + +\section2 Why is this bad? +Components with duplicate property names will not be created at runtime: they will be null instead. + +\section2 Example +\qml +import QtQuick + +Item { + property int helloWorld + property int helloWorld +} +\endqml +You can fix this warning by removing the duplicate property or renaming it: +\qml +import QtQuick + +Item { + property int helloWorld +} +\endqml + +\section1 Duplicated Signal Name + +\section2 What happened? +Multiple signals in the same QML component scope have the same name. + +\section2 Why is this bad? +Components with duplicate signal names will not be created at runtime: they will be null instead. + +\section2 Example +\qml +import QtQuick + +Rectangle { + signal helloWorld + signal helloWorld +} +\endqml +You can fix this warning by removing the duplicate signal or renaming it: +\qml +import QtQuick + +Rectangle { + signal helloWorld +} + +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/import.qdoc b/src/qml/doc/src/qmllint/import.qdoc new file mode 100644 index 0000000000..c5adababc4 --- /dev/null +++ b/src/qml/doc/src/qmllint/import.qdoc @@ -0,0 +1,174 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-import.html +\ingroup qmllint-warnings-and-errors + +\title Warnings Occurred While Importing +\brief The imported module was not found. + +This warning category contains multiple warnings: +\list +\li \l{Failed To Import Module} +\li \l{Component Was Not Found} +\li \l{Import Qualifier Must Start With A Capital Letter} +\li \l{Unknown Import Syntax} +\endlist + +\section1 Failed To Import Module + +\section2 What happened? +The module imported via \l{Import Statements}{import statement} was not found. + +This can be caused, for example, by +\list + \li a typo in the import statement, or + \li a user-defined module that was not built, or + \li a wrong \l{Import Statements#qml-import-path}{import path}, or + \li a missing module +\endlist + +\section2 Why is this bad? +The application can't run because it can't find a module it relies on. + +\section2 Examples + +\section3 Typo In The Import Statement +\qml +import QtQuicky // not ok: typo in module name + +Item { +} +\endqml +You can fix this warning by correcting the typo: +\qml +import QtQuick // ok: no typo in module name + +Item { +} +\endqml + +\section3 User-Defined Module That Was Not Built + +Some tooling like \l{\QMLLS Reference}{\QMLLS} or \l{qmllint Reference}{qmllint} +can't find user-defined modules when they +are not built. If your project defines the QML Module you are trying to import, then +the QML tooling will not find it until you build it. + +\note If building the module does not help when using \l{\QMLLS Reference}{\QMLLS}, follow the +instructions in +\l{Setting up the \QMLLS in Your Editor}{\QMLLS setup instructions} +and make sure that you communicate the correct build folder to \QMLLS. + +\section3 Wrong Import Path + +Please refer to \l{Import Statements#qml-import-path}{the QML import path documentation} and to +\l{Debugging QML Applications#debugging-module-imports}{the debugging module import documentation} +for more information about import paths. + +\section3 Missing Module + +If the previous sections did not help to find the imported module, it might be missing. +This might be caused by a missing dependency. When using external libraries, verify that they are +actually installed, and that their modules end up in an +\l{Import Statements#qml-import-path}{import path}. + +\section1 Component Was Not Found + +\section2 What happened? +Some component was not found. + +\section2 Why is this bad? +The application can't run because it can't instantiate the non-found component. + +\section2 Examples + +\section3 Typo In The Component Name +\qml +import QtQuick + +Item { + Itemy {} // not ok: typo in name +} +\endqml +You can fix this warning by correcting the typo: +\qml +import QtQuick + +Item { + Item {} // ok: no typo in name +} +\endqml + +\section3 Missing Import Statement + +\qml + +Item { // not ok: must be imported from QtQuick first +} +\endqml +You can fix this warning by adding the missing module import: +\qml +import QtQuick + +Item { // ok: was imported from QtQuick +} +\endqml + +\section1 Import Qualifier must start with a capital letter + +\section2 What happened? +Some imported module has an invalid qualifier. + +\section2 Why is this bad? +The module imported with this invalid qualifier can't be used. + +\section2 Examples + +\qml +import QtQuick as qq + +qq.Item { +} +\endqml +You can fix this warning by making the import qualifier start with an upper case letter: +\qml +import QtQuick as Qq + +Qq.Item { +} +\endqml + +\section1 Unknown Import Syntax + +\section2 What happened? +An import statement is using an invalid \l{Import Statements}{import syntax}. + +\section2 Why is this bad? +The application can't run because it can't import a module it relies on. + +\section2 Examples + +\qml +import "¯\(ツ)/¯:/path/to/Module" +import QtQuick + +Item { +} +\endqml +You can fix this warning by using URLs that have an allowed scheme: +\qml +import "qrc:/path/to/Module" +import QtQuick + +Item { +} +\endqml + +\note This example assumes that you are not using \l{QQmlAbstractUrlInterceptor}{URL handlers}. + +\sa{Import Statements} + +*/ + diff --git a/src/qml/doc/src/qmllint/incompatible-type.qdoc b/src/qml/doc/src/qmllint/incompatible-type.qdoc new file mode 100644 index 0000000000..6946740b66 --- /dev/null +++ b/src/qml/doc/src/qmllint/incompatible-type.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-incompatible-type.html +\ingroup qmllint-warnings-and-errors + +\title incompatible-type +\brief BRIEF + +\section1 incompatible-type + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/inheritance-cycle.qdoc b/src/qml/doc/src/qmllint/inheritance-cycle.qdoc new file mode 100644 index 0000000000..c1be63ae78 --- /dev/null +++ b/src/qml/doc/src/qmllint/inheritance-cycle.qdoc @@ -0,0 +1,46 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-inheritance-cycle.html +\ingroup qmllint-warnings-and-errors + +\title Inheritance Cycle +\brief A component inherits from itself. + +\section1 Component Is Part Of An Inheritance Cycle + +\section2 What happened? +A component inherited directly or indirectly from itself. + +Usually, Components can inherit properties, methods, signals and enums from other components. + +If a component inherits itself directly or indirectly through another base component, then +it forms an inheritance cycle. The warning indicates that the current component is inside an +inheritance cycle, see \l{#example}{Example}. + +\section2 Why is this bad? +Components with inheritance cycles will not be created at runtime: they will be null instead. + +\section2 Example +\qml +import QtQuick + +Item { + component Cycle: Cycle {} // not ok: directly inherits from itself + component C: C2 {} // not ok: indirectly inherits from itself + component C2: C{} +} +\endqml +You can fix this warning by breaking up the inheritance cycle +\qml +import QtQuick + +Item { + component Cycle: Item {} // ok: does not inherit from itself + component C: C2 {} // ok: does not indirectly inherits from itself anymore + component C2: Cycle{} +} +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/invalid-lint-directive.qdoc b/src/qml/doc/src/qmllint/invalid-lint-directive.qdoc new file mode 100644 index 0000000000..39488f291f --- /dev/null +++ b/src/qml/doc/src/qmllint/invalid-lint-directive.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-invalid-lint-directive.html +\ingroup qmllint-warnings-and-errors + +\title invalid-lint-directive +\brief BRIEF + +\section1 invalid-lint-directive + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/missing-enum-entry.qdoc b/src/qml/doc/src/qmllint/missing-enum-entry.qdoc new file mode 100644 index 0000000000..433562f638 --- /dev/null +++ b/src/qml/doc/src/qmllint/missing-enum-entry.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-missing-enum-entry.html +\ingroup qmllint-warnings-and-errors + +\title missing-enum-entry +\brief BRIEF + +\section1 missing-enum-entry + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/missing-property.qdoc b/src/qml/doc/src/qmllint/missing-property.qdoc new file mode 100644 index 0000000000..4d1b9a02c3 --- /dev/null +++ b/src/qml/doc/src/qmllint/missing-property.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-missing-property.html +\ingroup qmllint-warnings-and-errors + +\title missing-property +\brief BRIEF + +\section1 missing-property + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/missing-type.qdoc b/src/qml/doc/src/qmllint/missing-type.qdoc new file mode 100644 index 0000000000..466370ef39 --- /dev/null +++ b/src/qml/doc/src/qmllint/missing-type.qdoc @@ -0,0 +1,240 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-missing-type.html +\ingroup qmllint-warnings-and-errors + +\title Missing Type +\brief A type used in a binding or alias was not found. + +This warning category has multiple warnings: +\list + \li \l{Cannot Deduce Type of Alias} + \li \l{No Type Found For Property} +\endlist + +\section1 Cannot Deduce Type of Alias + +\section2 What happened? +An alias property points to a property with a C++ type whose QML counterpart was not found. This can +be caused by importing a QML module which do not declare its QML dependencies on other modules. + +\note If you are importing QML modules with external dependencies, verify that they are +actually installed, and that their modules end up in an +\l{Import Statements#qml-import-path}{import path}. + +The warning might also indicate that the type of the property referenced by the alias does not have +a QML counterpart. The referenced property type might be missing the +\l{QQmlEngine::}{QML_ELEMENT} macro, for example. Refer to +\l{Defining QML Types from C++} or \l{Overview - QML and C++ Integration} in this case. + +\section2 Why is this bad? +QML tooling is not able to find the QML counterpart of the C++ type: the +\l{Qt Quick Compiler}{compiler} can't compile this property alias to +C++ and \l{qmllint Reference}{qmllint} as well as \l{\QMLLS Reference}{\QMLLS} +can't analyze this property alias. + +\section2 Example +Let our QML module have one C++ class with a property \c{myProperty}: + +\code +#include <QQuickItem> +#include <QtQml/qqmlregistration.h> +#include <QObject> + +class MyCppObject : public QObject +{ + Q_OBJECT + QML_ELEMENT +public: + MyCppObject(QObject *parent = nullptr) + : QObject(parent) + {} + + Q_PROPERTY(QQuickItem *myProperty READ myProperty WRITE setMyProperty NOTIFY notifyMyProperty) + QQuickItem *myProperty() { return m_myProperty; } + void setMyProperty(QQuickItem *item) { emit notifyMyProperty(); m_myProperty = item; } + +private: + QQuickItem *m_myProperty; + +signals: + void notifyMyProperty(); +}; +\endcode + +with following \c{CMakeLists.txt}: +\badcode +project(mymodule VERSION 0.1 LANGUAGES CXX) + +set(CMAKE_CXX_STANDARD_REQUIRED ON) +find_package(Qt6 6.5 REQUIRED COMPONENTS Quick) +qt_standard_project_setup(REQUIRES 6.5) + +qt_add_executable(appmymodule + main.cpp +) + +qt_add_qml_module(appmymodule + URI mymodule + VERSION 1.0 + QML_FILES Main.qml HelloWorld.qml + SOURCES mycppobject.cpp mycppobject.h +) + +target_link_libraries(appmymodule + PRIVATE Qt6::Quick +) +\endcode + +The C++ dependency \c{Quick} was declared, such that this class can compile and the QQuickItem +include can be found. Also, \c{mymodule} does not have any dependency on QtQuick. + +Now, let's try to use \c{myProperty} in an alias in QML. The program will run but QML tooling like +the \l{Qt Quick Compiler}{compiler}, for example, will complain about the usage of \c{myProperty}: +\qml +import mymodule + +MyCppObject { + id: root + + property alias myAlias: root.myProperty // not ok: Cannot deduce type of alias [missing-type] +} +\endqml +The reason for the warning message is that in the QML code, the type \c{QQuickItem} of +\c{myProperty} and its QML counterpart \c{Item} are not known, even if you have \c{import QtQuick} +in your QML file. This is because the same type can be exposed multiple times with different +attributes in different modules: \c{mymodule} actually has to be precise about the QML type of +\c{myProperty}. + +You can fix this warning by adding the dependency in the \c{CMakeLists.txt}: +\badcode +qt_add_qml_module(mymodule + URI mymodule + ... + # declarare QML dependency to QtQuick module + DEPENDENCIES QtQuick + ... +) +\endcode + +Now, the warning should be gone! + +\b {See also} \l {Declaring module dependencies}. + +\section1 No Type Found For Property + +\section2 What happened? +A binding was set on a property whose QML type was not found. This can be caused by a QML module +which does not declare its QML dependencies on other modules. + +\note If you are importing QML modules with external dependencies, verify that they are +actually installed, and that their modules end up in an +\l{Import Statements#qml-import-path}{import path}. + +The warning might also indicate that the type of the property does not have +a QML counterpart. The property type might be missing the +\l{QQmlEngine::}{QML_ELEMENT} macro, for example. Refer to +\l{Defining QML Types from C++} or \l{Overview - QML and C++ Integration} in this case. + +\section2 Why is this bad? +QML tooling is not able to find the QML counterpart of the C++ type: the +\l{Qt Quick Compiler}{compiler} can't compile this property binding to +C++ and \l{qmllint Reference}{qmllint} as well as \l{\QMLLS Reference}{\QMLLS} can't analyze this property binding. + +\section2 Example +Let our QML module have a C++ class with two properties, \c{myProperty} and \c{myProperty2}: + +\code +#include <QQuickItem> +#include <QtQml/qqmlregistration.h> +#include <QObject> + +class MyCppObject : public QObject +{ + Q_OBJECT + QML_ELEMENT +public: + MyCppObject(QObject *parent = nullptr) + : QObject(parent) + {} + + Q_PROPERTY(QQuickItem *myProperty READ myProperty WRITE setMyProperty NOTIFY notifyMyProperty) + QQuickItem *myProperty() { return m_myProperty; } + void setMyProperty(QQuickItem *item) { emit notifyMyProperty(); m_myProperty = item; } + + Q_PROPERTY(QQuickItem *myProperty2 READ myProperty2 WRITE setMyProperty2 NOTIFY notifyMyProperty2) + QQuickItem *myProperty2() { return m_myProperty2; } + void setMyProperty2(QQuickItem *item) { emit notifyMyProperty2(); m_myProperty2 = item; } + +private: + QQuickItem *m_myProperty; + QQuickItem *m_myProperty2; + +signals: + void notifyMyProperty(); + void notifyMyProperty2(); +}; +\endcode + +with following \c{CMakeLists.txt}: +\badcode +project(mymodule VERSION 0.1 LANGUAGES CXX) + +set(CMAKE_CXX_STANDARD_REQUIRED ON) +find_package(Qt6 6.5 REQUIRED COMPONENTS Quick) +qt_standard_project_setup(REQUIRES 6.5) + +qt_add_executable(appmymodule + main.cpp +) + +qt_add_qml_module(appmymodule + URI mymodule + VERSION 1.0 + QML_FILES Main.qml HelloWorld.qml + SOURCES mycppobject.cpp mycppobject.h +) + +target_link_libraries(appmymodule + PRIVATE Qt6::Quick +) +\endcode + +The C++ dependency \c{Quick} was declared, such that this class can compile and the QQuickItem +include can be found. Also, \c{mymodule} does not have any dependency on QtQuick. + +Now, let's try to bind \c{myProperty2} to \c{myProperty} in an alias in QML. The program will run +but QML tooling like the \l{Qt Quick Compiler}{compiler}, for example, will complain about the +usage of \c{myProperty}: + +\qml +import mymodule + +MyCppObject { + id: root + + myProperty: myProperty2 // not ok: No type found for property "myProperty". [missing-type] +} +\endqml +The reason for the warning message is that in the QML code, the type \c{QQuickItem} of \c{myProperty} +and its QML counterpart \c{Item} are not known: the dependency 'QtQuick' of mymodule was not +declared in the \c{CMakeLists.txt}. + +You can fix this warning by adding the dependency in the \c{CMakeLists.txt}: +\badcode +qt_add_qml_module(mymodule + URI mymodule + ... + # declarare QML dependency to QtQuick module + DEPENDENCIES QtQuick + ... +) +\endcode + +Now, the warning should be gone! + +\b {See also} \l {Declaring module dependencies}. +*/ + diff --git a/src/qml/doc/src/qmllint/multiline-strings.qdoc b/src/qml/doc/src/qmllint/multiline-strings.qdoc new file mode 100644 index 0000000000..4c1aef4e85 --- /dev/null +++ b/src/qml/doc/src/qmllint/multiline-strings.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-multiline-strings.html +\ingroup qmllint-warnings-and-errors + +\title multiline-strings +\brief BRIEF + +\section1 multiline-strings + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/non-list-property.qdoc b/src/qml/doc/src/qmllint/non-list-property.qdoc new file mode 100644 index 0000000000..2d778d87bc --- /dev/null +++ b/src/qml/doc/src/qmllint/non-list-property.qdoc @@ -0,0 +1,85 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-non-list-property.html +\ingroup qmllint-warnings-and-errors + +\title Non-List Property +\brief Multiple values were assigned to a non-list property. + +\section1 Cannot Assign Multiple Objects To A Default Non-List Property + +\section2 What happened? +A \l{Default Properties}{default property} has multiple bindings but the default +property type is not a list type and only expects one binding. + +\section2 Why is this bad? +All the bindings to the default property, except the last one, will be ignored. This most likely +hints that the default property should instead be a list, or that there are too many bindings to +the same property. + +\section2 Example + +Let's declare a component \c{MyComponent} that has one default non-list property, and then lets +bind three items to that default property: +\qml +import QtQuick + +Item { + component MyComponent: QtObject { + default property Item helloWorld + } + MyComponent { + // first item bound to default property: + Item { objectName: "first" } // will warn: Cannot assign multiple objects to a default non-list property [non-list-property] + // second item bound to default property: + Item { objectName: "second" } // not ok: default property was bound already + // third item bound to default property: + Item { objectName: "third" } // not ok: default property was bound already + + Component.onCompleted: console.log(helloWorld.objectName) // prints "third" + } +} + +\endqml +You can fix this warning by replacing the default property by a list: +\qml +import QtQuick + +Item { + component MyComponent: QtObject { + default property list<Item> helloWorld + } + MyComponent { + // first item bound to default property: + Item { objectName: "first" } // ok: binding a first item to the list + // second item bound to default property: + Item { objectName: "second" } // ok: binding a second item to the list + // third item bound to default property: + Item { objectName: "third" } // ok: binding a third item to the list + } +} +\endqml +You can also fix this warning by removing all the unwanted bindings, in case the default property +is not supposed to be a list: +\qml +import QtQuick + +Item { + component MyComponent: QtObject { + default property Item helloWorld + } + MyComponent { + Item { objectName: "first" } // ok: just one item bound to default property + } + MyComponent { + Item { objectName: "second" } // ok: just one item bound to default property + } + MyComponent { + Item { objectName: "third" } // ok: just one item bound to default property + } +} +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/plugin.qdoc b/src/qml/doc/src/qmllint/plugin.qdoc new file mode 100644 index 0000000000..b2b43ea5f3 --- /dev/null +++ b/src/qml/doc/src/qmllint/plugin.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-plugin.html +\ingroup qmllint-warnings-and-errors + +\title plugin +\brief BRIEF + +\section1 plugin + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/prefixed-import-type.qdoc b/src/qml/doc/src/qmllint/prefixed-import-type.qdoc new file mode 100644 index 0000000000..f2f53bcffb --- /dev/null +++ b/src/qml/doc/src/qmllint/prefixed-import-type.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-prefixed-import-type.html +\ingroup qmllint-warnings-and-errors + +\title prefixed-import-type +\brief BRIEF + +\section1 prefixed-import-type + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/qtqml-qmllint-warnings-and-errors.qdoc b/src/qml/doc/src/qmllint/qtqml-qmllint-warnings-and-errors.qdoc new file mode 100644 index 0000000000..894f5f4306 --- /dev/null +++ b/src/qml/doc/src/qmllint/qtqml-qmllint-warnings-and-errors.qdoc @@ -0,0 +1,9 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group qmllint-warnings-and-errors +\title QML Lint Warning and Errors + +Here is an overview over all QML Lint warning and error messages. +*/ diff --git a/src/qml/doc/src/qmllint/read-only-property.qdoc b/src/qml/doc/src/qmllint/read-only-property.qdoc new file mode 100644 index 0000000000..7bc6b5fcc2 --- /dev/null +++ b/src/qml/doc/src/qmllint/read-only-property.qdoc @@ -0,0 +1,38 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-read-only-property.html +\ingroup qmllint-warnings-and-errors + +\title Readonly Property +\brief A readonly property was written. + +\section1 Cannot Assign To Read-Only Property + +\section2 What happened? +A \l{Read-Only Properties}{read-only property} was written. + +\section2 Why is this bad? +The QML engine will throw a Type Error when it sees the write to a read-only property. + +\section2 Example +\qml +import QtQuick + +Item { + id: root + readonly property int someNumber: 10 + + Component.onCompleted: { + someNumber = 20 // not ok: TypeError: Cannot assign to read-only property + } +} +\endqml +You can fix this warning by removing the write to the read-only property, by writing to another +non-read-only property, or by removing the readonly modifier if the property should no longer be +considered constant. + +\sa{Read-Only Properties} +*/ + diff --git a/src/qml/doc/src/qmllint/recursion-depth-errors.qdoc b/src/qml/doc/src/qmllint/recursion-depth-errors.qdoc new file mode 100644 index 0000000000..ed0d2c09b2 --- /dev/null +++ b/src/qml/doc/src/qmllint/recursion-depth-errors.qdoc @@ -0,0 +1,53 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-recursion-depth-errors.html +\ingroup qmllint-warnings-and-errors + +\title Recursion Depths Errors +\brief Qml statement or expression is too deeply nested. + +\section1 Maximum Statement Or Expression Depth Exceeded +\section2 What happened? +A QML statement or expression was too deeply nested for the compiler. This usually only happens for +generated code where statements or expressions can be very long, as the recursion limit is usually +large enough for any sensible QML document. + +\section2 Why is this bad? +The QML engine will not be able to run this code. + +\section2 Example +\qml +import QtQuick + +Item { + function f() { + let x = 1 + 1 + .... + 1 // maximum depth exceeded: add too many ones together + return x + } + + Item { Item { .... } } // maximum depth exceeded: too many nested Item's +} +\endqml + +You can fix this warning by auto-generating smaller code pieces. You could split deeply nested +Components in multiple files or inline components, or split deeply nested expressions into multiple +expressions: +\qml +import QtQuick + +Item { + function f() { + let x = 1 + 1 + .... + 1 // first half of the split + x += 1 + 1 + .... + 1 // second half of the split + return x + } + + component NestedItem : Item { Item {... }} // first half of the nested Item + component DeeplyNestedItem: Item { ... NestedItem{} ... } // second half of the nested Items + NestedItem + DeeplyNestedItem {} +} +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/required.qdoc b/src/qml/doc/src/qmllint/required.qdoc new file mode 100644 index 0000000000..6252ddef2d --- /dev/null +++ b/src/qml/doc/src/qmllint/required.qdoc @@ -0,0 +1,65 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-required.html +\ingroup qmllint-warnings-and-errors + +\title Component is Missing a Required Property +\brief A component's required property was not bound. + +\section1 Component is Missing a Required Property + +\section2 What happened? +The \l{QML Object Attributes#required-properties}{required property} of a component was not set. + + +\section2 Why is this bad? +QML applications where components miss required properties will misbehave: they will not +start at all if a missing required property is detected statically. Dynamically created components +with missing required properties will not be created at runtime: they will be null instead. + +\section2 Example +\qml +import QtQuick + +Item { + component RepeatMe: Item { + required property int index; + required property int helloWorld; + } + + RepeatMe {} // not ok: required properties index and helloWorld not set + + Repeater { + model: 10 + RepeatMe {} // not ok: required property index set by Repeater, but not helloWorld + } +} +\endqml +You can fix this warning by setting the required properties +\qml +import QtQuick + +Item { + component RepeatMe: Item { + required property int index; + required property int helloWorld; + } + + RepeatMe { + index: 0 + helloWorld: 42 + } // ok: all required properties were set + + Repeater { + model: 10 + RepeatMe { + helloWorld: index * 2 + 1 + } // ok: all required properties were set: index by the Repeater and helloWorld by the user + } +} +\endqml + +\sa {QML Coding Conventions#required-properties}{QML Coding Conventions - Required Properties} +*/ diff --git a/src/qml/doc/src/qmllint/restricted-type.qdoc b/src/qml/doc/src/qmllint/restricted-type.qdoc new file mode 100644 index 0000000000..d240f55e4a --- /dev/null +++ b/src/qml/doc/src/qmllint/restricted-type.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-restricted-type.html +\ingroup qmllint-warnings-and-errors + +\title restricted-type +\brief BRIEF + +\section1 restricted-type + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/signal-handler-parameters.qdoc b/src/qml/doc/src/qmllint/signal-handler-parameters.qdoc new file mode 100644 index 0000000000..a6510b566b --- /dev/null +++ b/src/qml/doc/src/qmllint/signal-handler-parameters.qdoc @@ -0,0 +1,261 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-signal-handler-parameters.html +\ingroup qmllint-warnings-and-errors + +\title Signal Handler Parameters +\brief The signal handler does not satisfy the signal types. + +This warning category has multiple warnings: +\list + \li \l{Type Of Parameter In Signal Was Not Found} + \li \l{Type Of Parameter In Signal Cannot Be Used} + \li \l{The Signal Has A Parameter Of The Same Name} +\endlist + + +\section1 Type Of Parameter In Signal Was Not Found + +\section2 What happened? +A signal handler tried to handle a signal with parameters of unknown QML types. + +Usually, this happens when handling C++ defined signals in QML when the module with the C++ defined +signal does not properly declare its QML dependency to another QML module. If the module with the +C++ defined signal compiles, then this is a sign that a dependency was only declared on the C++ +level and not on \l{qt_add_qml_module#declaring-module-dependencies}{the QML module level}. + +\note If you are importing QML modules with external dependencies, verify that they are +actually installed, and that their modules end up in an +\l{Import Statements#qml-import-path}{import path}. + +The warning might also indicate that the parameter type of the C++ defined signal does not have +a QML counterpart. The parameter type might be missing the +\l{QQmlEngine Class#QML_ELEMENT}{QML_ELEMENT} macro, for example. Refer to +\l{Defining QML Types from C++} or \l{Overview - QML and C++ Integration} in this case. + +\section2 Why is this bad? +In the first case, the module with the C++ signal has an undeclared dependency on the QML module +level, which makes it hard to use the module, as users of the module need to guess the module's +hidden dependencies. + +In both cases, QML tooling is not able to find the QML counterpart of the +C++ type: the \l{Qt Quick Compiler}{compiler} can't compile this signal handler to +C++ and \l{qmllint Reference}{qmllint} as well as \l{\QMLLS Reference}{\QMLLS} +can't analyze this handler. + +\section2 Example + +Let our module have a C++ class with one \c{helloWorld} signal: +\code +#include <QQuickItem> +#include <QtQml/qqmlregistration.h> +#include <QObject> + +class MyCppObject : public QObject +{ + Q_OBJECT + QML_ELEMENT +public: + MyCppObject(QObject *parent = nullptr) + : QObject(parent) + {} + +signals: + void helloWorld(QQuickItem *i); + +}; +\endcode +with following CMakeLists.txt: +\badcode +find_package(Qt6 6.5 REQUIRED COMPONENTS Quick QuickControls2) + +qt_standard_project_setup(REQUIRES 6.5) + +qt_add_executable(mymodule + main.cpp +) + +qt_add_qml_module(mymodule + URI MyModule + VERSION 1.0 + QML_FILES Main.qml + SOURCES mycppobject.cpp mycppobject.h +) + +# declare C++ dependency to Quick +target_link_libraries(appuntitled27 + PRIVATE Qt6::Quick +) +\endcode +The C++ dependency \c{Quick} was declared, such that this class can compile and the QQuickItem +include can be found. Also, mymodule does not have any dependency on QtQuick. + +Now, lets try to handle this \c{helloWorld} signal in QML: +\qml +import MyModule // name of the module with MyCppObject + +MyCppObject { + onHelloWorld: function (x) { console.log(x); } // not ok: Type QQuickItem was not found! +} +\endqml + +The reason of the warning message is that in the QML code, \c{QQuickItem} and its QML counterpart +\c{Item} are not known: the dependency 'QtQuick' of MyModule was not declared in the CMakeLists.txt! + +You can add it as following in the qt_add_qml_module() call: +\badcode +qt_add_qml_module(mymodule + URI MyModule + ... + # declare QML dependencies to QtQuick: + DEPENDENCIES QtQuick + ... +) +\endcode + +Now, the QML code should be fine again! + +\sa {qt_add_qml_module#declaring-module-dependencies} + +\omit +TODO: QML Lint cannot detect if you pass signal parameters by value, reference or pointer! +Therefore, it will never print that warning. +\section1 Type Of Parameter In Signal Should Be Passed By Pointer +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml + +TODO: QML Lint cannot detect if you pass signal parameters by value, reference or pointer! +Therefore, it will never print that warning. +that warning +\section1 Type Of Parameter In Signal Should Be Passed By Value Or Const Reference +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml + +\endomit + +\section1 Signal Handler Has More Formal Parameters Than The Signal It Handles +\section2 What happened? +A signal handler expects more parameters than what the signal will actually provide. + +\section2 Why is this bad? +The extra parameters will be undefined. + +\section2 Example +\qml +import QtQuick + +Item { + signal helloWorld(x: QtObject) // signal expects only one parameter + + onHelloWorld: function (x,y,z) {} // not ok: signal handler handles three parameters +} +\endqml +You can fix this warning by removing the extra parameters of the signal handler: +\qml +import QtQuick + +Item { + signal helloWorld(x: QtObject) // signal expects only one parameter + + onHelloWorld: function (x) {} // ok: signal handler handles one parameter +} +\endqml + +It can also be fixed by adding the missing parameters to the signal's declaration: +\qml +import QtQuick + +Item { + signal helloWorld(x: QtObject, y: int, y: int) // signal expects three parameters + + onHelloWorld: function (x,y,z) {} // ok: signal handler handles three parameters +} +\endqml + +\section1 The Signal Has A Parameter Of The Same Name +\section2 What happened? +The signal or signal handler might have swapped some of its arguments, or some arguments might be +missing. + +\section2 Why is this bad? +This is very probably a typo and not intended by the user. + +\section2 Example +\section3 Missing Arguments +\qml +import QtQuick + +Item { + signal helloWorld(x: QtObject, y: int) + + onHelloWorld: function (y) {} // not ok: it seems that x was forgotten +} + +\endqml +You can fix this warning by adding the missing parameters: +\qml +import QtQuick + +Item { + signal helloWorld(x: QtObject, y: int) + + onHelloWorld: function (x, y) {} // ok: parameters have the same order as in helloWorld +} +\endqml +or by renaming the first parameter: +\qml +import QtQuick + +Item { + signal helloWorld(x: QtObject, y: int) + + onHelloWorld: function (x) {} // ok: parameters have the same order as in helloWorld, even if y is missing +} +\endqml + +\section3 Swapped Arguments +\qml +import QtQuick + +Item { + signal helloWorld(x: QtObject, y: int) + + onHelloWorld: function (y, x) {} // not ok: helloWorld expects first 'x' then 'y' +} + +\endqml +You can fix this warning by reordering the parameters in the correct order +\qml +import QtQuick + +Item { + signal helloWorld(x: QtObject, y: int) + + onHelloWorld: function (x, y) {} // ok: parameters have the same order as in helloWorld +} + +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/syntax.duplicate-ids.qdoc b/src/qml/doc/src/qmllint/syntax.duplicate-ids.qdoc new file mode 100644 index 0000000000..e1f796c8fd --- /dev/null +++ b/src/qml/doc/src/qmllint/syntax.duplicate-ids.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-syntax.duplicate-ids.html +\ingroup qmllint-warnings-and-errors + +\title syntax.duplicate-ids +\brief BRIEF + +\section1 syntax.duplicate-ids + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/syntax.id-quotation.qdoc b/src/qml/doc/src/qmllint/syntax.id-quotation.qdoc new file mode 100644 index 0000000000..b335bbc962 --- /dev/null +++ b/src/qml/doc/src/qmllint/syntax.id-quotation.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-syntax.id-quotation.html +\ingroup qmllint-warnings-and-errors + +\title syntax.id-quotation +\brief BRIEF + +\section1 syntax.id-quotation + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/syntax.qdoc b/src/qml/doc/src/qmllint/syntax.qdoc new file mode 100644 index 0000000000..e2e59e8dce --- /dev/null +++ b/src/qml/doc/src/qmllint/syntax.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-syntax.html +\ingroup qmllint-warnings-and-errors + +\title syntax +\brief BRIEF + +\section1 syntax + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/top-level-component.qdoc b/src/qml/doc/src/qmllint/top-level-component.qdoc new file mode 100644 index 0000000000..111a1e4bf6 --- /dev/null +++ b/src/qml/doc/src/qmllint/top-level-component.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-top-level-component.html +\ingroup qmllint-warnings-and-errors + +\title top-level-component +\brief BRIEF + +\section1 top-level-component + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/uncreatable-type.qdoc b/src/qml/doc/src/qmllint/uncreatable-type.qdoc new file mode 100644 index 0000000000..05dcb53edc --- /dev/null +++ b/src/qml/doc/src/qmllint/uncreatable-type.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-uncreatable-type.html +\ingroup qmllint-warnings-and-errors + +\title uncreatable-type +\brief BRIEF + +\section1 uncreatable-type + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/unqualified.qdoc b/src/qml/doc/src/qmllint/unqualified.qdoc new file mode 100644 index 0000000000..7f2e315efe --- /dev/null +++ b/src/qml/doc/src/qmllint/unqualified.qdoc @@ -0,0 +1,52 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-unqualified.html +\ingroup qmllint-warnings-and-errors + +\title Unqualified Access +\brief Accessing an outer scope without its id. + +\section1 Unqualified Access + +\section2 What happened? + +A parent element was accessed without its \l{QML Object Attributes#the-id-attribute}{id}. + +\section2 Why is this bad? + +This makes the code harder to read and impedes performance. + +\section2 Example + +\qml +import QtQuick + +Item { + property int helloWorld + Item { + property int unqualifiedAccess: helloWorld + 1 // not ok: Unqualified access here. + } +} +\endqml + +You can fix this warning by referring to the parent object by +\l{QML Object Attributes#the-id-attribute}{id}. +If the object currently has no \l{QML Object Attributes#the-id-attribute}{id}, you will need to add +one first. + +\qml +import QtQuick + +Item { + id: root + property int helloWorld + Item { + property int unqualifiedAccess: root.helloWorld + 1 // ok: this access is qualified now! + } +} +\endqml + +\sa {QML Coding Conventions#unqualified-access}{QML Coding Conventions - Unqualified Access} +*/ diff --git a/src/qml/doc/src/qmllint/unresolved-alias.qdoc b/src/qml/doc/src/qmllint/unresolved-alias.qdoc new file mode 100644 index 0000000000..63b02613dd --- /dev/null +++ b/src/qml/doc/src/qmllint/unresolved-alias.qdoc @@ -0,0 +1,50 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-unresolved-alias.html +\ingroup qmllint-warnings-and-errors + +\title Unresolved Alias +\brief Property of property alias was not found. + +\section1 Unresolved Alias + +\section2 What happened? +A property alias should hold a reference to another property, see also +\l{QML Object Attributes#property-aliases}{QML Object Attributes - Property Aliases}. +In this case, it holds a reference to a property that was not found. + +\section2 Why is this bad? +Instances of components with unresolved alias will not be created at runtime: +they will be null instead. + +\section2 Example +\qml +import QtQuick + +Item { + id: someId + property int helloWorld + + property alias helloWorldAlias: helloWorld // not ok: aliases have to refer by id + property alias helloWorldAlias2: someId.helloWorlddd // not ok: no helloWorlddd in someId + property alias helloWorldAlias3: someIddd.helloWorld // not ok: someIddd does not exist +} + +\endqml +You can fix this warning by making sure that the id and the properties of the alias property +really do exist: +\qml +import QtQuick + +Item { + id: someId + property int helloWorld + + property alias helloWorldAlias: someId.helloWorld // ok: alias refers by id + property alias helloWorldAlias2: someId.helloWorld // ok: helloWorld does exist in someId + property alias helloWorldAlias3: someId.helloWorld // ok: someId does exist +} +\endqml +*/ diff --git a/src/qml/doc/src/qmllint/unresolved-type.qdoc b/src/qml/doc/src/qmllint/unresolved-type.qdoc new file mode 100644 index 0000000000..5b0a943fe8 --- /dev/null +++ b/src/qml/doc/src/qmllint/unresolved-type.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-unresolved-type.html +\ingroup qmllint-warnings-and-errors + +\title unresolved-type +\brief BRIEF + +\section1 unresolved-type + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/unused-imports.qdoc b/src/qml/doc/src/qmllint/unused-imports.qdoc new file mode 100644 index 0000000000..58821afb88 --- /dev/null +++ b/src/qml/doc/src/qmllint/unused-imports.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-unused-imports.html +\ingroup qmllint-warnings-and-errors + +\title unused-imports +\brief BRIEF + +\section1 unused-imports + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/use-proper-function.qdoc b/src/qml/doc/src/qmllint/use-proper-function.qdoc new file mode 100644 index 0000000000..d87667a6f9 --- /dev/null +++ b/src/qml/doc/src/qmllint/use-proper-function.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-use-proper-function.html +\ingroup qmllint-warnings-and-errors + +\title use-proper-function +\brief BRIEF + +\section1 use-proper-function + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/var-used-before-declaration.qdoc b/src/qml/doc/src/qmllint/var-used-before-declaration.qdoc new file mode 100644 index 0000000000..5089ecf276 --- /dev/null +++ b/src/qml/doc/src/qmllint/var-used-before-declaration.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-var-used-before-declaration.html +\ingroup qmllint-warnings-and-errors + +\title var-used-before-declaration +\brief BRIEF + +\section1 var-used-before-declaration + +\section2 What happened? +TODO + +\section2 Why is this bad? +TODO + +\section2 Example +\qml +\endqml +You can fix this warning by TODO +\qml +\endqml +*/ + diff --git a/src/qml/doc/src/qmllint/with.qdoc b/src/qml/doc/src/qmllint/with.qdoc new file mode 100644 index 0000000000..bfdde2e86b --- /dev/null +++ b/src/qml/doc/src/qmllint/with.qdoc @@ -0,0 +1,50 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qmllint-warnings-and-errors-with.html +\ingroup qmllint-warnings-and-errors + +\title With Statements +\brief With statements are strongly discouraged in QML. + +\section1 With Statements + +\section2 What happened? +The JavaScript \c{with} statement was used. + +\section2 Why is this bad? +With statements might cause false positives when analysing unqualified identifiers. Also, \c{with} +statements are +\l{https://262.ecma-international.org/#sec-with-statement}{marked as deprecated by the latest JavaScript standard}. + +\section2 Example +\qml +import QtQuick + +Item { + function f() { + with (Math) { + return PI + } + } +} +\endqml +You can fix this warning by replacing the \c{with} statement with a destructuring property, +for example: +\qml +import QtQuick + +Item { + function f() { + const { PI } = Math; + return PI + } +} + +\endqml + +\note You can find more replacement ideas +\l{https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with?retiredLocale=de#examples}{here}. +*/ + diff --git a/src/qml/doc/src/qmlsa-plugin-system.md b/src/qml/doc/src/qmlsa-plugin-system.md new file mode 100644 index 0000000000..606bda9e55 --- /dev/null +++ b/src/qml/doc/src/qmlsa-plugin-system.md @@ -0,0 +1,124 @@ +# The qmllint plugin system (Qml Static Analysis / QmlSA) + +In order to allow for users to extend qmllint and for us to separate module specific linting warnings into separate modules so they don't pollute qmllint - we created a plugin system. We will refer to it as QmlSA for short in the rest of this document. + +It currently does not have a stable API and doesn't have any public headers. + +## Anatomy of a plugin + +A basic QQmlSA plugin header looks like this: + +```cpp +#include <QtPlugin> +#include <QtCore/qobject.h> +#include <QtQmlCompiler/private/qqmlsa_p.h> + +class FooPlugin : public QObject, public QQmlSA::LintPlugin +{ + Q_OBJECT + Q_PLUGIN_METADATA(IID QmlLintPluginInterface_iid FILE "metadata.json") + Q_INTERFACES(QQmlSA::LintPlugin) + +public: + void registerPasses(QQmlSA::PassManager *manager, const QQmlSA::Element &rootElement) override; +}; +``` + +Note the reference to the metadata file. This is required in order for a QQmlSA plugin to work properly and must contain the following entries: + +```js +{ + /* The name of the plugin. Shouldn't contain any spaces, ideally with the first letter capitalized */ + "name": "PluginName", + /* Plugin author. You may or may not provide a contact email in here as well */ + "author": "John Doe", + /* A short description of the plugin - should not contain multiple lines */ + "description": "A plugin for doing X", + /* A version string. There are no strict requirements in how you use this but it should be present */ + "version": "1.0" +} +``` + +The plugin implementation itself is rather simple: + +```cpp +void FooPlugin::registerPasses(QQmlSA::PassManager *manager, const QQmlSA::Element &rootElement) +{ + // You can register either element or property passes + manager->registerElementPass(std::make_unique<SomeElementPass>(manager)); + manager->registerPropertyPass(std::make_shared<PropertyTest>(manager), "SomeModule", "SomeElement", + "somePropertyName"); + // ...or check whether a module has been imported in a certain file + manager->hasImportedModule("QtQuick.Controls") + + // You may also inspect the root element + rootElement->filePath() +} +``` + +As you can see there's calls to ``registerElementPass`` adn ``registerPropertyPass`` in the above example. We will explain both of these in more detail in the next section. + +## The passes + +The way QQmlSA plugins work is that they can register different kinds of passes which will run and iterate over the QML file being linted in different ways. + +Right now QmlSA has two types of passes: + +## Element passes (QQmlSA::ElementPass) + +These run for every QML element present in the QML scope being linted. + +### Methods + +The pass has a ``shouldRun`` and ``run`` method. + +``shouldRun`` checks whether the element is interesting to the pass at hand or not (i.e. by checking whether the element is derived from a certain type). It then returns either true or false. + +If it returns true, the ``run`` is executed. This will do the actual checking and emitting of warnings. + +**Do not do anything computationally expensive in shouldRun**. Either it has to be moved into the constructor (i.e. resolving a type that has to be checked against) or it should be done later in ``run``. This is because shouldRun will be run for every single element in the document and this can easily get too much. + +## Property passes (QQmlSA::PropertyPass) + +These run every time a property is written from, written to or has a binding created on. + +Because there are many more instances of this happening in a QML document then there are elements this pass works a bit differently than element passes. + +When registering a property pass you will need to specify what type and property the pass should work on. You may omit the type name if you're interested in all properties with a certain name (i.e. ``width``) or omit the property name if you're interested in all properties of a certain type. +**In the interest of performance you should always prefer fully specifying what you're interested in if at all possible.** + +Note that unlike with Element passes you may register the same pass multiple times with different types and properties. This is so you can use one pass across different types and properties. + +### Methods + +(All of the following only apply if it happens in the scope of the document) + +* ``onBinding`` - Called when a binding on a property gets created. +* ``onRead`` - Called when a property is read. Either as part of a binding or in a script block. +* ``onWrite`` - Called when a property is written to. Usually as part of a script block. + +All of these bindings get the following parameters: +* ``element`` - The QQmlSA::Element the property is a part of +* ``propertyName`` - The name of the property that has been changed (mainly interesting when the pass runs on multiple property names) +* ``bindingScope/readScope/writeScope`` - The actual scope the action took place. This can be different from the element in case a property is written/read to from another scope or we are talking about grouped properties. +* ``location`` - A QQmlJS::SourceLocation indicating where this took place. This is useful for printing locations in warnings + +Then there are some specific parameters: +* onBinding + * ``binding`` - A ``QQmlJSMetaPropertyBinding`` property that contains type information about the binding and what kind of binding is being dealt with + * ``value`` - A QQmlSA::Element mainly used in case it's an object binding (i.e. ``contentItem: Item {}``) +* onWrite + * ``value`` - A QQmlSA::Element containing the value that is being written to the property. It may also only contain type information if it's not a proper object. + +## API available to all passes + +In these methods passes can use the following methods to interact with qmllint further: +* ``void emitWarning(QAnyStringView message, QQmlJS::SourceLocation srcLocation = QQmlJS::SourceLocation())`` + * (should only be used in ElementPass::run and PropertyPass:onRead/Write/Binding) emits a warning highlighting the piece of code given in source location. +* ``QQmlSA::Element resolveType(QAnyStringView moduleName, QAnyStringView typeName)`` - Allows you to obtain any type from any module i.e. for later comparisons in ``shouldRun``. Use this in the constructor of your pass as doing this every time in ``shouldRun`` would be very expensive. + +## TODOs +- Stabilize the API +- Make the API public + - Don't expose QQmlJSMeta* types or QQmlJSScopes (currently ``QQmlSA::Element == QQmlJSScope``) + - Instead: Create a wrapper around these types diff --git a/src/qml/doc/src/qmlsingletons.qdoc b/src/qml/doc/src/qmlsingletons.qdoc new file mode 100644 index 0000000000..e5c95d4178 --- /dev/null +++ b/src/qml/doc/src/qmlsingletons.qdoc @@ -0,0 +1,339 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qml-singleton.html +\title Singletons in QML +\brief A guide for using singletons in QML + +In QML, a singleton is an object which is created at most once per +\l{QQmlEngine}{engine}. In this guide, we'll +\l{How can singletons be created in QML}{explain how to create} singletons +and \l{Accessing singletons}{how to use them}. We'll also provide some +best practices for working with singletons. + +\section1 How can singletons be created in QML? + +There are two separate ways of creating singletons in QML. You can either define +the singleton in a QML file, or register it from C++. + +\section2 Defining singletons in QML +To define a singleton in QML, you first have to add +\code +pragma Singleton +\endcode +to the top of your file. +There's one more step: You will need to add an entry to the QML module's +\l{Module Definition qmldir Files}{qmldir file}. + +\section3 Using qt_add_qml_module (CMake) +When using CMake, the qmldir is automatically created by \l{qt_add_qml_module}. +To indicate that the QML file should be turned into a singleton, you need to set +the \c{QT_QML_SINGLETON_TYPE} +file property on it: +\code +set_source_files_properties(MySingleton.qml + PROPERTIES QT_QML_SINGLETON_TYPE TRUE) +\endcode + +You can pass multiple files at once to \c{set_source_files_properties}: +\code +set(plain_qml_files + MyItem1.qml + MyItem2.qml + FancyButton.qml +) +set(qml_singletons + MySingleton.qml + MyOtherSingleton.qml +) +set_source_files_properties(${qml_singletons} + PROPERTIES QT_QML_SINGLETON_TYPE TRUE) +qt_add_qml_module(myapp + URI MyModule + QML_FILES ${plain_qml_files} ${qml_singletons} +) +\endcode + +\note set_source_files_properties needs to be called before \c{qt_add_qml_module} + +\section3 Without qt_add_qml_module +If you aren't using \c{qt_add_qml_module}, you'll need to manually create a +\l{Module Definition qmldir Files}{qmldir file}. +There, you'll need to mark your singletons accordingly: +\code +module MyModule +singleton MySingleton 1.0 MySingleton.qml +singleton MyOtherSingleton 1.0 MyOtherSingleton.qml +\endcode +See also \l{Object Type Declaration} for more details. + + +\section2 Defining singletons in C++ + +There are multiple ways of exposing singletons to QML from C++. The main +difference depends on whether a new instance of a class should be created when +needed by the QML engine; or if some existing object needs to be exposed to a +QML program. + +\section3 Registering a class to provide singletons + +The simplest way of defining a singleton is to have a default-constructible +class, which derives from QObject and mark it with the \l{QML_SINGLETON} and +\l{QML_ELEMENT} macros. +\code +class MySingleton : public QObject +{ + Q_OBJECT + QML_SINGLETON + QML_ELEMENT +public: + MySingleton(QObject *parent = nullptr) : QObject(parent) { + // ... + } +}; +\endcode +This will register the \c{MySingleton} class under the name \c{MySingleton} in +the QML module to which the file belongs. +If you want to expose it under a different name, you can use \l{QML_NAMED_ELEMENT} +instead. + +If the class can't be made default-constructible, or if you need access to +the \l{QQmlEngine} in which the singleton is instantiated, it is possible to +use a static create function instead. It must have the signature +\c{MySingleton *create(QQmlEngine *, QJSEngine *)}, where \c{MySingleton} is +the type of the class that gets registered. +\code +class MyNonDefaultConstructibleSingleton : public QObject +{ + Q_OBJECT + QML_SINGLETON + QML_NAMED_ELEMENT(MySingleton) +public: + MyNonDefaultConstructibleSingleton(QJSValue id, QObject *parent = nullptr) + : QObject(parent) + , m_symbol(std::move(id)) + {} + + static MyNonDefaultConstructibleSingleton *create(QQmlEngine *qmlEngine, QJSEngine *) + { + return new MyNonDefaultConstructibleSingleton(qmlEngine->newSymbol(u"MySingleton"_s)); + } + +private: + QJSValue m_symbol; +}; +\endcode + +\note The create function takes both a \l{QJSEngine} and a \l{QQmlEngine} parameter. That is +for historical reasons. They both point to the same object which is in fact a QQmlEngine. + +\section3 Exposing an existing object as a singleton + +Sometimes, you have an existing object that might have been created via +some third-party API. Often, the right choice in this case is to have one +singleton, which exposes those objects as its properties (see +\l{Grouping together related data}). +But if that is not the case, for example because there is only a single object that needs +to be exposed, use the following approach to expose an instance of type +\c{MySingleton} to the engine. +We first expose the Singleton as a \l{QML_FOREIGN}{foreign type}: +\code +struct SingletonForeign +{ + Q_GADGET + QML_FOREIGN(MySingleton) + QML_SINGLETON + QML_NAMED_ELEMENT(MySingleton) +public: + + inline static MySingleton *s_singletonInstance = nullptr; + + static MySingleton *create(QQmlEngine *, QJSEngine *engine) + { + // The instance has to exist before it is used. We cannot replace it. + Q_ASSERT(s_singletonInstance); + + // The engine has to have the same thread affinity as the singleton. + Q_ASSERT(engine->thread() == s_singletonInstance->thread()); + + // There can only be one engine accessing the singleton. + if (s_engine) + Q_ASSERT(engine == s_engine); + else + s_engine = engine; + + // Explicitly specify C++ ownership so that the engine doesn't delete + // the instance. + QJSEngine::setObjectOwnership(s_singletonInstance, + QJSEngine::CppOwnership); + return s_singletonInstance; + } + +private: + inline static QJSEngine *s_engine = nullptr; +}; +\endcode +Then we set \c{SingletonForeign::s_singletonInstance} before we start +the first engine +\code +SingletonForeign::s_singletonInstance = getSingletonInstance(); +QQmlApplicationEngine engine; +engine.loadFromModule("MyModule", "Main"); +\endcode + +\note It can be very tempting to simply use \l{qmlRegisterSingletonInstance} in +this case. However, be wary of the pitfalls of imperative type registration +listed in the next section. + +\section3 Imperative type registration +Before Qt 5.15, all types, including singletons were registered via the +\c{qmlRegisterType} API. Singletons specifically were registered via either +\l{qmlRegisterSingletonType} or \l{qmlRegisterSingletonInstance}. Besides the +minor annoyance of having to repeat the module name for each type and the forced +decoupling of the class declaration and its registration, the major problem with +that approach was that it is tooling unfriendly: It was not statically possible +to extract all the necessary information about the types of a module at compile +time. The declarative registration solved this issue. + +\note There is one remaining use case for the imperative \c{qmlRegisterType} API: +It is a way to expose a singleton of non-QObject type as a \c{var} property via +\l{qmlRegisterSingletonType}{the QJSValue based \c{qmlRegisterSingletonType} overload} +. Prefer the alternative: Expose that value as the property of a (\c{QObject}) based +singleton, so that type information will be available. + +\section2 Accessing singletons +Singletons can be accessed both from QML as well as from C++. In QML, you need +to import the containing module. Afterwards, you can access the singleton via its +name. Reading its properties and writing to them inside JavaScript contexts is +done in the same way as with normal objects: + +\code +import QtQuick +import MyModule + +Item { + x: MySingleton.posX + Component.onCompleted: MySingleton.ready = true; +} +\endcode + +Setting up bindings on a singletons properties is not possible; however, if it +is needed, a \l{Binding} element can be used to achieve the same result: +\code +import QtQuick +import MyModule + +Item { + id: root + Binding { + target: MySingleton + property: "posX" + value: root.x + } +} +\endcode + +\note Care must be taken when installing a binding on a singleton property: If +done by more than one file, the results are not defined. + +\section1 Guidelines for (not) using singletons + +Singletons allow you to expose data which needs to be accessed in multiple places +to the engine. That can be globally shared settings, like the spacing between +elements, or data models which need to be displayed in multiple places. +Compared to context properties which can solve a similar use case, +they have the benefit of being typed, being supported by tooling like the +\l{\QMLLS Reference}{\QMLLS}, and they are also generally faster at runtime. + +It is recommended not to register too many singletons in a module: Singletons, +once created, stay alive until the engine itself gets destroyed +and come with the drawbacks of shared state as they are part of the global state. +Thus consider using the following techniques to reduce the amount of singletons +in your application: + +\section2 Grouping together related data +Adding one singleton for each object which you want to expose adds quite some boiler plate. +Most of the time, it makes more sense to group data you want to expose together as properties +of a single singleton. Assume for instance that you want to create an ebook reader +where you need to expose three \l{QAbstractItemModel}{abstract item models}, one +for local books, and two for remote sources. Instead of repeating the process +for \l{Exposing an existing object as a singleton}{exposing existing objects} +three times, you can instead create one singleton and set it up before starting +the main application: +\code +class GlobalState : QObject +{ + Q_OBJECT + QML_ELEMENT + QML_SINGLETON + Q_PROPERTY(QAbstractItemModel* localBooks MEMBER localBooks) + Q_PROPERTY(QAbstractItemModel* digitalStoreFront MEMBER digitalStoreFront) + Q_PROPERTY(QAbstractItemModel* publicLibrary MEMBER publicLibrary) +public: + QAbstractItemModel* localBooks; + QAbstractItemModel* digitalStoreFront; + QAbstractItemModel* publicLibrary +}; + +int main() { + QQmlApplicationEngine engine; + auto globalState = engine.singletonInstance<GlobalState *>("MyModule", "GlobalState"); + globalState->localBooks = getLocalBooks(); + globalState->digitalStoreFront = setupLoalStoreFront(); + globalState->publicLibrary = accessPublicLibrary(); + engine.loadFromModule("MyModule", "Main"); +} +\endcode + +\section2 Use object instances +In the last section, we had the example of exposing three models as members of a +singleton. That can be useful when either the models need to be used in multiple +places, or when they are provided by some external API over which we have no +control. However, if we need the models only in a single place it might make +more sense have them as an instantiable type. Coming back to the previous example, +we can add an instantiable RemoteBookModel class, and then instantiate it inside +the book browser QML file: + + +\code +// remotebookmodel.h +class RemoteBookModel : public QAbstractItemModel +{ + Q_OBJECT + QML_ELEMENT + Q_PROPERTY(QUrl url READ url WRITE setUrl NOTIFY urlChanged) + // ... +}; + +// bookbrowser.qml +Row { + ListView { + model: RemoteBookModel { url: "www.public-lib.example"} + } + ListView { + model: RemoteBookModel { url: "www.store-front.example"} + } +} + +\endcode + +\section2 Passing initial state + +While singletons can be used to pass state to QML, they are wasteful when the +state is only needed for the initial setup of the application. In that case, it +is often possible to use \l{QQmlApplicationEngine::setInitialProperties}. +You might for instance want to set \l{Window::visibility} to fullscreen if +a corresponding command line flag has been set: +\code +QQmlApplicationEngine engine; +if (parser.isSet(fullScreenOption)) { + // assumes root item is ApplicationWindow + engine.setInitialProperties( + { "visibility", QVariant::fromValue(QWindow::FullScreen)} + ); +} +engine.loadFromModule("MyModule, "Main"); +\endcode + +*/ diff --git a/src/qml/doc/src/qmltypereference.qdoc b/src/qml/doc/src/qmltypereference.qdoc index ae36ebbcc9..67dd6a9fea 100644 --- a/src/qml/doc/src/qmltypereference.qdoc +++ b/src/qml/doc/src/qmltypereference.qdoc @@ -1,39 +1,15 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\qmlmodule QtQml 2.\QtMinorVersion -\title Qt QML QML Types +\qmlmodule QtQml +\title Qt Qml QML Types \ingroup qmlmodules -\brief List of QML types provided by the Qt QML module +\brief List of QML types provided by the Qt Qml module. -The \l{Qt QML} module provides the definition and implementation of various -convenience types which can be used with the QML language, including some -elementary QML types which can provide the basis for further extensions to the +The \l{Qt Qml} module provides the definition and implementation of various +convenience types that can be used with the QML language. This includes +elementary QML types, which can provide the basis for further extensions to the QML language. The \l QtObject and \l Component object types are non-visual and provide building-blocks for extensions to QML. @@ -43,38 +19,57 @@ The types provided by the \c QtQml module are only available in a QML document if that document imports the \c QtQml namespace (or if the document imports the \c QtQuick namespace, as noted below). -The current version of the \c QtQml module is version 2.\QtMinorVersion, and -thus it may be imported via the following statement: +To use the module, import the \c QtQml module with the following statement: -\qml \QtMinorVersion -import QtQml 2.\1 +\qml +import QtQml \endqml -Most clients will never need to use the \c QtQml import, as all of the types -are also provided by the \c QtQuick namespace which may be imported as -follows: +Many clients will never need to use the \c QtQml module directly, but will rather +import it indirectly via the \c QtQuick module as follows: -\qml \QtMinorVersion -import QtQuick 2.\1 +\qml +import QtQuick \endqml -See the \l{Qt Quick} module documentation for more information about the \c -QtQuick namespace and what it provides to QML application developers. +See the \l{Qt Quick} module documentation for more information about its types. + +The QML types for creating lists and models, such as \l ListModel and +\l ListElement, belong to a submodule, \l{Qt QML Models QML Types}{QtQml.Models}. -The QML types for creating lists and models, such as \l ListModel and \l -ListElement, are moved to a submodule, \c QtQml.Models. The \l{Qt QML Models QML -Types}{Qt QML Models} page has more information. +The \l WorkerScript QML type belongs to the submodule +\l{Qt QML WorkerScript QML Types}{QtQml.WorkerScript}. +Both, \l{Qt QML Models QML Types}{QtQml.Models} and +\l{Qt QML WorkerScript QML Types}{QtQml.WorkerScript} are automatically imported +whenever you import \c QtQml. All their types are then available, too. -The documentation for the types below applies equally to the types of the same -name provided by the \l{Qt Quick} module, as they are in fact identical. +The \l{Qt Quick} module automatically imports \c QtQml and, transitively, +\l{Qt QML Models QML Types}{QtQml.Models} and +\l{Qt QML WorkerScript QML Types}{QtQml.WorkerScript}, making all their types +available whenever you import \c QtQuick. -\section1 Basic Types +\section1 Value Types -The following \l{qtqml-typesystem-basictypes.html}{QML basic types} are +The following \l{qtqml-typesystem-valuetypes.html}{QML Value Types} are provided: -\annotatedlist qtqmlbasictypes +\annotatedlist qtqmlvaluetypes + +\section1 Sequence Types + +The following \l{QML Sequence Types}{QML sequence types} are provided by the Qt +QML module in addition to the ones registered with each value type and object +type: + +\list + \li \c {std::vector<QString>} + \li \c {std::vector<QUrl>} + \li \c {std::vector<bool>} + \li \c {std::vector<int>} + \li \c {std::vector<float>} + \li \c {std::vector<double>} +\endlist \section1 Object Types @@ -84,13 +79,14 @@ provided: */ /*! -\qmlbasictype date -\ingroup qtqmlbasictypes -\ingroup qtquickbasictypes +\qmlvaluetype date +\ingroup qmlvaluetypes \brief a date value. The \c date type refers to a date value, including the time of the day. +Properties of type \c date default to an invalid value. + To create a \c date value, specify it as a "YYYY-MM-DDThh:mm:ss.zzzZ" string. (The T is literal, YYYY is a full year number, MM and DD are month and day numbers, hh, mm and ss are hours, minutes and seconds, with .zzz as @@ -98,7 +94,7 @@ milliseconds and Z as time-zone offset. The T and following time are optional. If they are omitted, the date is handled as the start of UTC's day, which falls on other dates in some time-zones. When T is included, the :ss.zzz or just .zzz part can be omitted. With or without those, the zone offset can be -omitted, in which case local time is used.) For example: +omitted, in which case local time is used.) For example: \qml MyDatePicker { minDate: "2000-01-01 0:0"; maxDate: "2020-12-31 23:59" } @@ -117,16 +113,15 @@ or a relevant time-zone and selecting a time of day (such as noon) that reliably exists (daylight-savings transitions skip an hour, near one end or the other of a day). -This basic type is provided by the QML language. It can be implicitly converted +This value type is provided by the QML language. It can be implicitly converted to a \l{QtQml::Date}{Date} object. -\sa {QtQml::Date}{QML Date object}, {QML Basic Types} +\sa {QtQml::Date}{QML Date object}, {QML Value Types} */ /*! -\qmlbasictype point -\ingroup qtqmlbasictypes -\ingroup qtquickbasictypes +\qmlvaluetype point +\ingroup qtqmlvaluetypes \brief a value with x and y attributes. The \c point type refers to a value with \c x and \c y attributes. @@ -148,17 +143,20 @@ When integrating with C++, note that any QPoint or QPointF value converted into a \c point value. When a \c point value is passed to C++, it is automatically converted into a QPointF value. -\sa{QML Basic Types} +Properties of type \c point are \c {Qt.point(0, 0)} by default. + +\sa{QML Value Types} */ /*! -\qmlbasictype size -\ingroup qtqmlbasictypes -\ingroup qtquickbasictypes -\brief a value with width and height attributes +\qmlvaluetype size +\ingroup qtqmlvaluetypes +\brief a value with width and height attributes. The \c size type refers to a value with has \c width and \c height attributes. +Properties of type \c size have \c {Qt.size(-1, -1)} as default value. + For example, to read the \c width and \c height values of the \l {Image::sourceSize} size-type property: @@ -186,17 +184,19 @@ When integrating with C++, note that any QSize or QSizeF value converted into a \c size value, and vice-versa. When a \c size value is passed to C++, it is automatically converted into a QSizeF value. -\sa{QML Basic Types} +\sa{QML Value Types} */ /*! -\qmlbasictype rect -\ingroup qtqmlbasictypes -\ingroup qtquickbasictypes +\qmlvaluetype rect +\ingroup qtqmlvaluetypes \brief a value with x, y, width and height attributes. The \c rect type refers to a value with \c x, \c y, \c width and \c height attributes. +Properties of type \c rect are \c {Qt.rect(0, 0, 0, 0)} by default. This is an +empty rectangle at the coordinate origin. + For example, to read the \c width and \c height values of the \l Item \l {Item::childrenRect.x}{childrenRect} rect-type property: @@ -229,5 +229,5 @@ When integrating with C++, note that any QRect or QRectF value converted into a \c rect value, and vice-versa. When a \c rect value is passed to C++, it is automatically converted into a QRectF value. -\sa{QML Basic Types} +\sa{QML Value Types} */ diff --git a/src/qml/doc/src/qt6-changes.qdoc b/src/qml/doc/src/qt6-changes.qdoc new file mode 100644 index 0000000000..4f95103a4f --- /dev/null +++ b/src/qml/doc/src/qt6-changes.qdoc @@ -0,0 +1,257 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qml-changes-qt6.html + \title Changes to Qt QML + \ingroup changes-qt-5-to-6 + \brief Migrate Qt QML to Qt 6. + + Qt 6 is a result of the conscious effort to make the framework more + efficient and easy to use. + + We try to maintain binary and source compatibility for all the public + APIs in each release. But some changes were inevitable in an effort to + make Qt a better framework. + + In this topic we summarize those changes in Qt QML, and provide + guidance to handle them. + + \section1 QML language + + \section2 URL resolution + + In Qt 5, relative urls were often, albeit inconsistently, directly resolved, especially when + assigned to an url property. In Qt 6 this is no longer the case. + + If you had a QML file stored under "/home/qml/example.qml", and "example.qml" contained + \code + property url imageFolder: "./images" + \endcode + then the url property would store the URL "/home/qml/images". This made it impossible to use + relative URLs in QML in this way, so in Qt 6, the URL stays relative, and only gets resolved + when this is required (e.g. when it is used as the source of an Image component). + If you depend on the old behavior, you can use \c Qt.resolvedUrl + + For example, if you have code like + + \code + property url imageFolder: "./images" + \endcode + + you can rewrite it as + + \code + property url imageFolder: Qt.resolvedUrl("./images") + \endcode + + Qt.resolvedUrl can be used in both Qt 5 and 6. + + \section2 Variant Properties + + \c variant properties, which have been marked as obsolete since Qt 5, are now treated in exactly + the same way as \c var properties. + Code that relied on implicit string conversion triggered on assignment to variant properties + should be updated to explicitly create an object of the correct type. + + For example, if you have code like + + \code + property variant myColor: "red" + \endcode + + you can rewrite it as + + \code + property variant myColor: Qt.color("red") + \endcode + + Implicit conversions were done for strings that could be parsed as + \list + \li color (use Qt.color instead), + \li date (use the Date object instead), + \li rect (use Qt.rect instead) and + \li size (use Qt.size instead) + \endlist + + \c variant still remains a deprecated keyword in Qt 6, though new code is strongly encouraged to + use \c var properties instead. + + \note If the type of the property is known not to change, use a property of the concrete type, + instead of a \c var property. + + \note These conversions were also applied to \c QVariant properties of classes registered with + the engine. As with \c variant properties, code that relied on implicit string conversions need + to use the corresponding functions of the Qt object. + + \section1 Source Incompatible API Changes + + \section2 Changed API + + \c QQmlListProperty's \c CountFunction and \c AtFunction have been changed to use \c qsizetype + instead of \c int to align with the corresponding changes in Qt's containers. + + For example, if you have code like + + \code + int myCountFunction(QQmlListProperty<MyType> *); + MyType *myAtFunction(QQmlListProperty<MyType> *, int); + + QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction, + &myAtFunction); + \endcode + + you can rewrite it as + + \code + qsizetype myCountFunction(QQmlListProperty<MyType> *); + MyType *myAtFunction(QQmlListProperty<MyType> *, qsizetype); + + QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction, + &myAtFunction); + \endcode + + Code which needs to supports both Qt 5 and Qt 6 can either use a typedef which is \c int in Qt 5 + and \c qsizetype in Qt 6, or use \c QList::size_type, which already is such a type alias. + + \section2 Removed API + + Various deprecated functions have been removed. + + \list + \li The QQmlListProperty constructor taking a reference has been removed. + + For example, if you have code like + + \code + QQmlListProperty<QObject>(owner, owner->objectList); + \endcode + + you can rewrite it as + + \code + QQmlListProperty<QObject>(owner, &owner->objectList); + \endcode + + \li The functions \c qmlDebug, \c qmlInfo, \c qmlWarning, \c qmlContext and \c qmlEngine used + to exist both in the global namespace (or Qt namespace in namespaced builds), and in the \c + QtQml namespace. These functions now exist only in the global namespace. + + For example, if you have code like + + \code + QQmlEngine *engine = QtQml::qmlEngine(qmlObject); + \endcode + + you can rewrite it as + + \code + QQmlEngine *engine = qmlEngine(qmlObject); + \endcode + + \li The \c qmlRegisterType overload taking no arguments has been removed. Use + \c qmlRegisterAnonymousType instead, or switch to declarative type registration with + \c QML_ANONYMOUS. + + For example, if you have code like + + \code + class AnonymousType : public QObject { + // ... + }; + + qmlRegisterType<AnonymousType>(); + \endcode + + you can rewrite it as + + \code + class AnonymousType : public QObject { + // ... + }; + + qmlRegisterAnonymousType<AnonymousType>("MyModule", 1); + \endcode + + Or alternatively + \code + class AnonymousType : public QObject { + QML_ANONYMOUS + // ... + }; + \endcode + + \li The overloads of \c qmlRegisterExtendedType and \c qmlRegisterInterface + which take no version argument have been removed. Use the overloads providing a + version, or switch to declarative type registration with QML_EXTENDED + and QML_INTERFACE. + + For example, if you have code like + + \code + struct GreetInterface + { + virtual ~GreetInterface(); + virtual void greet(); + }; + Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface") + + qmlRegisterInterface<GreetInterface>("Greeter"); + \endcode + + you can rewrite it as + + \code + struct GreetInterface + { + virtual ~GreetInterface(); + virtual void greet(); + }; + Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface") + + qmlRegisterInterface<GreetInterface>("Greeter", 1); + \endcode + + Alternatively + + \code + struct GreetInterface + { + QML_INTERFACE(Greeter) + virtual ~GreetInterface(); + virtual void greet(); + }; + Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface") + \endcode + + \note In new code, declarative type registration should be preferred. + + \li The function \c QJSValue::engine has been removed. If access to the engine is required, a + reference to it must be stored instead. + + \li \c qmlAttachedPropertiesObjectById and \c qmlAttachedPropertiesObject(int *, const QObject *, + const QMetaObject *, bool) have been removed. Use the + \c qmlAttachedPropertiesObject(QObject *, QQmlAttachedPropertiesFunc, bool) overload of + \c qmlAttachedPropertiesObject instead. + + \li \c QJSEngine::installTranslatorFunctions has been removed. \c QJSEngine::installExtensions + is available as a replacement. + + For example, if you have code like + + \code + QJSEngine engine; + engine.installTranslatorFunctions(); + \endcode + + you can rewrite it as + + \code + QJSEngine engine; + engine.installExtensions(QJSEngine::TranslationExtension); + \endcode + + \endlist + + +*/ diff --git a/src/qml/doc/src/qtqml-cpp.qdoc b/src/qml/doc/src/qtqml-cpp.qdoc index 2c4d2a5ade..236b90ab0a 100644 --- a/src/qml/doc/src/qtqml-cpp.qdoc +++ b/src/qml/doc/src/qtqml-cpp.qdoc @@ -1,48 +1,13 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \module QtQml -\title Qt QML C++ Classes +\title Qt Qml C++ Classes \ingroup modules +\qtcmakepackage Qml \qtvariable qml -\brief The C++ API provided by the Qt QML module. +\brief The C++ API provided by the Qt Qml module. -To include the definitions of the module's classes, use the -following directive: - -\snippet code/doc_src_qtqml.cpp 0 - -\if !defined(qtforpython) -To link against the module, add this line to your \l qmake \c -.pro file: - -\snippet code/doc_src_qtqml.pro 0 -\endif - -For more information on the Qt QML module, see the -\l{Qt QML} module documentation. +For more information on the Qt Qml module, see the +\l{Qt Qml} module documentation. */ diff --git a/src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc b/src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc new file mode 100644 index 0000000000..3631a85b5f --- /dev/null +++ b/src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc @@ -0,0 +1,123 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-qtquick-compiler-tech.html +\ingroup overviews +\title Qt Quick Compiler +\brief Overview of Qt Quick Compiler components + +Qt Quick Compiler lets you process QML and JavaScript code at compile +time, rather than at run time. This allows for: + +\list + \li Faster application startup + \li Faster evaluation of bindings and functions +\endlist + +The Qt Quick Compiler consist of two components: +\list + \li \l {QML type compiler} + \li \l {QML script compiler} +\endlist + +\note \e qmltc, \e qmlsc and \l qmlcachegen are internal build tools. If you +need to care about their invocation, you are either writing a build system, or +you are doing something wrong. + +\section1 The QML type compiler + +The \l{QML type compiler}, \e(qmltc) compiles QML types to C++ classes. These C++ +classes are then added to your application and can be instantiated from other +C++ code. This way you can avoid much of the overhead of using \l{QQmlComponent} +to create instances of your QML types. In order to benefit from \l qmltc, you +need to adapt your C++ code and make use of the new classes. + +\l qmltc can only compile a QML document if it completely understands its +structure. It will fail if an unsupported language feature is encountered. +It does not have to understand the JavaScript code in bindings and functions, +though. + +\section1 The QML script compiler + +The \l{QML script compiler}, (\e qmlsc and \e qmlcachegen) compiles bindings and +functions to both, an efficient byte code and C++ functions. This process +automatically happens behind the scenes if you are using \l{qt_add_qml_module} +to specify your QML modules. For more information about available options to +control different aspects of QML compilation, see +\l {Caching compiled QML sources}. + +At compile time, for each QML or JavaScript +document a corresponding C++ file is created and built into the application. The +C++ file then contains a \e{QML compilation unit}, which consists of: + +\list + \li An efficient representation of the document structure + \li Byte code for all functions and bindings in the document + \li C++ code for functions and bindings the compiler fully understands +\endlist + +The QML engine then refrains from compiling the QML or JavaScript source code +at run time and instead uses the pre-built compilation unit to load the QML +component and its functions and bindings more quickly. The functions and +bindings that were compiled to C++ can also be executed faster. Other bindings +and functions are either interpreted directly from the byte code, or compiled +to machine code via a JIT compilation step at run time. At compile time, more +involved type analysis can be performed. Therefore, the generated C++ code +is generally more efficient than the result of the JIT compilation. + +There are limitations on what JavaScript constructs can be compiled to C++. +For more information, see \l {Limitations when compiling JavaScript to C++}. + +\e{qmlsc} will be used instead of \e{qmlcachegen} if the Qt Quick Compiler +Extensions are installed. It has the following additional features over +\e{qmlcachegen}: + +\list + \li It can compile documents in Direct Mode. In that case, the C++ headers + of the types underpinning other QML components are directly included + and the methods of those types are directly called. Conversely, in + Indirect Mode, \e qmlcachegen or \e qmlsc call methods through the + lookup mechanism which is also used in the interpreter and JIT. + \li It can compile documents in Static Mode. In that case, \e qmlsc assumes + that no properties of any types exposed to C++ can be shadowed by + derived types. This allows for more bindings and functions to be + compiled, but generates invalid code if any properties are shadowed. +\endlist + +Instead of producing C++ as output, \l {qmlsc} and \l {qmlcachegen} can also +generate .qmlc, .jsc and .mjsc "cache files". These still contain a QML +compilation unit each, and can be loaded by the QML engine to avoid +re-compilation. They can only contain document structure and byte code, though. +Compilation of bindings and functions to C++ is omitted if cache files are +produced. Neither the CMake nor the qmake build system offered by Qt expose this +functionality. + +\section1 Summary + +The following table summarizes the differences between \l{qmltc}, +\l{qmlcachegen} and \l{qmlsc}: + +\table + \header + \li \e qmltc + \li \e qmlcachegen + \li \e qmlsc + \row + \li Compiles QML types to C++ classes + \li Compiles QML documents to QML compilation units + \li Compiles QML documents to QML compilation units + \row + \li Generated output acts as faster alternative to + \l{QQmlComponent}-based object creation. + \li Generated output is used internally by the QML engine to avoid + re-compilation, and to speed up execution. + \li Generated output is used internally by the QML engine to avoid + re-compilation, and to speed up execution. Direct Mode and Static + Mode can further accelerate your application. + \row + \li Available for all versions of Qt + \li Available for all versions of Qt + \li Available for commercial customers +\endtable +*/ diff --git a/src/qml/doc/src/qtqml-tooling.qdoc b/src/qml/doc/src/qtqml-tooling.qdoc new file mode 100644 index 0000000000..45e4528a6b --- /dev/null +++ b/src/qml/doc/src/qtqml-tooling.qdoc @@ -0,0 +1,48 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! +\group qtqml-tooling +\title Qt Qml Tooling +\brief List of Qt Qml Tools and Utilities + +The Qt Qml module provides a range of tools and utilities that enhance +the developer and designer experience and includes some internal tools +used by Qt. The following sections offer a concise overview of these tools +and utilities, along with links to additional information about each of them. + +\section1 Developer Tools + +A set of tools provided by the Qt Qml module that aim to facilitate a QML developer's life +during various phases of development. These tools are: + +\list + \li \l {qmllint Reference}{qmllint} + \li \l {qmlformat} + \li \l {\QMLLS Reference}{qmlls} + \li \l {qmlprofiler} +\endlist + +\section1 Designer Tools + +The Qt Qml module also provides user facing tools which can increase the productivity +of designers by helping them with fast prototyping. These tools are: + +\list + \li \l{qml} + \li \l{qmlpreview} +\endlist + +\section1 Internal Tools + +Certain utility tools are not intended for direct user interaction. +Instead, they are all meant to be invoked by the build system, +augmenting its functionality and capabilities. + +\list + \li \l {QML type compiler} + \li \l {QML script compiler} + \li \l {qmltyperegistrar} + \li \l {qmlimportscanner} +\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..c8a99f1a37 --- /dev/null +++ b/src/qml/doc/src/qtqml-writing-a-module.qdoc @@ -0,0 +1,461 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-writing-a-module.html +\title Writing QML Modules +\brief How to write a custom QML module. + +You should 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 Combine QML files and C++-based types in the same module. +\li Invoke \l {Ahead-of-Time-Compilation}{qmlcachegen} on all + QML files. +\li Use the pre-compiled versions of QML files inside the module. +\li Provide the module both in the physical and in the + \l{The Qt Resource System}{resource file system}. +\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> +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 Versions + +QML has a complex system to assign versions to components and modules. In most +cases you should ignore all of it by: + +\list 1 + \li Never adding a version to your import statements + \li Never specifying any versions in \l{qt_add_qml_module} + \li Never using \l{QML_ADDED_IN_VERSION} or \l{QT_QML_SOURCE_VERSIONS} + \li Never using \l{Q_REVISION} or the \c{REVISION()} attribute in \l{Q_PROPERTY} + \li Avoiding unqualified access + \li Generously using import namespaces +\endlist + +Versioning is ideally handled outside the language itself. You may, for example, +keep separate \l{QML Import Path}{import paths} for different sets of QML modules. +Or you may use a versioning mechanism provided by your operating system to install +or uninstall packages with QML modules. + +In some cases, Qt's own QML modules may show different behavior, depending on what +version is imported. In particular, if a property is added to a QML component, and +your code contains unqualified access to another property of the same name, your +code will break. In the following example, the code will behave differently +depending on the version of Qt, because the \l [QML] {Rectangle::}{topLeftRadius} +property was added in Qt 6.7: + +\qml +import QtQuick + +Item { + // property you want to use + property real topLeftRadius: 24 + + Rectangle { + + // correct for Qt version < 6.7 but uses Rectangle's topLeftRadius in 6.7 + objectName: "top left radius:" + topLeftRadius + } +} +\endqml + +The solution here is to avoid the unqualified access. \l{qmllint Reference}{qmllint} can be used to +find such problems. The following example accesses the property you actually mean +in a safe, qualified way: + +\qml +import QtQuick + +Item { + id: root + + // property you want to use + property real topLeftRadius: 24 + + Rectangle { + + // never mixes up topLeftRadius with unrelated Rectangle's topLeftRadius + objectName: "top left radius:" + root.topLeftRadius + } +} +\endqml + +You can also avoid the incompatibility by importing a specific version of QtQuick: + +\qml +// make sure Rectangle has no topLeftRadius property +import QtQuick 6.6 + +Item { + property real topLeftRadius: 24 + Rectangle { + objectName: "top left radius:" + topLeftRadius + } +} +\endqml + +Another problem solved by versioning is the fact that QML components imported by +different modules may shadow each other. In the following example, if \c{MyModule} were +to introduce a component named \c{Rectangle} in a newer version, the \c{Rectangle} +created by this document would not be a \c {QQuickRectangle} anymore, but rather the +new \c{Rectangle} introduced by \c{MyModule}. + +\qml +import QtQuick +import MyModule + +Rectangle { + // MyModule's Rectangle, not QtQuick's +} +\endqml + +A good way to avoid the shadowing would be to import \c{QtQuick} and/or \c{MyModule} +into type namespaces as follows: + +\qml +import QtQuick as QQ +import MyModule as MM + +QQ.Rectangle { + // QtQuick's Rectangle +} +\endqml + +Alternatively, if you import \c{MyModule} with a fixed version, and the new component +receives a correct version tag via \l{QML_ADDED_IN_VERSION} or \l{QT_QML_SOURCE_VERSIONS}, +the shadowing is also avoided: + +\qml +import QtQuick 6.6 + +// Types introduced after 1.0 are not available, like Rectangle for example +import MyModule 1.0 + +Rectangle { + // QtQuick's Rectangle +} +\endqml + +For this to work, you need to use versions in \c{MyModule}. There are a few things +to be aware of. + +\section2 If you add versions, add them everywhere + +You need to add a \c{VERSION} attribute to \l{qt_add_qml_module}. The version should +be the most recent version provided by your module. Older minor versions of the same +major version will automatically be registered. For older major versions, see +\l{#Exporting Multiple Major Versions from The Same Module}{below}. + +You should add \l{QML_ADDED_IN_VERSION} or \l{QT_QML_SOURCE_VERSIONS} to every type +that was \e not introduced in version \c{x.0} of your module, where \c{x} is the current +major version. + +If you forget to add a version tag, the component will be available in all versions, +making the versioning ineffective. + +However, there is no way to add versions to properties, methods, and signals defined +in QML. The only way to version QML documents is to add a new document with separate +\l{QT_QML_SOURCE_VERSIONS} for each change. + +\section2 Versions are not transitive + +If a component from your module \c{A} imports another module \c{B} and instantiates a type +from that module as the root element, then the import version of \c{B} is relevant for the +properties available from the resulting component, no matter what version of \c{A} is +imported by a user. + +Consider a file \c{TypeFromA.qml} with version \c{2.6} in module \c{A}: + +\qml +import B 2.7 + +// Exposes TypeFromB 2.7, no matter what version of A is imported +TypeFromB { } +\endqml + +Now consider a user of \c{TypeFromA}: + +\qml +import A 2.6 + +// This is TypeFromB 2.7. +TypeFromA { } +\endqml + +The user hopes to see version \c{2.6} but actually gets version +\c{2.7} of the base class \c{TypeFromB}. + +Therefore, in order to be safe, you not only have to duplicate your QML files and +give them new versions when you add properties yourself, but also when you bump +versions of modules you import. + +\section2 Qualified access does not honor versioning + +Versioning only affects unqualified access to members of a type or the type itself. +In the example with \c{topLeftRadius}, if you write \c{this.topLeftRadius}, the +property will be resolved if you're using Qt 6.7, even if you \c{import QtQuick 6.6}. + +\section2 Versions and revisions + +With \l{QML_ADDED_IN_VERSION}, and the two-argument variants of \l{Q_REVISION} and +\l{Q_PROPERTY}'s \c{REVISION()}, you can only declare versions that are tightly coupled +to the \l{QMetaObject}{metaobject's} revision as exposed in \l{QMetaMethod::revision} +and \l{QMetaProperty::revision}. This means all the types in your type hierarchy have +to follow the same versioning scheme. This includes any types provided by Qt itself +that you inherit from. + +With \l{QQmlEngine::}{qmlRegisterType} and related functions you can register any mapping +between metaobject revisions and type versions. You then need to use the one-argument forms +of \l{Q_REVISION} and the \c{REVISION} attribute of \l{Q_PROPERTY}. However, this +can become rather complex and confusing and is not recommended. + +\section2 Exporting multiple major versions from the same module + +\l qt_add_qml_module by default considers the major version given in its +VERSION 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 versions using \l qmlRegisterModule() 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[QtQml]{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. + +If \l{QTP0001} policy is set to \c NEW, the \c RESOURCE_PREFIX argument +for \c{qt_add_qml_module()} defaults to \c{/qt/qml/}, therefore your +modules are placed in \c{:/qt/qml/} in the resource file system. +This is part of the default \l{QML Import Path}, but not used by Qt +itself. For modules to be used within your application, this is the right place. + +If you have instead specified a custom \c RESOURCE_PREFIX, you have to add the +custom resource prefix to the \l{QML Import Path}. You can also add multiple +resource prefixes: + +\badcode +QQmlEngine qmlEngine; +qmlEngine.addImportPath(QStringLiteral(":/my/resource/prefix")); +qmlEngine.addImportPath(QStringLiteral(":/other/resource/prefix")); +// Use qmlEngine to load the main.qml file. +\endcode + +This might be necessary when using third party libraries to avoid module name +conflicts. Using a custom resource prefix is discouraged in all other cases. + +The path \c :/qt-project.org/imports/ is also part of the default \l{QML Import +Path}. For modules that are heavily re-used across different projects or Qt +versions, \c :/qt-project.org/imports/ is acceptable as resource prefix. Qt's +own QML modules are placed there, though. You have to be careful not to +overwrite them. + +Do not add any unnecessary import paths. The QML engine might find your modules +in the wrong place then. This can trigger problems which can only be reproduced +in specific environments. + +\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 your 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 68d2b66950..f44a7130e6 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -1,167 +1,104 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-index.html -\title Qt QML -\brief The Qt QML module defines and implements the QML language +\title Qt Qml +\brief The Qt Qml module implements the QML language and offers APIs to register + types for it. -The Qt QML module provides a framework for developing applications and libraries -with the \l{QML Applications}{QML language}. It defines and implements the +The Qt Qml module provides a framework for developing applications and libraries +with the \l{The QML Reference}{QML language}. It defines and implements the language and engine infrastructure, and provides an API to enable application -developers to extend the QML language with custom types and integrate QML code -with JavaScript and C++. The Qt QML module provides both a \l{Qt QML QML Types} -{QML API} and a \l{Qt QML C++ Classes}{C++ API}. +developers to \l{Registering QML Types and QML Modules}{register} custom QML types +and modules and integrate QML code with JavaScript and C++. The Qt Qml module +provides both a \l{Qt Qml QML Types}{QML API} and a +\l{Qt Qml C++ Classes}{C++ API}. -Note that while the Qt QML module provides the language and infrastructure -for QML applications, the \l{Qt Quick} module provides many visual components, -model-view support, an animation framework, and much more for building user -interfaces. +\section1 Using the Module -For those new to QML and Qt Quick, please see -\l{QML Applications} -for an introduction to writing QML applications. +\section2 QML API -\section1 Getting Started +\include {module-use.qdocinc} {using the qml api} {QtQml} -To include the definitions of the module's classes, use the -following directive: - -\code -#include <QtQml> -\endcode +The Qt Qml module contains the QML framework and important QML types used in +applications. The constructs of QML are described in the \l{The QML Reference}. -The QML types in Qt QML are available through the \c QtQml import. To use the -types, add the following import statement to your .qml file: +The \l{Qt Qml QML Types}{QML API} of the Qt Qml module provides a number of +\l{qtqml-typesystem-objecttypes.html}{QML Object Types}, +\l{qtqml-typesystem-valuetypes.html}{QML Value Types} and namespaces. -\qml \QtMinorVersion -import QtQml 2.\1 -\endqml +\section2 C++ API +\include {module-use.qdocinc} {using the c++ api} -To link against the module, add this line to your \l qmake \c -.pro file: +The C++ API contains some +\l{Important C++ Classes Provided By The Qt Qml Module}{important classes} +you should get familiar with. It also provides +\l{Integrating with JavaScript values from C++}{types} to hold JavaScript +values. -\code -QT += qml -\endcode +\section3 Building with CMake -\section1 QML and QML Types +\include {module-use.qdocinc} {building with cmake} {Qml} -The Qt QML module contains the QML framework and important QML types used in -applications. The constructs of QML are described in the \l{The QML Reference}. +To provide foreign QML type support for a non-QML library, locate +the \c QmlIntegration module as follows: -In addition to the \l{QML Basic Types}, the module comes with -the following QML object types: -\list -\li \l Component -\li \l QtObject -\li \l Binding -\li \l Connections -\li \l Timer -\endlist +\snippet code/doc_src_qtqml.cmake 1 -The \l{QtQml::Qt}{Qt} global object provides useful enums and functions -for various QML types. +See \l{qt6_generate_foreign_qml_types} for details. -\section2 Lists and Models +\section3 Building with qmake -New in Qt 5.1, the model types are moved to a submodule, \c QtQml.Models. The -\l{Qt QML Models QML Types}{Qt QML Models} page has more information. +\include {module-use.qdocinc} {building_with_qmake} {qml} -\list -\li \l DelegateModel -\li \l DelegateModelGroup -\li \l ListElement -\li \l ListModel -\li \l ObjectModel -\endlist +\section1 Registering QML Types and QML Modules -\section1 JavaScript Environment for QML Applications +In order to register types for usage with QML you first need to define a +\l{Writing QML Modules}{QML module}, preferably using \l{qt_add_qml_module} in CMake. +Then, you can add C++ headers to your new module, and +\l{Defining QML Types from C++}{define types} to be +\l{Exposing Attributes of C++ Types to QML}{exposed to QML} in them. -JavaScript expressions allow QML code to contain application logic. Qt QML -provides the framework for running JavaScript expressions in QML and from C++. +\section1 Tweaking the engine -These sections are from \l{The QML Reference}. - \list - \li \l{qtqml-javascript-topic.html}{Integrating QML and JavaScript} - \li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML} - \li \l{qtqml-javascript-dynamicobjectcreation.html}{Dynamic QML Object Creation from JavaScript} - \li \l{qtqml-javascript-resources.html}{Defining JavaScript Resources In QML} - \li \l{qtqml-javascript-imports.html}{Importing JavaScript Resources In QML} - \li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} - \endlist +There are a number of knobs you can turn to customize the behavior of the QML engine. +The page on \l{Configuring the JavaScript Engine}{configuring the JavaScript engine} +lists the environment variables you may use to this effect. The description of the +\l{The QML Disk Cache}{QML Disk Cache} describes the options related to how your QML +components are compiled and loaded. -\section1 Integrating QML with C++ Applications +\section1 Articles and Guides -The module also provides the framework for running QML applications. -The QML framework allows QML code to contain JavaScript expressions and for -the QML code to interact with C++ code. +These articles contain information about Qt Qml. \list -\li \l{Important C++ Classes Provided By The Qt QML Module} -\li \l{Integrating QML and C++} + \li \l{The QML Reference} + \li \l{Qt Qml Tooling} + \li \l{Writing QML Modules} + \li \l{Singletons in QML} \endlist -\section1 Additional Frameworks +\section1 Reference + \list -\li \l{The Declarative State Machine Framework} + \li \l {Qt Qml C++ Classes} {C++ Classes} + \li \l {Qt Qml QML Types} {QML Types} \endlist \section1 Licenses and Attributions -Qt QML is available under commercial licenses from \l{The Qt Company}. +Qt Qml is available under commercial licenses from \l{The Qt Company}. In addition, it is available under free software licenses. Since Qt 5.4, these free software licenses are \l{GNU Lesser General Public License, version 3}, or the \l{GNU General Public License, version 2}. See \l{Qt Licensing} for further details. -Furthermore Qt QML in Qt \QtVersion may contain third party +Furthermore Qt Qml in Qt \QtVersion may contain third party modules under following permissive licenses: \generatelist{groupsbymodule attributions-qtqml} -\section1 Guides and Other Information - -Further information for writing QML applications: -\list -\li \l{The QML Reference} -\li \l{QML Applications} - - essential information for application development with QML and Qt Quick -\li \l{Qt Quick} - a module which provides a set of QML types and C++ classes - for building user interfaces and applications with QML -\endlist - -\section2 Reference -\list -\li \l{Qt QML C++ Classes}{C++ Classes} -\li \l{Qt QML QML Types}{QML Types} -\li \l{Qt QML Examples}{Examples} -\endlist - */ diff --git a/src/qml/doc/src/statemachine.qdoc b/src/qml/doc/src/statemachine.qdoc deleted file mode 100644 index 6986f1baa0..0000000000 --- a/src/qml/doc/src/statemachine.qdoc +++ /dev/null @@ -1,328 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \qmlmodule QtQml.StateMachine 1.\QtMinorVersion - \title Declarative State Machine QML Types - \brief Provides QML types to create and execute state graphs. - - The following is a list of QML types provided by the module: -*/ - - -/*! - \page qmlstatemachine.html - \title The Declarative State Machine Framework - \brief Overview of the Declarative State Machine Framework for constructing and executing state graphs. - - \ingroup frameworks-technologies - - \tableofcontents - - The Declarative State Machine Framework provides types for creating and - executing state graphs in QML. It is similar to the C++ State Machine - framework based on Harel's - \l{Statecharts: A visual formalism for complex systems}, which - is also the basis for UML state diagrams. Like its - \l{The State Machine Framework}{C++ counterpart}, the framework provides an - API and execution model based on \l{State Chart XML: State Machine Notation for - Control Abstraction}{State Chart XML (SCXML)} - to embed the elements and semantics of statecharts in QML applications. - - For user interfaces with multiple visual states, independent of the - application's logical state, consider using QML States and Transitions. - - These following QML types are provided by framework to create event-driven - state machines: - - \annotatedlist statemachine-qmltypes - - \section1 Using Both QtQuick and QtQml.StateMachine Imports - - \warning If you're attempting to import both \l{QtQuick} and - \e{QtQml.StateMachine} in one single QML file, make sure to import - \e{QtQml.StateMachine} \e{last}. This way, the \e{State} type is provided - by the Declarative State Machine Framework and not by \l{QtQuick}: - - \qml \QtMinorVersion - import QtQuick 2.\1 - import QtQml.StateMachine 1.\1 - - StateMachine { - State { - // okay, is of type QtQml.StateMachine.State - } - } - \endqml - - Alternatively, you can import \e{QtQml.StateMachine} into a separate - namespace to avoid any ambiguity with QtQuick's \e{State} item: - - \qml \QtMinorVersion - import QtQuick 2.\1 - import QtQml.StateMachine 1.\1 as DSM - - DSM.StateMachine { - DSM.State { - // ... - } - } - \endqml - - \section1 A Simple State Machine - - To demonstrate the core functionality of the State Machine API, let's look - at an example: A state machine with three states, \c s1, \c s2 and \c - s3. The state machine is controlled by a single Button; when the button - is clicked, the machine transitions to another state. Initially, the state - machine is in state \c s1. The following is a state chart showing the - different states in our example. - - \image statemachine-button.png - - The following snippet shows the code needed to create such a state machine. - - \snippet qml/statemachine/statemachine-button.qml 0 - - The state machine runs asynchronously to become part of your application's - event loop. - - \section1 State Machines That Finish - - The state machine defined in the previous section never finishes. In order - for a state machine to be able to finish, it needs to have a top-level \e - final state (FinalState object). When the state machine enters the top-level - final state, the machine emits the \l{State::finished}{finished} - signal and halts. - - All you need to do to introduce a final state in the graph is create a - FinalState object and use it as the target of one or more transitions. - - \section1 Sharing Transitions - - Assume we wanted the user to be able to quit the application at any time by - clicking a Quit button. In order to achieve this, we need to create a final - state and make it the target of a transition associated with the Quit - button's \e clicked() signal. We could add a transition for each state; - however, this seems redundant and one would also have to - remember to add such a transition from every new state that is added in the - future. - - We can achieve the same behavior (namely that clicking the Quit button quits - the state machine, regardless of which state the state machine is in) by - grouping states \c s1, \c s2 and \c s3. This is done by creating a new - top-level state and making the three original states children of the new - state. The following diagram shows the new state machine. - - \image statemachine-button-nested.png - - The three original states have been renamed \c s11, \c s12 and \c s13 to - reflect that they are now childrens of the new top-level state, \c s1. Child - states implicitly inherit the transitions of their parent state. This means - it is now sufficient to add a single transition from \c s1 to the final - state, \c s2. New states added to \c s1 will automatically inherit this - transition. - - All that's needed to group states is to specify the proper parent when the - state is created. You also need to specify which of the child states is the - initial one (the child state the state machine should enter when the - parent state is the target of a transition). - - \snippet qml/statemachine/statemachine-button-nested.qml 0 - - In this case we want the application to quit when the state machine is - finished, so the machine's \e finished() signal is connected to the - application's \e quit() slot. - - A child state can override an inherited transition. For example, the - following code adds a transition that effectively causes the Quit button to - be ignored when the state machine is in state, \c s12. - - \snippet qml/statemachine/statemachine-button-nested-ignore-quit.qml 0 - - A transition can have any state as its target irrespective of where the - target state is in the state hierarchy. - - \section1 Using History States - - Imagine that we wanted to add an "interrupt" mechanism to the example - discussed in the previous section; the user should be able to click a button - to have the state machine perform some non-related task, after which the - state machine should resume whatever it was doing before (i.e. return to the - old state, which is one of the three states in this case). - - Such behavior can easily be modeled using \e{history states}. A history - state (HistoryState object) is a pseudo-state that represents the child - state that the parent state was in before it exited last. - - A history state is created as a child of the state for which we wish to - record the current child state; when the state machine detects the presence - of such a state at runtime, it automatically records the current (real) - child state when the parent state exits. A transition to the history - state is in fact a transition to the child state that the state machine had - previously saved; the state machine automatically "forwards" the transition - to the real child state. - - The following diagram shows the state machine after the interrupt mechanism - has been added. - - \image statemachine-button-history.png - - The following code shows how it can be implemented; in this example we - simply display a message box when \c s3 is entered, then immediately return - to the previous child state of \c s1 via the history state. - - \snippet qml/statemachine/statemachine-button-history.qml 0 - - \section1 Using Parallel States - - Assume that you wanted to model a set of mutually exclusive properties of a - car in a single state machine. Let's say the properties we are interested in - are Clean vs Dirty, and Moving vs Not moving. It would take four mutually - exclusive states and eight transitions to represent the states and freely - move between all possible combinations as shown in the following state chart. - - \image statemachine-nonparallel.png - - If we added a third property (say, Red vs Blue), the total number of states - would double, to eight; and if we added a fourth property (say, Enclosed vs - Convertible), the total number of states would double again, to 16. - - This exponential increase can be reduced using parallel states, which enables - linear growth in the number of states and transitions as we add more - properties. Furthermore, states can be added to or removed from the parallel - state without affecting any of their sibling states. The following state - chart shows the different paralles states for the car example. - - \image statemachine-parallel.png - - To create a parallel state group, set childMode to QState.ParallelStates. - - \qml - State { - id: s1 - childMode: QState.ParallelStates - State { - id: s11 - } - State { - id: s12 - } - } - \endqml - - When a parallel state group is entered, all its child states will be - simultaneously entered. Transitions within the individual child states - operate normally. However, any of the child states may take a transition - which exits the parent state. When this happens, the parent state and all of - its child states are exited. - - The parallelism in the State Machine framework follows an interleaved - semantics. All parallel operations will be executed in a single, atomic step - of the event processing, so no event can interrupt the parallel operations. - However, events will still be processed sequentially, as the machine itself - is single threaded. For example, consider the situation where there are two - transitions that exit the same parallel state group, and their conditions - become true simultaneously. In this case, the event that is processed last - of the two will not have any effect. - - \section1 Exiting a Composite State - - A child state can be final (a FinalState object); when a final child state - is entered, the parent state emits the State::finished signal. The - following diagram shows a composite state \c s1 which does some processing - before entering a final state: - - \image statemachine-finished.png - - When \c s1 's final state is entered, \c s1 will automatically emit - \l{State::finished}{finished}. We use a signal transition to cause this event to - trigger a state change: - - \qml - State { - id: s1 - SignalTransition { - targetState: s2 - signal: s1.finished - } - } - \endqml - - Using final states in composite states is useful when you want to hide the - internal details of a composite state. The outside world should be able to - enter the state and get a notification when the state has completed its work, - without the need to know the internal details. This is a very powerful - abstraction and encapsulation mechanism when building complex (deeply nested) - state machines. (In the above example, you could of course create a transition - directly from \c s1 's \c done state rather than relying on \c s1 's - finished() signal, but with the consequence that implementation details of - \c s1 are exposed and depended on). - - For parallel state groups, the State::finished signal is emitted when \e - all the child states have entered final states. - - \section1 Targetless Transitions - - A transition need not have a target state. A transition without a target can - be triggered the same way as any other transition; the difference is that - it doesn't cause any state changes. This allows you to react to a signal or - event when your machine is in a certain state, without having to leave that - state. For example: - - \qml - Button { - id: button - text: "button" - StateMachine { - id: stateMachine - initialState: s1 - running: true - State { - id: s1 - SignalTransition { - signal: button.clicked - onTriggered: console.log("button pressed") - } - } - } - } - \endqml - - The "button pressed" message will be displayed each time the button is clicked, but the - state machine will remain in its current state (s1). If the target state - were explicitly set to s1, s1 would be exited and re-entered each - time (the QAbstractState::entered and QAbstractState::exited - signals would be emitted). - - \section1 Related Information - - \list - \li \l{Declarative State Machine QML Types} - \li \l{The State Machine Framework} - \endlist -*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qml.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qml.qdoc new file mode 100644 index 0000000000..6a0a335839 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qml.qdoc @@ -0,0 +1,107 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qml.html +\title qml +\brief Overview of the qml command line utility. +\ingroup qtqml-tooling + +\section1 The qml utility +\c The qml utility tool loads QML documents and creates a window to show the scene +if your QML document includes a visual item. You can also evaluate non-visual QML +documents with it. +It is mainly meant for testing your QML applications or components quickly +as described in \l {Prototyping with the QML Runtime Tool}{here}. + +\table +\header + \li Usage: +\row + \li qml [\l{options}] files... [-- args...] +\endtable + +\section2 options + +\table +\header + \li Option + \li Description +\row + \li -h, --help + \li Displays help on commandline options. +\row + \li --help-all + \li Displays help, including generic Qt options. +\row + \li -v, --version + \li Displays version information. +\row + \li -a, --apptype <core|gui|widget> + \li Select which application class to use. Default is gui. +\row + \li -I <path> + \li Prepend the given path to the import paths. +\row + \li -f <file> + \li Load the given file as a QML file. +\row + \li -c, --config <file> + \li Load the given built-in configuration or configuration file. +\row + \li --list-conf + \li List the built-in configurations. +\row + \li --translation <file> + \li Load the given file as the translations file. +\row + \li --dummy-data <file> + \li Load QML files from the given directory as context properties. (deprecated) +\row + \li --desktop + \li Force use of desktop OpenGL (AA_UseDesktopOpenGL). +\row + \li --gles + \li Force use of GLES (AA_UseOpenGLES). +\row + \li --software + \li Force use of software rendering (AA_UseSoftwareOpenGL). +\row + \li --core-profile + \li Force use of OpenGL Core Profile. +\row + \li --disable-context-sharing + \li Disable the use of a shared GL context for QtQuick Windows +\row + \li --enable-shader-cache + \li Enable persistent caching of generated shaders +\row + \li --transparent + \li Requests an alpha channel in order to enable semi-transparent windows. +\row + \li --multisample + \li Requests 4x multisample antialiasing. +\row + \li --quiet + \li Suppress all output. +\row + \li --verbose + \li Print information about what qml is doing, like specific file URLs being loaded. +\row + \li --slow-animations + \li Run all animations in slow motion. +\row + \li --fixed-animations + \li Run animations off animation tick rather than wall time. +\row + \li -r, --rhi <backend> + \li Set the backend for the Qt graphics abstraction (RHI). Backend is one of: + default, vulkan, metal, d3d11, gl +\row + \li -S <selector> + \li Add selector to the list of QQmlFileSelectors. + +\endtable + + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlformat.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlformat.qdoc new file mode 100644 index 0000000000..b516104f66 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlformat.qdoc @@ -0,0 +1,146 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlformat.html +\title qmlformat +\brief Overview of the qmlformat tool. +\ingroup qtqml-tooling + +\section1 qmlformat +\e qmlformat is a tool that automatically formats QML files in accordance +with the \l{QML Coding Conventions}. \l{Details}{More...} + +\table +\header + \li Usage: +\row + \li qmlformat [\l{options}] \l{arguments} +\endtable + +\section2 Options +\target options +The following options are available: + +\table +\header + \li Option + \li Default Value + \li Description +\row + \li -h, --help + \li + \li Displays help on commandline options. +\row + \li --help-all + \li + \li Displays help, including generic Qt options. + +\row + \li -v, --version + \li + \li Displays version information. +\row + \li -V, --verbose + \li + \li Verbose mode. Outputs more detailed information. +\row + \li --write-defaults + \li + \li Writes defaults settings to .qmlformat.ini and exits + (Warning: This will overwrite any existing settings and comments!) +\row + \li --ignore-settings + \li + \li Ignores all settings files and only takes command line options into consideration +\row + \li -i, --inplace + \li + \li Edit file in-place instead of outputting to stdout. +\row + \li -f, --force + \li + \li Continue even if an error has occurred. +\row + \li -t, --tabs + \li + \li Use tabs instead of spaces. +\row + \li -w, --indent-width <width> + \li 4 + \li How many spaces are used when indenting. +\row + \li -n, --normalize + \li + \li Reorders the attributes of the objects according to the QML Coding Guidelines. +\row + \li -F, --files <file> + \li + \li Format all files listed in file, in-place +\row + \li -l, --newline <newline> + \li + \li Override the new line format to use (native macos unix windows). +\row + \li --objects-spacing + \li + \li Ensure spaces between objects (only works with normalize option). +\row + \li --functions-spacing + \li + \li Ensure spaces between functions (only works with normalize option). + +\endtable + +\section2 Arguments +\target arguments +\table +\header + \li Arguments: +\row + \li filenames +\endtable + +\section2 Details +\e qmlformat is flexible and can be configured according to your needs. + +\section3 Output +qmlformat writes the formatted version of the file to stdout. +If you wish to have your file updated in-place specify the \c{-i} flag. + +\section3 Grouping Properties, Functions, and Signals Together +With \c{-n} or \c{--normalize} flag, \e qmlformat groups all properties, functions, +and signals together, instead of retaining the order you specified. + +\section3 Settings File +You can configure \e qmlformat by including a settings file \c{.qmlformat.ini} in your +project source or in the parent directories of your project source folder. A default +settings file can be obtained by passing the \c{--write-defaults} flag. This generates the +\c{.qmlformat.ini} file in the current working directory. + +\warning \c{--write-defaults} will overwrite any existing settings and comments! + +\section3 Formatting a List of Files +While you can pass a list of files to be formatted as arguments, qmlformat provides +\c {-F} option to format a set of files stored in a file. In this case, formatting will happen +inplace. + +\code + // FileList.txt + main.qml + mycomponent.qml +\endcode + +Then, use it like +\code + qmlformat -F FileList.txt +\endcode + +\note If the file contains an invalid entry, for example, a file path that +doesn't exist or a valid file path but the content is an invalid qml document, +then \c qmlformat will error out for that particular entry. It will still format +the valid file entries in place. + +\warning If you provide -F option, qmlformat will ignore the positional arguments. + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlimportscanner.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlimportscanner.qdoc new file mode 100644 index 0000000000..7a4047cf7d --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlimportscanner.qdoc @@ -0,0 +1,15 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlimportscanner.html +\title qmlimportscanner +\brief Overview of the qmlimportscanner utility. +\ingroup qtqml-tooling + +\section1 qmlimportscanner +\c qmlimportscanner is an internal tool shipped with Qt Qml to scan QML files +inside the directory for QML import dependencies. It is meant to be invoked by +the build system only, users shouldn't need to execute it directly. + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmllint.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmllint.qdoc new file mode 100644 index 0000000000..7dfde85f2a --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmllint.qdoc @@ -0,0 +1,142 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmllint.html +\title qmllint Reference +\ingroup qtqml-tooling +\brief A tool for verifying the syntax of QML files and warning about +anti-patterns. + +\e qmllint is a tool shipped with Qt, that verifies the syntatic validity of +QML files. +It also warns about some QML anti-patterns. If you want to disable a specific +warning type, you can find the appropriate flag for doing so by passing +\c{--help} on the command line. + +By default, some issues will result in warnings that will be printed. If there +are more warnings than a limit which can be configured with \c{--max-warnings}, +the exit code will be non-zero. +Minor issues however (such as unused imports) are just informational messages +by default and will never affect the exit code. +qmllint is very configurable and allows for disabling warnings or changing how +they are treated. +Users may freely turn any issue into a warning, informational message, or +disable them outright. + +qmllint warns about: +\list + \li Unqualified accesses of properties + \li Usage of signal handlers without a matching signal + \li Usage of with statements in QML + \li Issues related to compiling QML code + \li Unused imports + \li Deprecated components and properties + \li And many other things +\endlist + +\note In order for qmllint to work properly, it requires type information. +That information is provided by QML modules in the import paths. +The current directory, as well as the import paths for Qt's built-in types, +are used as import paths by default. +To add more import paths not included in the default, +add them via the \c{-I} flag. + +To get an overview and explanation of all available command line options, run \c{qmllint --help}. + +\section2 Compiler warnings + +qmllint can warn you about code that cannot be compiled by \l{qmlsc}. + +These warnings are not enabled by default. In order to enable them specify +\c{--compiler warning} or adjust your settings file accordingly. + +\section2 Marking components and properties as deprecated + +qmllint allows you to mark both properties and components as deprecated: + +\code +@Deprecated { reason: "Use NewCustomText instead" } +Text { + @Deprecated { reason: "Use newProperty instead" } + property int oldProperty + property int newProperty + Component.onCompleted: console.log(oldProperty); // Warning: XY.qml:8:40: Property "oldProperty" is deprecated (Reason: Use newProperty instead) +} +\endcode + +Deprecation warnings for components will be shown every time the component is created. + +\section2 Disabling warnings inline + +You may at any point disable warnings temporarily in a file using \c{// qmllint +disable}. + +You can do this at the end of a line when a single line produces warnings: + +\code +Item { + property string foo + Item { + property string bar: foo // qmllint disable unqualified + } +} +\endcode + +Alternatively you can disable comments for a block of lines by putting the +comment in a line only containing \c{// qmllint disable}, ending the block with +\c{// qmllint enable}: + +\code +Item { + property string foo + Item { + // qmllint disable unqualified + property string bar: foo + property string bar2: foo + // qmllint enable unqualified + } +} +\endcode + +qmllint interprets all single line comments starting with \c {qmllint} as +directives. Thus you may not start a comment that way unless you wish to enable +or disable warnings. + +\note As done in the examples above it is preferable to explicitly specify the +warning or a list of warnings you want to disable instead of disabling all +warnings. This can be done by simply listing warning categories after \c{qmllint disable} (the names are +the same as the options listed in \c{--help}). + +\section2 Settings + +In addition to passing command-line options, you can also +configure qmllint via a settings file. +The command line \c{--write-defaults} will generate one for you. + +Setting files are named \c{.qmllint.ini} and look like this: + +\quotefile qmllint/config.ini + +Warning levels may be set to \c{info}, \c{warning} or \c{disable} just as with +command line options. + +qmllint will automatically look for a settings file at the location of the qml +file that is being linted. +It also looks through all parent directories to find this file and +automatically applies the settings therein. You can disable this behavior by +using \c{--ignore-settings}. +You may always override these defaults by specifying command line parameters +that take precedence over the warning levels in settings. + +\section2 Scripting + +qmllint can write or output JSON via the \c{--json <file>} option which will return valid JSON +with warning messages, file and line location of warnings, and their severity +level. Use the special filename '-' to write to stdout instead of a file. +This can be used to more easily integrate qmllint in your pre-commit hooks or +CI testing. + +\sa {Type Description Files} +\sa {Qt Quick Tools and Utilities} +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc new file mode 100644 index 0000000000..e9c737c036 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc @@ -0,0 +1,168 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlls.html +\title \QMLLS Reference +\brief Overview of \QMLLS (qmlls). +\ingroup qtqml-tooling + +\QMLLS is a tool shipped with Qt that helps you write code +in your favorite (LSP-supporting) editor. +See \l{https://microsoft.github.io/language-server-protocol/}{Language Server Protocol} +for more information. + +Currently, it enables your editor to: +\list + \li Autocomplete your code + \li Display qmllint warnings + \li Navigate to definitions in QML files + \li Find usages of JavaScript variables and QML objects + \li Rename JavaScript variables and QML objects + \li Format QML files +\endlist + +\note qmlls is currently in development, see \l{Known Limitations} for +more details. + +\section1 Supported Features + +\section2 Linting + +\QMLLS can automatically lint opened QML files +and display warnings or errors straight in the editor. See +\l{qmllint Reference}{qmllint} for more information about the linting process. + +\section2 Formatting + +\QMLLS can format entire files from inside +the editor. See \l{qmlformat} for more information about the +formatting process. + + +\section2 Finding Definitions + +\QMLLS can find definitions of JavaScript variables, +functions, QML object id's and QML properties from their usages. + +\QMLLS can also find the definition of types used in +type annotations for JavaScript functions, QML object properties, +and QML object instantiation. + +\section2 Finding Usages + +\QMLLS can find usages of JavaScript variables, +QML object properties, JavaScript functions, QML object methods, +and QML object id's. + +\section2 Renaming + +\QMLLS can rename JavaScript variables and functions, +as well as QML object properties, methods, and id's, as long as +they are defined in a QML file. + +\section2 Suggesting Autocompletion Items + +\QMLLS provides autocompletion suggestions for +JavaScript variables, expressions, and statements, as well as +QML object properties, methods, and id's. + +\section2 Tracking Changes in C++ Files + +\QMLLS can track changes in C++ files defining QML +types. It automatically rebuilds CMake QML modules to provide +accurate and up-to-date warnings and completion items for C++ +defined QML types. + +You can +\l{Disabling automatic CMake builds}{disable this feature}. + +\section1 Setting up the \QMLLS in Your Editor + +\note You can find the \QMLLS binary under +\c{<Qt installation folder>/bin/qmlls} in installations of Qt +made with \QOI. + +\section2 Setting up the Build Directory + +\QMLLS needs to know the location of your build +folder. You can pass it the following ways: +\list + \li The \c{--build-dir} command line option. In this case +your editor should invoke \c{qmlls} as following: +\badcode +<path/to/qmlls> --build-dir <path/to/build-directory> +\endcode + \li The \c{QMLLS_BUILD_DIRS} environment variable. + \li The \c{.qmlls.ini} settings file, see \l {Configuration File}. +\endlist + +\note When the build directory is specified in multiple ways, the +command line option takes preference over the environment variable +that takes precedence over the setting file. + +\section2 Disabling Automatic CMake Builds + +\c{qmlls} will try to trigger a CMake rebuild when it detects that the +source code of a C++ defined QML type has been modified. + +To disable this feature, use the following ways: +\list + \li The \c{--no-cmake-calls} command line option. In this case +your editor should invoke \c{qmlls} as follows: +\badcode +<path/to/qmlls> --build-dir <path/to/build-directory> --no-cmake-calls +\endcode + \li The \c{QMLLS_NO_CMAKE_CALLS} environment variable. + \li The \c{.qmlls.ini} settings file, see \l {Configuration File}. +\endlist + +\section1 Configuration File + +\QMLLS can be configured via a configuration file \c{.qmlls.ini}. +This file should be in the root source directory of the project. +It should be a text file in the ini-format. + +\note \c{.qmlls.ini} files can be generated automatically via +\l{QT_QML_GENERATE_QMLLS_INI}. + +The configuration file should look like this: +\code +// .qmlls.ini +[General] +buildDir=<path/to/build-directory> +no-cmake-calls=<true-or-false> +\endcode + +Currently, the configuration file can be used to set the build +directory of the current project and optionally disable the automatic +CMake rebuild functionality for C++ defined QML types. + +\note \QMLLS can create default configuration files +using the \c{--write-defaults} option. This will overwrite an +already existing .qmlls.ini file in the current directory. + +\section1 Known Limitations + +\QMLLS might emit false positive warnings on projects +that were not built, as it needs the build information to find +QML modules defined in the same project, for example. + +Despite covering many common QML features, +the \QMLLS is still in development with some features +yet to be supported: + +\list + \li Renaming QML types. + \li Suggesting autocompletions on invalid QML files. + \li Navigating to definitions of objects defined in C++. + \li Supporting all QML and JavaScript language constructs for all features. +\endlist + +The QML code model in the \QMLLS does not yet +support all of the JavaScript language constructs, which means that +some features like navigating to definition and finding usages might not +work on these language constructs. + + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlpreview.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlpreview.qdoc new file mode 100644 index 0000000000..5e9da3d2f4 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlpreview.qdoc @@ -0,0 +1,74 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlpreview.html +\title qmlpreview +\brief Overview of the qmlpreview utility. +\ingroup qtqml-tooling + +\section1 The Qml Preview +The QML Preview tool watches QML and JavaScript files on disk and updates +the application live with any changes. The application to be previewed +has to have QML debugging enabled. \l {details}{More...} + +\table +\header + \li Usage +\row + \li qmlpreview [\l{options}] executable [parameters...] +\endtable + +\section2 options + +\table +\header + \li Option + \li Description +\row + \li --verbose + \li Print debugging output. +\row + \li -h, --help + \li Displays help on commandline options. +\row + \li --help-all + \li Displays help, including generic Qt options. +\row + \li -v, --version + \li Displays version information. +\endtable + +\section2 Arguments + +\table + \header + \li Argument + \li Description + \row + \li executable + \li The path of the executable file that loads a QML document. + \row + \li parameters + \li Arguments of the executable + +\endtable + +\section2 Details +\target details + +\section3 Enable QML Debugging +To enable QML debugging, make sure you build your application with appropriate +configuration parameters. When using qmake, you should add \c {CONFIG+=qml_debug} +in the \c {.pro} file. If you use another build system, then \c {QT_QML_DEBUG} +variable should be defined. + +\badcode + qt_add_executable(MyApp + ... + ) + + target_compile_definitions(MyApp PRIVATE QT_QML_DEBUG) +\endcode + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlprofiler.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlprofiler.qdoc new file mode 100644 index 0000000000..6bce0417b7 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmlprofiler.qdoc @@ -0,0 +1,10 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmlprofiler.html +\title qmlprofiler +\brief Overview of the qml profiler tool. +\ingroup qtqml-tooling + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmltyperegistrar.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmltyperegistrar.qdoc new file mode 100644 index 0000000000..1f2103d1b1 --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-qmltyperegistrar.qdoc @@ -0,0 +1,10 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-qmltyperegistrar.html +\title qmltyperegistrar +\brief Overview of the qmltyperegistrar utility. +\ingroup qtqml-tooling + +*/ diff --git a/src/qml/doc/src/tools/qtqml-tooling-svgtoqml.qdoc b/src/qml/doc/src/tools/qtqml-tooling-svgtoqml.qdoc new file mode 100644 index 0000000000..836acc3f6a --- /dev/null +++ b/src/qml/doc/src/tools/qtqml-tooling-svgtoqml.qdoc @@ -0,0 +1,92 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tooling-svgtoqml.html +\title svgtoqml +\brief The SVG to QML converter tool +\ingroup qtqml-tooling + +\c svgtoqml is a command line tool shipped with Qt that converts an SVG document +to a QML file. This QML file can then be used as a component in Qt Quick +applications. The \l{Weather Forecast Example} includes multiple QML files that have been generated +using this tool. + +\section1 Overview +The \c svgtoqml will convert an SVG file to a QML file which uses Qt Quick primitives. Since +Qt Quick supports scalable vector graphics, the resulting item will be smoothly transformable as far +as this is possible. As a baseline, the tool supports most of the static features of the SVG Tiny 1.2 +profile. Certain additional features are supported, determined on a case-by-case basis. Interactive +features and animations are not supported. + +\section1 Usage +The basic usage of \c svgtoqml is to provide an input file and an output file: +\c{svgtoqml input.svg output.qml}. This will read the \c{input.svg} file and convert it into the +corresponding Qt Quick scene in \c{output.qml}, which can then be used as part of a Qt Quick +application. + +In addition, it supports the following options: + +\table +\header + \li Option + \li Description +\row + \li --copyright-statement <string> + \li Adds <string> as a comment at the beginning of the generated file. +\row + \li --curve-renderer + \li Enables the curve renderer backend for \l{Qt Quick Shapes}. This enables smooth, antialiased + shapes in the scene without multi-sampling, but at some extra cost. +\row + \li --optimize-paths + \li Enables optimization of paths before committing them to the QML file, potentially making + them faster to load and render later. +\row + \li --outline-stroke-mode + \li Stroke the outline (contour) of the filled shape instead of the original path. +\row + \li -t, --type-name <string> + \li In place of \l{Shape}, the output will use the type name <string> instead. This is + enables using a custom item to override the default behavior of \l{Shape} items. +\row + \li -v, --view + \li Display a preview of the Qt Quick item as it will be generated. +\endtable + +\section1 Comparison to other options +There are multiple options for including SVG content in Qt Quick. The following will give an +overview of where \c svgtoqml fits into the story. + +\section2 Comparison to Qt Svg +\l{Qt Svg} is a module which provides a parser and software renderer for SVG files. In addition, it +includes an image loader plugin, so that SVG files can be loaded directly by the \l{Image} element +in Qt Quick. The SVG will then be rasterized and cached at a specified size and redrawing it will +be quite cheap. But zooming into the image without pixelation will involve reloading it at a +different size, which in turn can be expensive. + +\c svgtoqml (and the \l{VectorImage} component) are alternative ways of rendering the same content. +Once loaded into Qt Quick, transforms can be changed while retaining the geometry data needed to +render the scene in GPU memory. Thus, the vector image can be redrawn at different scales with very +little overhead. + +If the image size will not change during the life time of the application, however, loading the +SVG as an \l{Image} will be more efficient. In this case, if the SVG is always rendered at a +small subset of possible sizes, consider pre-rasterizing it to an image format which is more +efficient to load, such as \c PNG. + +\section2 Comparison to VectorImage +The \l{VectorImage} component provides the same basic functionality as \c svgtoqml, but instead of +pregenerating the Qt Quick scene as a QML file, it creates the scene at runtime. This allows loading +SVG files that are not provided at build time and thus allows for more flexibility. Pregenerating +the scenes with \c svgtoqml allows optimizing the scene before it is loaded. Thus, for files that +are available at build time, \c svgtoqml is the preferred option. + +\section2 Comparison to PathSvg +The \l{PathSvg} component is part of the \l{Qt Quick Shapes} module. It provides a way to define +paths with the syntax used by SVG, where the control points of a path are specified as a string. It +does not support loading SVG files, so it is not a direct alternative to \c svgtoqml. If a complex +SVG contains a specific shape needed by the application, then copying this path description into +\l{PathSvg} may be more convenient than generating the full file. + +*/ diff --git a/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc new file mode 100644 index 0000000000..302c71882a --- /dev/null +++ b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-script-compiler.qdoc @@ -0,0 +1,120 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-qml-script-compiler.html +\title QML script compiler +\brief A tool to compile functions and expressions in QML. +\keyword qmlsc +\ingroup qtqml-tooling + +The QML script compiler compiles functions and expressions in QML and JavaScript +files to a byte code that can be interpreted or Just-in-time compiled by the +QML engine. + +In addition, it compiles some functions and expressions in QML files into C++ +code, within limitations set by the nature of JavaScript. It generates C++ code +for functions that can be exhaustively analyzed. The following flow chart +explains the compilation workflow. + +\image qmlsc-compilation-scheme.png + +QML script compiler is available in two versions. One is \e qmlcachegen, which +is a part of the \l{Qt Quick Compiler}. Another one is \e qmlsc, which is a part +of the commercial-only add-on \e{Qt Quick Compiler Extensions}. + +\section1 qmlcachegen +\e qmlcachegen uses the meta-object system and generates lookups and stores them in a +central place, a compilation unit. The compilation unit contains a representation of +document structure, compact byte code representation for each function and expression, +and native code for functions and bindings that compiler fully understands. +The byte code in a compilation unit can be used by the QML engine to avoid re-compilation +and to speed up execution. + +\section1 qmlsc +\e qmlsc, on the flip side, extends the base functionality of qmlcachegen by providing +two extra modes. + +\list +\li \l {static mode} +\li \l {direct mode} +\endlist + +\section2 static mode +In static mode, qmlsc assumes that no properties of any types exposed to C++ can be +shadowed by derived types. It eliminates the shadow checking mechanism and allows more +JavaScript code to be compiled to C++ and eventually generates faster code. + +To enable static mode in qmlsc, you should pass \c{--static} via \c{QT_QMLCACHEGEN_ARGUMENTS} to \l{qt_add_qml_module}. +\badcode + qt_add_qml_module(someTarget + ... + ) + + set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--static" + ) +\endcode + +\warning qmlsc static-mode generates invalid code if any properties are shadowed in +the QML document. + +\section2 direct mode +In direct mode, qmlsc assumes that all C++ types used in your QML code are available +and can be included as C++ headers to the generated code. Then the generated code +accesses or modifies properties by directly calling getters, setters and invokable +functions in those headers which makes the execution even faster. This means you have to +link to private Qt APIs in CMake. + +\warning Private Qt APIs change often. You will need to recompile Qt for each new version. + +\warning If a type is only defined in a plugin or has no header, you can’t use it in direct mode. + +To enable direct mode, you should consider the followings: + +\list + \li you should pass \c{--direct-calls} via \c{QT_QMLCACHEGEN_ARGUMENTS} to \l{qt_add_qml_module}. + +\badcode + qt_add_qml_module(someTarget + ... + ) + + set_target_properties(someTarget PROPERTIES + QT_QMLCACHEGEN_ARGUMENTS "--direct-calls" + ) +\endcode + + \li Link all the relavant private Qt modules instead of their public counterparts. +\badcode + qt_add_qml_module(someTarget + ... + ) + + target_link_libraries(someTarget PRIVATE + Qt::QmlPrivate + Qt::QuickPrivate + ... + ) +\endcode + + \li Do not set the \c{PLUGIN_TARGET} to be the same as the backing library target. +\badcode + # direct mode will not function in this setup. + qt_add_qml_module(someTarget + PLUGIN_TARGET someTarget + ... + ) +\endcode +\endlist + +\section1 Limitations when compiling JavaScript to C++ + +Many JavaScript constructs cannot be efficiently represented in C++. The QML +script compiler skips the C++ code generation for functions that contain such +constructs and only generates byte code to be interpreted or run through the +Just-in-time compiler. Most common QML expressions are rather simple: value +lookups on QObjects, arithmetics, simple if/else or loop constructs. Those can +easily be expressed in C++, and doing so makes your application run faster. + +*/ diff --git a/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-type-compiler.qdoc b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-type-compiler.qdoc new file mode 100644 index 0000000000..38f8fe039b --- /dev/null +++ b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-type-compiler.qdoc @@ -0,0 +1,283 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-qml-type-compiler.html +\title QML type compiler +\brief A tool to compile QML types to C++ ahead of time. +\keyword qmltc +\ingroup qtqml-tooling + +The QML type compiler, \c qmltc, is a tool shipped with Qt to translate QML +types into C++ types that are \e{ahead-of-time} compiled as part of the user +code. Using qmltc can lead to better run-time performance due to more +optimization opportunities available to the compiler compared to a +QQmlComponent-based object creation. The qmltc is part of the \l{Qt Quick Compiler} +toolchain. + +By design, qmltc outputs user-facing code. That code is supposed to be utilized +by the C++ application directly, otherwise you won't see any benefit. This +generated code essentially replaces QQmlComponent and its APIs to create objects +from QML documents. You can find more information under \l{Using qmltc in a QML +application} and \l{Generated Output Basics}. + +In order to enable qmltc: + +\list + \li Create a \l{qt_add_qml_module}{proper QML module} for your application. + + \li Invoke qmltc, for example, through the \l{qmltc-cmake}{CMake API}. + + \li \c{#include} the generated header file(s) in the application source + code. + + \li Instantiate an object of the generated type. +\endlist + +In this workflow qmltc usually runs during the build process. Thus, when qmltc +rejects a QML document (whether due to errors or warnings, or because of +constructs qmltc doesn't yet support), the build process will fail. This is +similar to how you receive qmllint errors when you enable the automatic +generation of linting targets during \l{qt_add_qml_module}{QML module creation} +and then attempt to "build" them to run the qmllint. + +\warning qmltc is currently in a Tech Preview stage and might not compile an +arbitrary QML program (see \l{Known Limitations} for more details). When qmltc +fails, nothing is generated as your application cannot sensibly use the qmltc +output. If your program contains errors (or unsolvable warnings), they should be +fixed to enable the compilation. The general rule is to adhere to the best +practices and follow \l{qmllint Reference}{qmllint} advice. + +\note \c qmltc does not guarantee that the generated C++ stays API-, source- or +binary-compatible between past or future versions, even patch versions. +Furthermore, qmltc-compiled apps using Qt's QML modules will require linking +against private Qt API. This is because Qt's QML modules do not usually provide +a public C++ API since their primary usage is through QML. + + +\section2 Using qmltc in a QML application + +From the build system perspective, adding qmltc compilation is not much +different from adding qml cache generation. Naively, the build process could be +described as: + +\image qmltc-compilation-scheme.png + +While the real compilation process is much trickier, this diagram captures the +core components that qmltc uses: the QML files themselves and qmldir with +qmltypes information. Simpler applications typically have rather primitive +qmldir yet, in general, qmldir could be complex, providing essential, nicely +packed type information that qmltc relies on to perform correct QML-to-C++ +translation. + +Nevertheless, adding an extra build step is not enough in qmltc case. The +application code must also be modified to use qmltc-generated classes instead of +QQmlComponent or its higher-level alternatives. + +\section3 Compiling QML code with qmltc + +Qt, starting from Qt 6, uses CMake to build its various components. User +projects can - and are encouraged to - also use CMake to build their components +using Qt. Adding out-of-the-box qmltc compilation support to your project would +require a CMake-driven build flow as well since this flow is centered around +proper QML modules and their infrastructure. + +The easy way to add qmltc compilation is by using the dedicated +\l{qmltc-cmake}{CMake API} as part of a QML module creation for the application. +Consider a simple application directory structure: + +\badcode +. +├── CMakeLists.txt +├── myspecialtype.h // C++ type exposed to QML +├── myspecialtype.cpp +├── myApp.qml // main QML page +├── MyButton.qml // custom UI button +├── MySlider.qml // custom UI slider +└── main.cpp // main C++ application file +\endcode + +Then the CMake code would usually look similar to the following: + +\snippet qmltc/CMakeLists.txt qmltc-app-name +\codeline +\snippet qmltc/CMakeLists.txt qmltc-qml-files +\codeline +\snippet qmltc/CMakeLists.txt qmltc-add-qml-module +\codeline +\snippet qmltc/CMakeLists.txt qmltc-compile-to-cpp + +\section3 Using the Generated C++ + +Unlike in the case of QQmlComponent instantiation, the output of qmltc, being +C++ code, is used directly by the application. Generally, constructing a new +object in C++ is equivalent to creating a new object through +QQmlComponent::create(). Once created, the object could be manipulated from C++ +or, for example, combined with QQuickWindow to be drawn on screen. + +If a compiled type exposes some required properties, `qmltc` will +require an initial value for those properties in the constructor for +the generated object. + +Additionally, the constructor for a qmltc object can be provided with +with a callback to set up initial values for the component's +properties. + +Given a \c{myApp.qml} file, the application code (in both cases) would +typically look like this: + +\if defined(onlinedocs) + \tab {generated-c++}{tab-qqmlcomponent}{Using QQmlComponent}{checked} + \tab {generated-c++}{tab-qmltc}{Using qmltc-generated class}{} + \tabcontent {tab-qqmlcomponent} +\else + \section4 Using QQmlComponent +\endif +\snippet qmltc/tst_qmltc_examples.cpp qqmlcomponent-include +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qqmlcomponent-app-code-0 +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qqmlcomponent-app-code-1 +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qqmlcomponent-app-code-2 +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qmltc-app-exec +\if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmltc} +\else + \section4 Using qmltc-generated class +\endif +\snippet qmltc/tst_qmltc_examples.cpp qmltc-include +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qmltc-app-code +\codeline +\snippet qmltc/tst_qmltc_examples.cpp qmltc-app-exec +\if defined(onlinedocs) + \endtabcontent +\endif + +\section2 QML engine + +The generated code uses QQmlEngine to interact with dynamic parts of a QML +document - mainly the JavaScript code. For this to work, no special arrangements +are needed. Any QQmlEngine instance passed to the constructor of a +qmltc-generated class object should work correctly as does +\c{QQmlComponent(engine)}. This also means that you can use +\l{QQmlEngine}{QQmlEngine methods} that affect QML behavior. However, there are +caveats. Unlike QQmlComponent-based object creation, qmltc itself \e{does not} +rely on QQmlEngine when compiling the code to C++. For instance, +\c{QQmlEngine::addImportPath("/foo/bar/")} - normally resulting in an additional +import path to scan for - would be completely ignored by the ahead-of-time qmltc +procedure. + +\note To add import paths to the qmltc compilation, consider using a relevant +argument of the \l{qmltc-cmake}{CMake command} instead. + +Generally, you can think of it this way: QQmlEngine involves the application +process to run, while qmltc does not as it operates \e{before} your application +is even compiled. Since qmltc makes no attempt to introspect your application's +C++ source code, there is no way for it to know about certain kinds of QML +manipulations you, as a user, do. Instead of using QQmlEngine and related +run-time routines to expose types to QML, adding import paths, etc. you are, +practically, required to create \l{qt_add_qml_module}{well-behaving QML modules} +and use \l{Defining QML Types from C++}{declarative QML type registration}. + +\warning Despite qmltc working closely with QQmlEngine and creating C++ code, +the generated classes cannot be further exposed to QML and used through +QQmlComponent. + +\section2 Generated Output Basics + +\c qmltc aims to be compatible with the existing QML execution model. This +implies that the generated code is roughly equivalent to the internal +QQmlComponent setup logic and thus you should be able to understand your QML +type's behavior, semantics and API the same way you do currently - by visually +inspecting the corresponding QML document. + +However, the generated code is still somewhat confusing, especially given that +your application should use the qmltc output on the C++ side directly. There are +two parts of the generated code: CMake build files structure and the generated +C++ format. The former is covered in the \l{qmltc-cmake}{CMake API of qmltc} and +the latter is covered here. + +Consider a simple HelloWorld type, that has a \c hello property, a function to +print that property, and a signal emitted when the object of that type is +created: + +\snippet qmltc/special/HelloWorld.qml qmltc-hello-world-qml + +When providing a C++ alternative of this QML type, the C++ class would need a +\l{Overview - QML and C++ Integration}{QML-specific meta-object system macro}, +Q_PROPERTY decoration for the \c hello property, \c{Q_INVOKABLE} C++ printing +function and a regular Qt signal definition. Similarly, qmltc would translate +the given HelloWorld type into roughly the following: + +\snippet qmltc/special/HelloWorld.qml.cpp qmltc-hello-world-generated + +Even though specific details of the generated type could differ, the universal +aspects remain. For instance: + +\list + \li QML types within a document are translated into C++ types, according to + the compiler-visible information. + \li Properties are translated into C++ properties with Q_PROPERTY + declarations. + \li JavaScript functions become \c{Q_INVOKABLE} C++ functions. + \li QML signals are transformed into C++ Qt signals. + \li QML enumerations are converted into C++ enumerations with \c{Q_ENUM} + declarations. +\endlist + +An additional detail is the way \c qmltc generates class names. A class name for +a given QML type is automatically deduced from the QML document defining that +type: the QML file name without extensions (up to and excluding the first \c{.}, +also known as the base name) becomes a class name. The file name case is +preserved. Thus, \c{HelloWorld.qml} would result in a \c{class HelloWorld} and +\c{helloWoRlD.qml} in a \c{class helloWoRlD}. Following the QML convention, if a +QML document file name starts with a lower-case letter, the generated C++ class +is assumed to be anonymous and marked with \l{QML_ANONYMOUS}. + +For now, although the generated code is ready to be used from the C++ +application side, you should generally limit calls to the generated APIs. +Instead, prefer implementing the application logic in QML/JavaScript and +hand-written C++ types exposed to QML, using the qmltc-created classes for +simple object instantiation. While generated C++ gives you direct (and usually +faster) access to QML-defined elements of the type, understanding such code +could be a challenge. + +\section2 Known Limitations + +Despite covering many common QML features, qmltc is still in the early stage of +development with some things yet to be supported. + +Imported QML modules that consist of QML-defined types (such as +\c{QtQuick.Controls}) might not get compiled correctly, even if those QML-defined +types were compiled by qmltc.. +At present, you can reliably use \c{QtQml} and \c{QtQuick} modules as well as any +other QML module that \b{only} contains C++ classes exposed to QML. + +On top of this, there are some more fundamental peculiarities to consider: + +\list + \li Qt's QML modules usually rely on C++ libraries to do the heavy lifting. + Often enough, these libraries do not provide public C++ API (since their + primary usage is through QML). For the users of qmltc, this means that their + apps need to link against private Qt libraries. + + \li Due to the nature of qmltc code generation, QML plugins are unusable for + compilation purposes. Instead, QML modules - that use a plugin - have to + ensure that the plugin data is accessible at compile time. Such QML modules + would then have \e optional plugins. In most cases, the compile-time + information can be provided through a header file (with C++ declarations) + and linkable library (with C++ definitions). The user code is responsible + (usually through CMake) for including a path to the header file and linking + against the QML module library. +\endlist + +\note +Given the tech preview status of the compiler, you might also encounter bugs in +qmltc, in the generated code, or some other related part. We encourage you to +\l{https://bugreports.qt.io/}{submit a bug report} in this case. + +*/ diff --git a/src/qml/doc/src/tools/qtquickcompiler/qtqml-tool-qmlcachegen.qdoc b/src/qml/doc/src/tools/qtquickcompiler/qtqml-tool-qmlcachegen.qdoc new file mode 100644 index 0000000000..b7f6d56705 --- /dev/null +++ b/src/qml/doc/src/tools/qtquickcompiler/qtqml-tool-qmlcachegen.qdoc @@ -0,0 +1,13 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtqml-tool-qmlcachegen.html +\title qmlcachegen +\brief A tool to compile QML documents ahead of time +\ingroup qtqml-tooling + +\e qmlcachegen is an internal build tool, invoked by the build system +when using \l qt_add_qml_module in CMake or CONFIG+=qtquickcompiler in +qmake. Users should not invoke it manually. +*/ |