diff options
Diffstat (limited to 'src/qml/doc/src')
111 files changed, 5892 insertions, 1080 deletions
diff --git a/src/qml/doc/src/cmake/cmake-properties.qdoc b/src/qml/doc/src/cmake/cmake-properties.qdoc index 750dcd2d49..a2ca59efc8 100644 --- a/src/qml/doc/src/cmake/cmake-properties.qdoc +++ b/src/qml/doc/src/cmake/cmake-properties.qdoc @@ -17,7 +17,7 @@ global CMake properties: \ingroup cmake-properties-qtqml \ingroup cmake-global-properties-qtqml -\title QT_QMLLLINTER_TARGETS_FOLDER +\title QT_QMLLINTER_TARGETS_FOLDER \brief Sets the FOLDER property for targets that belong to the QML linter. @@ -76,6 +76,8 @@ A \c{.qml} file that provides a singleton type needs to have its \c QT_QML_SINGL 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. @@ -204,3 +206,24 @@ 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 index 6e35655b43..de984c88ef 100644 --- a/src/qml/doc/src/cmake/cmake-variables.qdoc +++ b/src/qml/doc/src/cmake/cmake-variables.qdoc @@ -2,6 +2,15 @@ // 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 @@ -26,6 +35,41 @@ The \c QT_QML_OUTPUT_DIRECTORY will also be added to the import path of the 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 index a5381647c9..a4e54ed1ae 100644 --- a/src/qml/doc/src/cmake/policy/qtp0001.qdoc +++ b/src/qml/doc/src/cmake/policy/qtp0001.qdoc @@ -14,23 +14,26 @@ 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. -The \c OLD behavior of this policy is that, unless -\c AUTO_RESOURCE_PREFIX is set, the \c RESOURCE_PREFIX argument for +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 +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 AUTO_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. +\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. -\note The \c{OLD} behavior of a policy is deprecated, and may -be removed in the future. +\qtpolicydeprecatedbehavior -\sa qt_policy, qt_cmake_policies, qt_add_qml_module +\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 index 857779af2d..63f9707d4d 100644 --- a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc +++ b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc @@ -23,7 +23,6 @@ qt_add_qml_module( [STATIC | SHARED] [PLUGIN_TARGET plugin_target] [OUTPUT_DIRECTORY output_dir] - [AUTO_RESOURCE_PREFIX] [RESOURCE_PREFIX resource_prefix] [CLASS_NAME class_name] [TYPEINFO typeinfo] @@ -39,6 +38,7 @@ qt_add_qml_module( [DESIGNER_SUPPORTED] [FOLLOW_FOREIGN_VERSIONING] [NAMESPACE namespace] + [NO_PLUGIN] [NO_PLUGIN_OPTIONAL] [NO_CREATE_PLUGIN_TARGET] [NO_GENERATE_PLUGIN_SOURCE] @@ -50,6 +50,9 @@ qt_add_qml_module( [NO_IMPORT_SCAN] [ENABLE_TYPE_COMPILER] [TYPE_COMPILER_NAMESPACE namespace] + [QMLTC_EXPORT_DIRECTIVE export_macro] + [QMLTC_EXPORT_FILE_NAME header_defining_export_macro] + ) \endcode @@ -59,6 +62,9 @@ qt_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} @@ -112,9 +118,13 @@ 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 migt be necessary to use -\c Q_IMPORT_QML_PLUGIN to ensure that the QML plugin is correctly linked. +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 @@ -161,6 +171,12 @@ 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 @@ -209,11 +225,10 @@ 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). -Since Qt 6.5, you can specify \l{AUTO_RESOURCE_PREFIX}. If -\l{AUTO_RESOURCE_PREFIX} is specified, \l{RESOURCE_PREFIX} is set to -\c{/qt/qml}. This way, your modules are automatically -placed in the default import path of the QML engine. If you don't do this, you -should set up a \l{QML Import Path} to point to your resource prefix. +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} @@ -269,7 +284,7 @@ set_target_properties(someTarget PROPERTIES \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 QtQuick Compiler +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. @@ -279,6 +294,23 @@ set_target_properties(someTarget PROPERTIES ) \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 @@ -296,9 +328,7 @@ JavaScript file names that are intended to be addressed as components should start with an uppercase letter. Alternatively, you may use lowercase file names and set the source file -property -\l{cmake-source-file-property-QT_QML_SOURCE_TYPENAME}{QT_QML_SOURCE_TYPE_NAME} -to the desired type name. +property \l QT_QML_SOURCE_TYPENAME to the desired type name. \target qml-cmake-singletons \section2 Singletons @@ -308,15 +338,25 @@ 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 +\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 +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 @@ -447,6 +487,7 @@ 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 @@ -512,7 +553,7 @@ class MyItem: public QQuickItem { ... }; 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++ +\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 @@ -537,6 +578,10 @@ 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. @@ -561,6 +606,7 @@ 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 @@ -568,6 +614,7 @@ that situation. The project is then expected to call 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 @@ -577,7 +624,21 @@ plugin class, the \c NO_GENERATE_PLUGIN_SOURCE option should be given. Where no \c CLASS_NAME is provided, it defaults to the \c URI with dots replaced by underscores, then \c Plugin appended. Unless the QML module has no plugin, the class name will be recorded as a \c classname line in the generated -\l{Module Definition qmldir Files}{qmldir} file. +\l{Module Definition qmldir Files}{qmldir} file. You need to add any C++ files +with custom plugin code to the plugin target. Since the plugin then likely +contains functionality that goes beyond simply loading the backing library, you +will probably want to add \l{NO_PLUGIN_OPTIONAL}, too. Otherwise the QML engine +may skip loading the plugin if it detects that the backing library is already +linked. + +\target NO_PLUGIN +If the \c NO_PLUGIN keyword is given, then no plugin will be built. This +keyword is thus incompatible with all the options that customize the plugin +target, in particular \l{NO_GENERATE_PLUGIN_SOURCE}, \l{NO_PLUGIN_OPTIONAL}, +\l{PLUGIN_TARGET}, \l{NO_CREATE_PLUGIN_TARGET}, and \l{CLASS_NAME}. If you do +not provide a plugin for your module, it will only be fully usable if its +backing library has been linked into the executable. It is generally hard to +guarantee that a linker preserves the linkage to a library it considers unused. \target NO_PLUGIN_OPTIONAL If the \c NO_PLUGIN_OPTIONAL keyword is given, then the plugin is recorded in @@ -661,27 +722,23 @@ code will be generated into a C++ namespace of this name. 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{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. +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 +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 defines a namespace, in which the generated -C++ code resides. By default, no namespace is specified for user projects. The -code generated from Qt's own sources is put under a QT_NAMESPACE namespace. - \c TYPE_COMPILER_NAMESPACE argument allows to override the namespace in which -\l{QML Type Compiler}{qmltc} generates code. +\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 @@ -691,4 +748,15 @@ 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_deploy_qml_imports.qdoc b/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc index c92286f109..87125cd0bf 100644 --- a/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc +++ b/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc @@ -6,17 +6,17 @@ \ingroup cmake-commands-qtqml \title qt_deploy_qml_imports -\target qt6_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{qt_deploy_qml_imports()} -can only be called from a deployment script. It cannot be called directly by the -project. +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 +\include cmake-qml-qt-finalize-target-warning.qdocinc warning \section1 Synopsis @@ -38,9 +38,9 @@ qt_deploy_qml_imports( 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{qt_deploy_runtime_dependencies()} won't find these QML modules. -The \c{qt_deploy_qml_imports()} command provides the necessary logic which -complements \l{qt_deploy_runtime_dependencies()} and deploys the runtime parts +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 @@ -62,10 +62,11 @@ 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{qt_deploy_runtime_dependencies()}. +\l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}. \sa {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}, - qt_deploy_runtime_dependencies(), QT_DEPLOY_QML_DIR + {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}, + QT_DEPLOY_QML_DIR \section1 Example @@ -86,7 +87,7 @@ qt_add_qml_module(MyApp # 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} CONTENTS " +file(GENERATE OUTPUT ${deploy_script} CONTENT " include(\"${QT_DEPLOY_SUPPORT}\") qt_deploy_qml_imports( # Deploy QML modules used by MyApp 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 index f99f963770..0d5088e7e5 100644 --- 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 @@ -14,7 +14,7 @@ \cmakecommandsince 6.3 -\include cmake-qml-qt-finalize-target-warning.qdocinc +\include cmake-qml-qt-finalize-target-warning.qdocinc warning \section1 Synopsis @@ -24,6 +24,8 @@ qt_generate_deploy_qml_app_script( 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...] @@ -68,9 +70,11 @@ 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{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{qt_deploy_runtime_dependencies()}, again +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 @@ -94,14 +98,22 @@ other platforms. On platforms other than macOS, Qt translations are automatically deployed. To inhibit this behavior, specify \c{NO_TRANSLATIONS}. Use -\l{qt6_deploy_translations}{qt_deploy_translations} to deploy translations in a +\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{qt_deploy_runtime_dependencies()}. +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()} @@ -114,6 +126,8 @@ same target. \section1 Example +The following example shows how to deploy a QtQuick app. + \badcode cmake_minimum_required(VERSION 3.16...3.22) project(MyThings) @@ -142,4 +156,22 @@ qt_generate_deploy_qml_app_script( ) 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 index 8206dc011b..22d72c101b 100644 --- a/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc +++ b/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc @@ -65,4 +65,13 @@ 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_target_qml_sources.qdoc b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc index 35854d4b95..336cd973f9 100644 --- a/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc +++ b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc @@ -159,6 +159,8 @@ 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 diff --git a/src/qml/doc/src/cppclasses/topic.qdoc b/src/qml/doc/src/cppclasses/topic.qdoc index 0ef283fe16..b440ca437d 100644 --- a/src/qml/doc/src/cppclasses/topic.qdoc +++ b/src/qml/doc/src/cppclasses/topic.qdoc @@ -2,13 +2,13 @@ // 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. diff --git a/src/qml/doc/src/cppintegration/contextproperties.qdoc b/src/qml/doc/src/cppintegration/contextproperties.qdoc index af9f4719e8..1783c0cdc8 100644 --- a/src/qml/doc/src/cppintegration/contextproperties.qdoc +++ b/src/qml/doc/src/cppintegration/contextproperties.qdoc @@ -5,6 +5,23 @@ \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 e564edb943..4932943fc1 100644 --- a/src/qml/doc/src/cppintegration/data.qdoc +++ b/src/qml/doc/src/cppintegration/data.qdoc @@ -92,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 @@ -306,97 +306,15 @@ 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 - -and all registered QList, QVector, QQueue, QStack, QSet, std::list, -std::vector that contain a type marked with \l Q_DECLARE_METATYPE. - -These sequence types are implemented directly in terms of the underlying C++ -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. +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. 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++. -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 - -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)"). - \section2 QByteArray to JavaScript ArrayBuffer The QML engine provides automatic type conversion between QByteArray values and diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc index e6a6dbfe36..feb9053632 100644 --- a/src/qml/doc/src/cppintegration/definetypes.qdoc +++ b/src/qml/doc/src/cppintegration/definetypes.qdoc @@ -16,7 +16,7 @@ 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 @@ -77,15 +77,18 @@ Types to QML} explains, the properties, methods and signals of any QObject-derived class are accessible from QML code. To register a QObject-derived class as an instantiable QML object type, add -\c QML_ELEMENT or \c QML_NAMED_ELEMENT(<name>) to the class declaration and +\c QML_ELEMENT or \c QML_NAMED_ELEMENT(<name>) to the class declaration. You +also need to make adjustments in the build system. For qmake, add \c {CONFIG += qmltypes}, a \c {QML_IMPORT_NAME}, and a -\c QML_IMPORT_MAJOR_VERSION to your project file. This will register the class -into the type namespace under the given major version, using either the class -name or an explicitly given name as QML type name. The minor version(s) will -be derived from any revisions attached to properties, methods, or signals. The -default minor version is \c 0. You can explicitly restrict the type to be -available only from specific minor versions by adding the -\c QML_ADDED_IN_MINOR_VERSION() macro to the class declaration. Clients can +\c QML_IMPORT_MAJOR_VERSION to your project file. For CMake, the file containing +the class should be part of a target set-up with +\l{qt_add_qml_module}{qt_add_qml_module()}. +This will register the class into the type namespace under the given major version, +using either the class name or an explicitly given name as QML type name. The +minor version(s) will be derived from any revisions attached to properties, +methods, or signals. The default minor version is \c 0. You can explicitly +restrict the type to be available only from specific minor versions by adding +the \c QML_ADDED_IN_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 @@ -107,26 +110,52 @@ This type can be registered by adding an appropriate type namespace and version number to the project file. For example, to make the type available in the \c com.mycompany.messaging namespace with version 1.0: -\code -CONFIG += qmltypes -QML_IMPORT_NAME = com.mycompany.messaging -QML_IMPORT_MAJOR_VERSION = 1 -\endcode +\if defined(onlinedocs) + \tab {build-qt-app}{tab-cmake}{CMake}{selected} + \tab {build-qt-app}{tab-qmake}{qmake}{} + \tabcontent {tab-cmake} + \else + \section3 Using CMake +\endif + \badcode + qt_add_qml_module(messaging + URI com.mycompany.messaging + VERSION 1.0 + SOURCES + message.cpp message.h + ) + \endcode +\if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmake} +\else + \section3 Using QMake +\endif + \code + CONFIG += qmltypes + QML_IMPORT_NAME = com.mycompany.messaging + QML_IMPORT_MAJOR_VERSION = 1 + \endcode + + If the header the class is declared in is not accessible from your project's + include path, you may have to amend the include path so that the generated + registration code can be compiled. + + \code + INCLUDEPATH += com/mycompany/messaging + \endcode +\if defined(onlinedocs) + \endtabcontent +\endif -If the header the class is declared in is not accessible from your project's -include path, you may have to amend the include path so that the generated -registration code can be compiled: -\code -INCLUDEPATH += com/mycompany/messaging -\endcode The type can be used in an \l{qtqml-syntax-basics.html#object-declarations} {object declaration} from QML, and its properties can be read and written to, as per the example below: \qml -import com.mycompany.messaging 1.0 +import com.mycompany.messaging Message { author: "Amelie" @@ -137,7 +166,7 @@ Message { \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 +\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++ @@ -177,6 +206,60 @@ There are some further limitations on what you can do with value types: 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 Sometimes a QObject-derived class may need to be registered with the QML type @@ -192,7 +275,7 @@ not be instantiable should not be instantiable from QML \endlist -The \l {Qt QML} module provides several macros for registering non-instantiable +The \l {Qt Qml} module provides several macros for registering non-instantiable types: \list @@ -256,6 +339,7 @@ be aware that properties of such a singleton type cannot be bound to. 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. @@ -331,7 +415,7 @@ available when \c MyTypes version 1.1 or higher is imported. Imports of \c MyTypes version 1.0 remain unaffected. For the same reason, new types introduced in later versions should be tagged -with the QML_ADDED_IN_MINOR_VERSION macro. +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 @@ -361,7 +445,11 @@ 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. @@ -380,9 +468,6 @@ 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 @@ -861,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 diff --git a/src/qml/doc/src/cppintegration/exposecppattributes.qdoc b/src/qml/doc/src/cppintegration/exposecppattributes.qdoc index e3b3288a98..6031d0eebb 100644 --- a/src/qml/doc/src/cppintegration/exposecppattributes.qdoc +++ b/src/qml/doc/src/cppintegration/exposecppattributes.qdoc @@ -39,6 +39,14 @@ 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. @@ -83,7 +91,8 @@ Instead of: \badcode using FooEnum = Foo::Enum; -class Bar : public QObject { +class Bar : public QObject +{ Q_OBJECT Q_PROPERTY(FooEnum enum READ enum WRITE setEnum NOTIFY enumChanged) }; @@ -92,37 +101,46 @@ class Bar : public QObject { Refer to the type directly: \code -class Bar : public QObject { +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[]) { @@ -130,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(); @@ -142,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 @@ -381,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; @@ -394,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: @@ -408,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(); @@ -423,6 +445,8 @@ examples below: import QtQuick 2.0 Item { + required property MessageBoard msgBoard + width: 100; height: 100 MouseArea { 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 66c133980d..156ad47089 100644 --- a/src/qml/doc/src/cppintegration/extending-tutorial.qdoc +++ b/src/qml/doc/src/cppintegration/extending-tutorial.qdoc @@ -2,11 +2,11 @@ // 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. @@ -20,18 +20,19 @@ 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 Tutorial Project +\section1 Creating Project from Scratch -We create a new project using the \e {Qt Quick Application} template in Qt Creator, -as instructed in \l {Qt Creator: Creating Qt Quick Projects}. +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 @@ -54,7 +55,7 @@ a version of 1.0. We want this \c PieChart type to be usable from QML like this: \qml - import Charts 1.0 + import Charts PieChart { width: 100; height: 100 @@ -89,7 +90,7 @@ 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 \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 +QML. If you don't register the class, \c App.qml won't be able to create a \c PieChart. \section2 qmake Setup @@ -111,8 +112,7 @@ Similarly, for the registration to take effect when using CMake, use the 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: +draw a simple pie chart: \snippet tutorials/extending-qml/chapter1-basics/piechart.cpp 0 \dots 0 @@ -121,10 +121,10 @@ flag to enable painting: \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 +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 @@ -132,7 +132,7 @@ provided for various other \l {QML Value Types}{value types}. For example, a str like "640x480" can be automatically converted to a QSize value. We'll also create a C++ application that uses a QQuickView to run and -display \c app.qml. +display \c App.qml. Here is the application \c main.cpp: @@ -162,18 +162,14 @@ Now we can build and run the application: 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 @@ -205,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 @@ -218,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 @@ -256,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 @@ -301,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(): @@ -346,8 +340,7 @@ Using CMake: \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 @@ -356,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 @@ -391,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 @@ -456,19 +448,18 @@ by the module: 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 +\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 - qml -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 @@ -507,4 +498,6 @@ Or randomly add and remove slices from time to time using \l{Property Value Sour } \endcode +\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 index 242a6a2fbc..aac9c080d8 100644 --- 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 @@ -121,7 +121,8 @@ QJSManagedValue is similar to QJSValue, with a few differences: \list \li The constructors (except for the default and move constructor2) require passing a QJSEngine pointer. -\li Methods like \c deleteProperty and \l isSymbol are added. +\li Methods like \l {QJSManagedValue::}{deleteProperty} and + \l {QJSManagedValue::}{isSymbol} are added. \li If QJSManagedValue methods encounter an exception, they leave it intact. \endlist diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc index 48911bc774..b14c54a24e 100644 --- a/src/qml/doc/src/cppintegration/topic.qdoc +++ b/src/qml/doc/src/cppintegration/topic.qdoc @@ -5,8 +5,9 @@ \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 @@ -20,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 @@ -48,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 @@ -90,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 @@ -101,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 @@ -118,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 4a4fdf0454..0000000000 --- a/src/qml/doc/src/examples.qdoc +++ /dev/null @@ -1,47 +0,0 @@ -// Copyright (C) 2017 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\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 c120257247..6ea7e4a005 100644 --- a/src/qml/doc/src/external-resources.qdoc +++ b/src/qml/doc/src/external-resources.qdoc @@ -37,6 +37,10 @@ \title Qt Creator: QML Profiler */ /*! + \externalpage https://doc.qt.io/qtcreator/creator-live-preview-desktop.html + \title Qt Creator: QML Preview On Desktop +*/ +/*! \externalpage https://fontawesome.com/ \title Font Awesome */ @@ -53,3 +57,24 @@ \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-qml-qt-finalize-target-warning.qdocinc b/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.qdocinc index 9152726398..0125a1c4c2 100644 --- 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 @@ -1,7 +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 77d9fa90e9..fcc6fdc802 100644 --- a/src/qml/doc/src/includes/qqmlcomponent.qdoc +++ b/src/qml/doc/src/includes/qqmlcomponent.qdoc @@ -1,5 +1,5 @@ // Copyright (C) 2017 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +// 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/dynamicobjectcreation.qdoc b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc index 29a4a67460..f20111d154 100644 --- a/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc +++ b/src/qml/doc/src/javascript/dynamicobjectcreation.qdoc @@ -11,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 @@ -102,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/finetuning.qdoc b/src/qml/doc/src/javascript/finetuning.qdoc index 14b4c9538d..0e8a913a2a 100644 --- a/src/qml/doc/src/javascript/finetuning.qdoc +++ b/src/qml/doc/src/javascript/finetuning.qdoc @@ -20,8 +20,11 @@ Running JavaScript code can be influenced by a few environment variables, partic considered for JIT compilation. The default value is 3 times. \row \li \c{QV4_FORCE_INTERPRETER} - \li Setting this environment variable disables the JIT and runs all - functions through the interpreter, no matter how often they are called. + \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. @@ -82,6 +85,19 @@ Running JavaScript code can be influenced by a few environment variables, partic \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. diff --git a/src/qml/doc/src/javascript/functionlist.qdoc b/src/qml/doc/src/javascript/functionlist.qdoc index 04c55224ce..d656bc2234 100644 --- a/src/qml/doc/src/javascript/functionlist.qdoc +++ b/src/qml/doc/src/javascript/functionlist.qdoc @@ -209,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 b7950d556e..a27fe48fbe 100644 --- a/src/qml/doc/src/javascript/hostenvironment.qdoc +++ b/src/qml/doc/src/javascript/hostenvironment.qdoc @@ -41,37 +41,12 @@ takes an \c int and a \c string parameter, and returns a \c QtObject: function doThings(a: int, b: string) : QtObject { ... } \endqml -Type annotations help tools like \l{Qt Creator} and \l{qmllint} to make sense +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. -By default, type annotations are ignored by the interpreter and the JIT -compiler, but enforced by \l{qmlcachegen} and \l{qmlsc} when compiling to C++. -This can lead to differences in behavior if you either pass values that -are not actually of the declared type or if you modify instances of -\l{QML Value Types} passed as typed arguments. Value types are passed by -reference by the interpreter and JIT, but by value when compiled to C++. - -You can eliminate those differences by either forcing the interpreter and JIT -to also respect type annotations or by having \l{qmlcachegen} and \l{qmlsc} -ignore type annotations. The former has a performance cost when using the -interpreter or JIT, the latter makes the compilation to C++ avoid any JavaScript -functions, and any bindings and signal handlers that call JavaScript functions. -Therefore less code will be compiled to C++. - -In order to always enforce type annotations, add the following to your QML -document: -\qml -pragma FunctionSignatureBehavior: Enforced -\endqml - -In order to always ignore type annotations, add the following instead: -\qml -pragma FunctionSignatureBehavior: Ignored -\endqml - 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 @@ -86,6 +61,17 @@ Item { 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 The QML JavaScript host environment implements a number of host objects and functions, as @@ -103,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/memory.qdoc b/src/qml/doc/src/javascript/memory.qdoc index c7dcc00d98..54f48f48df 100644 --- a/src/qml/doc/src/javascript/memory.qdoc +++ b/src/qml/doc/src/javascript/memory.qdoc @@ -163,7 +163,7 @@ 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 gc() function +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 diff --git a/src/qml/doc/src/javascript/number.qdoc b/src/qml/doc/src/javascript/number.qdoc index 7676a7cd4f..a37fd8051b 100644 --- a/src/qml/doc/src/javascript/number.qdoc +++ b/src/qml/doc/src/javascript/number.qdoc @@ -34,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} */ /*! @@ -69,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 0857cabbdc..1bd03fad54 100644 --- a/src/qml/doc/src/javascript/qmlglobalobject.qdoc +++ b/src/qml/doc/src/javascript/qmlglobalobject.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2017 The Qt Company Ltd. +// 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 @@ -7,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/string.qdoc b/src/qml/doc/src/javascript/string.qdoc deleted file mode 100644 index ade490d981..0000000000 --- a/src/qml/doc/src/javascript/string.qdoc +++ /dev/null @@ -1,26 +0,0 @@ -// Copyright (C) 2017 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \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 \a 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 27308cde3a..2302f90fbe 100644 --- a/src/qml/doc/src/javascript/topic.qdoc +++ b/src/qml/doc/src/javascript/topic.qdoc @@ -24,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 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/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index 5c5dc669f7..470d4598fc 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -9,14 +9,24 @@ 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. + 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 @@ -46,19 +56,43 @@ 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. + 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_MINOR_VERSION() + Q_REVISION(), QML_ADDED_IN_VERSION() */ /*! @@ -136,8 +170,8 @@ 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. - + It's required in order for declarative registration via \l QML_ELEMENT to + function properly. \sa QML_INTERFACE, Q_INTERFACES */ @@ -153,10 +187,10 @@ Some QML types are implicitly uncreatable, in particular types exposed with \l QML_ANONYMOUS or namespaces exposed with \l QML_ELEMENT or - \l QML_NAMED_ELEMENT(). For such types, \l QML_UNCREATABLE() can be used to - provide a custom error message. + \l QML_NAMED_ELEMENT(). - Since Qt 6.0 you can use "" instead of a reason to use a standard message instead. + 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 */ @@ -173,7 +207,9 @@ \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. + 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: @@ -300,17 +336,37 @@ engine in order to assert on that. \sa QML_ELEMENT, QML_NAMED_ELEMENT(), - qmlRegisterSingletonInstance(), QQmlEngine::singletonInstance() + 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 tags on properties declared with + 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 @@ -320,17 +376,37 @@ 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() + \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_MINOR_VERSION() is present on a different type or namespace of + \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. @@ -339,7 +415,7 @@ 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() + \sa QML_REMOVED_IN_VERSION, QML_ELEMENT, QML_NAMED_ELEMENT */ /*! @@ -364,7 +440,7 @@ \note Keeping multiple \l{PAST_MAJOR_VERSIONS} around is computationally expensive. - \sa QML_ELEMENT, QML_ADDED_IN_MINOR_VERSION + \sa QML_ELEMENT, QML_ADDED_IN_VERSION */ /*! @@ -376,6 +452,8 @@ {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} */ @@ -391,6 +469,8 @@ \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} */ @@ -434,6 +514,8 @@ \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 */ @@ -444,8 +526,9 @@ 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_ATTACHED(), \l QML_EXTENDED(), or \l QML_EXTENDED_NAMESPACE() macros + \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 @@ -455,9 +538,15 @@ for example because they belong to 3rdparty libraries. To register a namespace, see \l QML_FOREIGN_NAMESPACE(). - \b{NOTE:} You may want to use \l QML_NAMED_ELEMENT() instead of \l QML_ELEMENT due to the fact that - the element will be named like the struct it is contained in, not the foreign type. - See \l {Extending QML - Extension Objects Example} for an example. + \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() */ @@ -468,6 +557,7 @@ 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 @@ -527,11 +617,14 @@ \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 @@ -543,39 +636,39 @@ containers like this: \code - class Person : public QObject - { - Q_OBJECT - QML_ELEMENT - [...] - }; - - class Thing + class IntDequeRegistration { Q_GADGET - QML_VALUE_TYPE(thing) - [...] - }; - - class PersonListRegistration - { - Q_GADGET - QML_FOREIGN(QList<Person *>) + QML_FOREIGN(std::deque<int>) QML_ANONYMOUS - QML_SEQUENTIAL_CONTAINER(Person *) + QML_SEQUENTIAL_CONTAINER(int) }; + \endcode + + After this, you can use the container like a JavaScript array in QML. - class ThingListRegistration + \code + class Maze { - Q_GADGET - QML_FOREIGN(std::vector<Thing>) - QML_ANONYMOUS - QML_SEQUENTIAL_CONTAINER(Thing) - }; + Q_OBJECT + Q_ELEMENT + // 0: North, 1: East, 2: South, 3: West + Q_PROPERTY(std::deque<int> solution READ solution CONSTANT FINAL) + [...] + } \endcode - After this, you can use the respective containers like JavaScript arrays - in QML. + \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. @@ -586,6 +679,8 @@ 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() */ @@ -623,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 @@ -676,7 +771,7 @@ */ /*! - \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 @@ -695,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 @@ -714,7 +809,7 @@ */ /*! - \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 @@ -729,7 +824,7 @@ /*! - \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 @@ -775,7 +870,7 @@ Key1, Key2, }; - Q_ENUMS(MyEnum) + Q_ENUM_NS(MyEnum) } //... @@ -844,7 +939,7 @@ */ /*! - \fn int qmlRegisterAnonymousType(const char *uri, int versionMajor) + \fn template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor) \relates QQmlEngine This template function registers the C++ type in the QML system as an anonymous type. The @@ -962,7 +1057,7 @@ */ /*! - \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 @@ -1036,7 +1131,7 @@ 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 QML_ATTACHED(), {Providing Attached Properties} @@ -1053,7 +1148,7 @@ */ /*! - \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 @@ -1145,15 +1240,6 @@ \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML} */ - -/*! - \fn int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject*(QQmlEngine *, QJSEngine *)> callback) - \relates QQmlEngine - - \overload qmlRegisterSingletonType - \since 5.14 -*/ - /*! \fn int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName) \relates QQmlEngine @@ -1373,6 +1459,10 @@ Returns -1 if no matching type was found or one of the given parameters was invalid. + \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() */ @@ -1398,7 +1488,7 @@ /*! \macro QML_CONSTRUCTIBLE_VALUE - \internal + \since 6.5 \relates QQmlEngine Marks the surrounding value type as constructible. That is, any \l Q_INVOKABLE @@ -1413,6 +1503,7 @@ Q_GADGET QML_VALUE_TYPE(myValueType) QML_CONSTRUCTIBLE_VALUE + public: Q_INVOKABLE MyValueType(double d); // ... @@ -1428,12 +1519,35 @@ } \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 - \internal + \since 6.5 \relates QQmlEngine Marks the surrounding value type as structured. Structured value types can @@ -1468,5 +1582,31 @@ 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 dde54e2af6..df609fb3b9 100644 --- a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc @@ -221,167 +221,4 @@ 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. - -\section1 Pragmas - -You can prepend global instructions to a QML document using the \c pragma -keyword. The following pragmas are supported: - -\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 - -The same declaration can also be given for C++-defined types. See -\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} - -\section2 ComponentBehavior - -With this pragma you can restrict components defined in this file to only -create objects within their original context. This holds for inline -components as well as Component elements explicitly or implicitly created -as properties. If a component is bound to its context, you can safely -use IDs from the rest of the file within the component. Otherwise, the -engine and the QML tooling cannot know in advance what type, if any, such -IDs will resolve to at run time. - -In order to bind the components to their context specify the \c{Bound} -argument: - -\qml -pragma ComponentBehavior: Bound -\endqml - -The default 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. By default the interpreter and JIT ignore type annotations, but -the \l{QML Script Compiler} enforces them when compiling to C++. - -Specifying \c{Enforce} as value makes sure the type annotations are always -enforced. The resulting type coercions increase the overhead of calling -typed JavaScript functions. - -Specifying \c{Ignore} as value makes the \l{QML Script Compiler} ignore -any JavaScript functions when compiling the document to C++. This means less -code is compiled to C++ ahead of time, and more code has to be interpreted or -JIT-compiled. - -\sa {Type annotations and assertions} - -\section2 ValueTypeBehavior - -The behavior of \l{QML Value Types} and list types differs slightly -depending on whether a QML document is compiled to C++ using the -\l{QML Script Compiler} or interpreted at run time. - -With this pragma you can change the way value types and sequences are handled -when retrieved as locals from properties. By default, the interpreter and JIT -treat all value types and sequences as references. This means, if you change -the local value, the original property is also changed. Furthermore, if you -write the original property explicitly, the local value is also updated. - -When compiled to C++ using the \l{QML Script Compiler}, the local value is not -updated when the property is written, and the property is only updated when -written directly, without retrieving it as local value before. - -For example, the following code prints "1 1" when compiled to C++ and "5 5" -when interpreted or JIT-compiled: - -\qml -import QtQml - -QtObject { - id: root - - property rect r: ({x: 1, y: 2, width: 3, height: 4}) - property list<double> numbers: [1, 2, 3, 4, 5] - - function manipulate() { - root.r = {x: 5, y: 6, width: 7, height: 8}; - root.numbers = [5, 4, 3, 2, 1]; - } - - Component.onCompleted: { - var numbers = root.numbers; - var r = root.r; - manipulate() - console.log(r.x, numbers[0]); - } -} -\endqml - -You may notice that the behavior when interpreted or JIT-compiled can be rather -confusing. - -Specifying \c{Copy} as value to the pragma makes the interpreter and JIT behave -like the generated C++ code. This is the recommended way to handle the problem. -Specifying \c{Reference} makes the \l{QML Script Compiler} skip any functions -that use value types or sequences when generating C++ code. Those functions are -then left to be interpreted or JIT-compiled with the default behavior of the -interpreter and JIT. - */ diff --git a/src/qml/doc/src/qmllanguageref/documents/scope.qdoc b/src/qml/doc/src/qmllanguageref/documents/scope.qdoc index 87cb191a19..0bbbcae178 100644 --- a/src/qml/doc/src/qmllanguageref/documents/scope.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/scope.qdoc @@ -4,6 +4,7 @@ \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 2c3f6fe7bd..72a6e08407 100644 --- a/src/qml/doc/src/qmllanguageref/documents/structure.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/structure.qdoc @@ -6,9 +6,10 @@ \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 @@ -19,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/modules/identifiedmodules.qdoc b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc index fff697dd8e..93461f1ed7 100644 --- a/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc @@ -153,7 +153,6 @@ 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 @@ -170,10 +169,9 @@ 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/qqmlextensionplugin.qdocinc b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc index fca702a278..771d520f8a 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc +++ b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc @@ -62,85 +62,3 @@ that's part of the same binary as the registration: volatile auto registration = &qml_register_types_my_module; Q_UNUSED(registration); \endcode - -\section1 TimeExample QML Extension 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. It declares a QML type called \c Time via \l QML_NAMED_ELEMENT(). - -\snippet qmlextensionplugins/timemodel.h 0 -\dots - -To make this type available, create a plugin class named \c QExampleQmlPlugin, -which is a subclass of \l QQmlEngineExtensionPlugin. It uses the -Q_PLUGIN_METADATA() macro in the class definition to register the plugin with -the Qt meta object system using a unique identifier for the plugin. - -\snippet qmlextensionplugins/plugin.cpp plugin - -\section1 Build Settings for the Plugin - -The build file defines the project as a plugin library, specifies it should be -built into the \c imports/TimeExample directory, and registers the plugin -target name. - -\section2 Using CMake: - -\snippet qmlextensionplugins/CMakeLists.txt 0 - -\snippet qmlextensionplugins/CMakeLists.txt 1 - -\section2 Using qmake: - -\code -TEMPLATE = lib -CONFIG += qt plugin qmltypes -QT += qml - -QML_IMPORT_NAME = TimeExample -QML_IMPORT_MAJOR_VERSION = 1 - -DESTDIR = imports/$$QML_IMPORT_NAME -TARGET = qmlqtimeexampleplugin - -SOURCES += qexampleqmlplugin.cpp -\endcode - -This registers the \c TimeModel class, with the import \c{TimeExample 1.0}, as -a QML type called \c Time. The \l{Defining QML Types from C++} article has more -information about registering C++ types for usage in QML. - -\section1 Plugin Definition in the qmldir - -Finally, a \l {Module Definition qmldir Files} {qmldir file} is required -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. - -CMake will, by default, automatically generate this file. For more -information, see \l {Auto-generating qmldir and typeinfo files}. - -When using qmake, specify the following in the \c qmldir file: - -\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 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, 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}. diff --git a/src/qml/doc/src/qmllanguageref/qmlreference.qdoc b/src/qml/doc/src/qmllanguageref/qmlreference.qdoc index 4b873d9a0f..7f92129fcf 100644 --- a/src/qml/doc/src/qmllanguageref/qmlreference.qdoc +++ b/src/qml/doc/src/qmllanguageref/qmlreference.qdoc @@ -14,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 @@ -49,6 +49,7 @@ 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} @@ -60,6 +61,8 @@ modules. \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 809755ce16..ce2e48d41a 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/basics.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/basics.qdoc @@ -24,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 @@ -33,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 06cc5e13e1..f653ba452b 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc @@ -85,15 +85,29 @@ 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 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. +\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 diff --git a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc index 27489445ae..c19ac3eeec 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc @@ -12,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 @@ -112,7 +110,7 @@ Rectangle { In this case, the engine will emit an error and refuse to load the file. -\section4 C++ Module Imports +\section3 C++ Module Imports 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 @@ -122,7 +120,7 @@ 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++. -\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 @@ -172,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 @@ -198,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. @@ -211,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. @@ -254,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} @@ -292,6 +290,11 @@ 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 60e90217f4..2b1803042e 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2017 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -50,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 @@ -200,7 +200,7 @@ definition becomes: An example of property value initialization follows: \qml -import QtQuick 2.0 +import QtQuick Rectangle { color: "red" @@ -222,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 @@ -262,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 @@ -327,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: [ @@ -341,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" } @@ -352,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 @@ -470,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 @@ -498,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 @@ -585,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 @@ -621,10 +611,34 @@ 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 @@ -671,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: @@ -684,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 @@ -743,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 @@ -776,7 +790,7 @@ may be hidden and become inaccessible.) Here are three examples of signal declarations: \qml -import QtQuick 2.0 +import QtQuick Item { signal clicked @@ -795,7 +809,7 @@ 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. @@ -840,7 +854,7 @@ Rectangle { MouseArea { anchors.fill: parent onReleased: root.deactivated() - onPressed: (mouse)=> root.activated(mouse.x, mouse.y) + onPressed: mouse => root.activated(mouse.x, mouse.y) } } \endqml @@ -853,7 +867,9 @@ provided by the client: // myapplication.qml SquareButton { onDeactivated: console.log("Deactivated!") - onActivated: (xPosition, yPosition)=> console.log("Activated at " + xPosition + "," + yPosition) + onActivated: (xPosition, yPosition) => { + console.log(`Activated at ${xPosition}, ${yPosition}`) + } } \endqml @@ -875,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 @@ -920,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() : real { + function calculateHeight(): real { return rect.width / 2; } @@ -939,14 +955,14 @@ 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: (mouse)=> label.moveTo(mouse.x, mouse.y) + onClicked: mouse => label.moveTo(mouse.x, mouse.y) } Text { @@ -991,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 @@ -1015,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 } @@ -1048,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 @@ -1058,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. } } } @@ -1073,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 } } } @@ -1117,8 +1133,8 @@ 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 diff --git a/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc index 92e2e81869..b40181b49c 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/signals.qdoc @@ -54,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. @@ -97,6 +104,7 @@ import QtQuick Item { id: myitem + signal errorOccurred(message: string, line: int, column: int) } \endqml @@ -113,7 +121,7 @@ signal. If you do not need to handle all parameters, it is possible to omit trailing ones: \qml Status { - onErrorOccurred: function (message) { console.log(message) } + onErrorOccurred: message => console.log(message) } \endqml @@ -247,7 +255,7 @@ Now any objects of the \c SquareButton can connect to the \c activated signal us \qml // myapplication.qml SquareButton { - onActivated: (xPosition, yPosition)=> console.log("Activated at " + xPosition + "," + yPosition) + onActivated: (xPosition, yPosition) => console.log(`Activated at {xPosition}, ${yPosition}`) } \endqml @@ -279,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 @@ -347,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/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 d332617b16..d4b09ab180 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc @@ -98,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 38196036d4..b1c5bce891 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc @@ -22,7 +22,7 @@ Wherever the type definitions come from, the engine will enforce type-safety for properties and instances of those types. -\section1 Value 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. @@ -32,6 +32,35 @@ passed as arguments to methods of objects. 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 JavaScript objects and arrays are supported by the QML engine. Any standard @@ -40,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: [] @@ -58,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 index dc5c99ea03..0bf849b155 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc @@ -7,16 +7,21 @@ QML supports built-in and custom value types. -A \e{value type} is one that is passed by value rather than by reference, such -as an \c int or a \c string. This contrasts with +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. 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. +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: @@ -40,22 +45,30 @@ 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 QML language are listed below: +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 example, the value types provided by the \c QtQuick module are listed below: + +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 useful functions for manipulating values of value types. +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++}. @@ -202,9 +215,10 @@ property is only invoked when the property is reassigned to a different object v /*! \qmlvaluetype string \ingroup qmlvaluetypes - \brief a free form text string. + \brief A free form text string. - The \c string type refers to a free form text string in quotes, e.g. "Hello world!". + 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 @@ -213,19 +227,43 @@ property is only invoked when the property is reassigned to a different object v Properties of type \c string are empty by default. - Strings have a \c length attribute that holds the number of characters in the - string. + 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. + 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: - 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. + \qml + var message = "There are %1 items" + var count = 20 + console.log(message.arg(count)) + \endqml - This value type is provided by the QML language. + The example above prints "There are 20 items". - \sa {QML Value Types} + 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} */ /*! 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/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 4efa25c989..67dd6a9fea 100644 --- a/src/qml/doc/src/qmltypereference.qdoc +++ b/src/qml/doc/src/qmltypereference.qdoc @@ -3,13 +3,13 @@ /*! \qmlmodule QtQml -\title Qt QML QML Types +\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. @@ -25,24 +25,29 @@ To use the module, import the \c QtQml module with the following statement: 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 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, are moved to a submodule, \c QtQml.Models. The \l{Qt QML Models QML -Types}{Qt QML Models} page has more information. +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 \l WorkerScript QML type belongs to the submodule +\l{Qt QML WorkerScript QML Types}{QtQml.WorkerScript}. -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. +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 \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 Value Types @@ -51,6 +56,21 @@ provided: \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 The following \l{qtqml-typesystem-objecttypes.html}{QML object types} are @@ -102,7 +122,6 @@ to a \l{QtQml::Date}{Date} object. /*! \qmlvaluetype point \ingroup qtqmlvaluetypes -\ingroup qtquickvaluetypes \brief a value with x and y attributes. The \c point type refers to a value with \c x and \c y attributes. @@ -132,7 +151,6 @@ Properties of type \c point are \c {Qt.point(0, 0)} by default. /*! \qmlvaluetype size \ingroup qtqmlvaluetypes -\ingroup qtquickvaluetypes \brief a value with width and height attributes. The \c size type refers to a value with has \c width and \c height attributes. @@ -172,7 +190,6 @@ is automatically converted into a QSizeF value. /*! \qmlvaluetype rect \ingroup qtqmlvaluetypes -\ingroup qtquickvaluetypes \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. diff --git a/src/qml/doc/src/qt6-changes.qdoc b/src/qml/doc/src/qt6-changes.qdoc index 1dfee995f9..4f95103a4f 100644 --- a/src/qml/doc/src/qt6-changes.qdoc +++ b/src/qml/doc/src/qt6-changes.qdoc @@ -68,7 +68,7 @@ Implicit conversions were done for strings that could be parsed as \list - \li color (use Qt.color instead instead), + \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) diff --git a/src/qml/doc/src/qtqml-cpp.qdoc b/src/qml/doc/src/qtqml-cpp.qdoc index 9e140c5674..236b90ab0a 100644 --- a/src/qml/doc/src/qtqml-cpp.qdoc +++ b/src/qml/doc/src/qtqml-cpp.qdoc @@ -2,12 +2,12 @@ // 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. -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 index 293546255f..3631a85b5f 100644 --- a/src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc +++ b/src/qml/doc/src/qtqml-qtquick-compiler-tech.qdoc @@ -7,7 +7,7 @@ \title Qt Quick Compiler \brief Overview of Qt Quick Compiler components -Qt Quick Compiler enables you to process QML and JavaScript code at compile +Qt Quick Compiler lets you process QML and JavaScript code at compile time, rather than at run time. This allows for: \list @@ -17,17 +17,17 @@ time, rather than at run time. This allows for: The Qt Quick Compiler consist of two components: \list - \li \l {QML Type Compiler} - \li \l {QML Script Compiler} + \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. -\subtitle The QML Type Compiler +\section1 The QML type compiler -The \l{QML Type Compiler}, \e(qmltc) compiles QML types to C++ classes. These C++ +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 @@ -38,12 +38,16 @@ 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. -\subtitle The QML Script Compiler +\section1 The QML script compiler -The \l{QML Script Compiler}, (\e qmlsc and \e qmlcachegen) compiles bindings and +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. At compile time, for each QML or JavaScript +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: @@ -63,7 +67,7 @@ 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}. +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 @@ -89,7 +93,7 @@ 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. -\subtitle Summary +\section1 Summary The following table summarizes the differences between \l{qmltc}, \l{qmlcachegen} and \l{qmlsc}: diff --git a/src/qml/doc/src/qtqml-tool-qmlsc.qdoc b/src/qml/doc/src/qtqml-tool-qmlsc.qdoc deleted file mode 100644 index b1276449fc..0000000000 --- a/src/qml/doc/src/qtqml-tool-qmlsc.qdoc +++ /dev/null @@ -1,30 +0,0 @@ -// Copyright (C) 2022 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -\page qtqml-tool-qmlsc.html -\title QML Script Compiler -\brief A tool to compile functions and expressions in QML. -\keyword qmlsc - -The QML Script Compiler, \c qmlsc will compile functions and expressions in QML -files of an application into C++ code within limitations set by the nature of -JavaScript. It replaces \e qmlcachegen, and simply generates C++ code in addition -to byte code for functions that can be exhaustively analyzed. The following flow -chart explains the compilation of \e qmlsc. - -\image qmlsc-compilation-scheme.png - -\section1 Limitations when compiling JavaScript - -Many JavaScript constructs cannot be efficiently represented in C++. \e qmlsc -skips the C++ code generation for functions that contain such constructs and -only generates byte code to be interpreted. Although, 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. - -\e qmlsc is available for commercial customers and some of its features are -merged into \e qmlcachegen, which continues to be available with all versions of -Qt. -*/ 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 index 68566f984a..c8a99f1a37 100644 --- a/src/qml/doc/src/qtqml-writing-a-module.qdoc +++ b/src/qml/doc/src/qtqml-writing-a-module.qdoc @@ -92,7 +92,7 @@ You can use the \l Q_IMPORT_QML_PLUGIN macro to create a reference to this symbo Add the following code to the main.cpp: \badcode -#include <QtQml/qqmlextensionplugin.h> +#include <QtQml/QQmlExtensionPlugin> Q_IMPORT_QML_PLUGIN(ExtraModulePlugin) \endcode @@ -104,10 +104,201 @@ CMakeLists.txt, link the plugin, not the backing library, into the main program: \skipto target_link_libraries \printuntil ) -\section1 Exporting Multiple Major Versions from The Same Module +\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 -URI argument, even if the individual types declare other versions in their +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 @@ -143,7 +334,7 @@ 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 or \c AUTO_RESOURCE_PREFIX and \l IMPORT_PATH can be used. +\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 @@ -206,11 +397,11 @@ qt_add_qml_module( If all QML modules are always loaded from the resource file system, you can deploy the application as a single binary. -Generally, you should pass the \c AUTO_RESOURCE_PREFIX without arguments to -\l{qt_add_qml_module}. This way, your modules are placed in -\c{:/qt/qml/} in the resource file system. Since Qt 6.5, -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 \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 diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc index 2da6a8c9e0..f44a7130e6 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -1,25 +1,19 @@ -// Copyright (C) 2020 The Qt Company Ltd. +// 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}. - -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. - -If you're new to QML and Qt Quick, see \l{QML Applications} for an -introduction to writing QML applications. +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}. \section1 Using the Module @@ -27,10 +21,23 @@ introduction to writing QML applications. \include {module-use.qdocinc} {using the qml api} {QtQml} +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 \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. + \section2 C++ API \include {module-use.qdocinc} {using the c++ api} +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. + \section3 Building with CMake \include {module-use.qdocinc} {building with cmake} {Qml} @@ -46,125 +53,52 @@ See \l{qt6_generate_foreign_qml_types} for details. \include {module-use.qdocinc} {building_with_qmake} {qml} -\section1 QML and QML Types - -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}. - -In addition to the \l{QML Value 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 - -The \l{QtQml::Qt}{Qt} global object provides useful enums and functions -for various QML types. - -\section2 Lists and Models - -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. - -\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++. - -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 +\section1 Tweaking the engine -\section1 Integrating QML with C++ Applications +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. -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. +\section1 Articles and Guides -\section2 Articles and Guides +These articles contain information about Qt Qml. \list - \li \l {Overview - QML and C++ Integration} - \li \l {Data Type Conversion Between QML and C++} - \li \l {Integrating with JavaScript values from C++} - \li \l {Exposing Attributes of C++ Types to QML} - \li \l {Defining QML Types from C++} - \li \l {Writing QML Modules} - \li \l {Important C++ Classes Provided By The Qt QML Module} + \li \l{The QML Reference} + \li \l{Qt Qml Tooling} + \li \l{Writing QML Modules} + \li \l{Singletons in QML} \endlist -\section2 Examples +\section1 Reference \list - \li \l {Writing QML Extensions with C++} + \li \l {Qt Qml C++ Classes} {C++ Classes} + \li \l {Qt Qml QML Types} {QML Types} \endlist -\omit - \section1 Additional Frameworks - \list - \li \l{The Declarative State Machine Framework} - \endlist -\endomit - \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 Related Articles and Guides - -Further information for writing QML applications: -\list - \li \l {The QML Reference} - \li \l {Qt Quick Compiler} - - overview of Qt Quick Compiler components - \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 - \li \l {The QML Disk Cache} - - how to fine tune if and where the QML engine caches compilation - results -\endlist - -\section1 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/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/qtqml-tool-qmltc.qdoc b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-type-compiler.qdoc index a9e9256926..38f8fe039b 100644 --- a/src/qml/doc/src/qtqml-tool-qmltc.qdoc +++ b/src/qml/doc/src/tools/qtquickcompiler/qtqml-qml-type-compiler.qdoc @@ -2,16 +2,17 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qtqml-tool-qmltc.html -\title QML Type Compiler +\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 +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 Qt Quick Compiler +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 @@ -45,7 +46,14 @@ 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} advice. +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 @@ -105,9 +113,18 @@ 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. Given a -\c{myApp.qml} file, the application code (in both cases) would typically look -like this: +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} @@ -212,9 +229,6 @@ aspects remain. For instance: declarations. \endlist -\note \c qmltc does not guarantee that the generated C++ stays API-, source- or -binary-compatible between releases. - 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{.}, @@ -235,20 +249,13 @@ could be a challenge. \section2 Known Limitations Despite covering many common QML features, qmltc is still in the early stage of -development with many things yet to be supported. To name a few: - -\list - \li Translation APIs (qsTr() and similar methods) +development with some things yet to be supported. - \li Inline components - - \li Imported QML modules that consist of QML-defined types (such as - \c{QtQuick.Controls}). 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 - - \li Singleton QML types -\endlist +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: @@ -268,6 +275,7 @@ On top of this, there are some more fundamental peculiarities to consider: 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/qtqml-tool-qmlcachegen.qdoc b/src/qml/doc/src/tools/qtquickcompiler/qtqml-tool-qmlcachegen.qdoc index 8a30e49717..b7f6d56705 100644 --- a/src/qml/doc/src/qtqml-tool-qmlcachegen.qdoc +++ b/src/qml/doc/src/tools/qtquickcompiler/qtqml-tool-qmlcachegen.qdoc @@ -5,6 +5,7 @@ \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 |