diff options
Diffstat (limited to 'src/qml/doc/src')
24 files changed, 215 insertions, 112 deletions
diff --git a/src/qml/doc/src/cmake/cmake-properties.qdoc b/src/qml/doc/src/cmake/cmake-properties.qdoc index 0b8d2c9367..98858ca6d1 100644 --- a/src/qml/doc/src/cmake/cmake-properties.qdoc +++ b/src/qml/doc/src/cmake/cmake-properties.qdoc @@ -13,7 +13,7 @@ CMake source file properties: /*! -\page cmake-source-file-property-QT_QML_INTERNAL_TYPE.html +\page cmake-source-file-property-qt-qml-internal-type.html \ingroup cmake-source-file-properties-qtqml \title QT_QML_INTERNAL_TYPE @@ -30,7 +30,7 @@ Set this property to \c TRUE to indicate that the \c{.qml} file provides an inte /*! -\page cmake-source-file-property-QT_QML_SINGLETON_TYPE.html +\page cmake-source-file-property-qt-qml-singleton-type.html \ingroup cmake-source-file-properties-qtqml \title QT_QML_SINGLETON_TYPE @@ -53,7 +53,7 @@ how to set the \c QT_QML_SINGLETON_TYPE property. /*! -\page cmake-source-file-property-QT_QML_SKIP_CACHEGEN.html +\page cmake-source-file-property-qt-qml-skip-cachegen.html \ingroup cmake-source-file-properties-qtqml \title QT_QML_SKIP_CACHEGEN @@ -72,7 +72,7 @@ The file will still be added to the \c target as a resource in uncompiled form /*! -\page cmake-source-file-property-QT_QML_SKIP_QMLDIR_ENTRY.html +\page cmake-source-file-property-qt-qml-skip-qmldir-entry.html \ingroup cmake-source-file-properties-qtqml \title QT_QML_SKIP_QMLDIR_ENTRY @@ -91,7 +91,7 @@ the \c{.qml} file from being added as a type to the QML module's typeinfo file /*! -\page cmake-source-file-property-QT_QML_SKIP_QMLLINT.html +\page cmake-source-file-property-qt-qml-skip-qmllint.html \ingroup cmake-source-file-properties-qtqml \title QT_QML_SKIP_QMLLINT @@ -109,7 +109,7 @@ Set this property to \c TRUE to prevent the file from being included in /*! -\page cmake-source-file-property-QT_QML_SOURCE_TYPENAME.html +\page cmake-source-file-property-qt-qml-source-typename.html \ingroup cmake-source-file-properties-qtqml \title QT_QML_SOURCE_TYPENAME @@ -126,7 +126,7 @@ Use this property to override the \c QML type name provided by this file. /*! -\page cmake-source-file-property-QT_QML_SOURCE_VERSIONS.html +\page cmake-source-file-property-qt-qml-source-versions.html \ingroup cmake-source-file-properties-qtqml \title QT_QML_SOURCE_VERSIONS @@ -145,7 +145,7 @@ version after the \c{.0} release, specify those versions using this property. /*! -\page cmake-source-file-property-QT_QMLTC_FILE_BASENAME.html +\page cmake-source-file-property-qt-qmltc-file-basename.html \ingroup cmake-source-file-properties-qtqml \title QT_QMLTC_FILE_BASENAME @@ -163,7 +163,7 @@ conflicting file names. */ /*! -\page cmake-source-file-property-QT_QML_SKIP_TYPE_COMPILER.html +\page cmake-source-file-property-qt-qml-skip-type-compiler.html \ingroup cmake-source-file-properties-qtqml \title QT_QML_SKIP_TYPE_COMPILER diff --git a/src/qml/doc/src/cmake/cmake-variables.qdoc b/src/qml/doc/src/cmake/cmake-variables.qdoc index 15f73f074e..574b24e970 100644 --- a/src/qml/doc/src/cmake/cmake-variables.qdoc +++ b/src/qml/doc/src/cmake/cmake-variables.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page cmake-variable-QT_QML_OUTPUT_DIRECTORY.html +\page cmake-variable-qt-qml-output-directory.html \ingroup cmake-variables-qtqml \title QT_QML_OUTPUT_DIRECTORY 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 20c343a1bd..e20876fede 100644 --- a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc +++ b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_qml_module.html +\page qt-add-qml-module.html \ingroup cmake-commands-qtqml \title qt_add_qml_module @@ -364,8 +364,12 @@ been created. When \c NO_CREATE_PLUGIN_TARGET is given, \c PLUGIN_TARGET must also be provided to explicitly name the plugin target. Every QML module must define a \c URI. It should be specified in dotted URI -notation, such as \c{QtQuick.Layouts}. It must not contain anything other than -alphanumeric or dot characters. Other QML modules may use this name in +notation, such as \c{QtQuick.Layouts}. Each segment must be a well-formed +ECMAScript Identifier Name. This means, for example, the segments +must not start with a number and they must not contain \e{-} (minus) +characters. As the \c URI will be translated into directory names, you +should restrict it to alphanumeric characters of the latin alphabet, +underscores, and dots. Other QML modules may use this name in \l{qtqml-syntax-imports.html}{import statements} to import the module. The \c URI will be used in the \c module line of the generated \l{Module Definition qmldir Files}{qmldir} file. The \c URI is also used to diff --git a/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc index cb98406a9d..2ce744559c 100644 --- a/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc +++ b/src/qml/doc/src/cmake/qt_add_qml_plugin.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_qml_plugin.html +\page qt-add-qml-plugin.html \ingroup cmake-commands-qtqml \title qt_add_qml_plugin 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 92da84733e..cc3c61863c 100644 --- a/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc +++ b/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_deploy_qml_imports.html +\page qt-deploy-qml-imports.html \ingroup cmake-commands-qtqml \title qt_deploy_qml_imports @@ -18,7 +18,7 @@ project. \preliminarycmakecommand -\include cmake-qml-qt-finalize-target-warning.cmake +\include cmake-qml-qt-finalize-target-warning.qdocinc \section1 Synopsis 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 493a4fc029..fc78baddcd 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 @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_generate_deploy_qml_app_script.html +\page qt-generate-deploy-qml-app-script.html \ingroup cmake-commands-qtqml \title qt_generate_deploy_qml_app_script @@ -15,7 +15,7 @@ \cmakecommandsince 6.3 \preliminarycmakecommand -\include cmake-qml-qt-finalize-target-warning.cmake +\include cmake-qml-qt-finalize-target-warning.qdocinc \section1 Synopsis 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 856f0fe2b1..9bd412d36d 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 @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_generate_foreign_qml_types.html +\page qt-generate-foreign-qml-types.html \ingroup cmake-commands-qtqml \title qt_generate_foreign_qml_types @@ -67,4 +67,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_import_qml_plugins.qdoc b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc index b45e47ce55..8d6b32f903 100644 --- a/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc +++ b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_import_qml_plugins.html +\page qt-import-qml-plugins.html \ingroup cmake-commands-qtqml \title qt_import_qml_plugins diff --git a/src/qml/doc/src/cmake/qt_query_qml_module.qdoc b/src/qml/doc/src/cmake/qt_query_qml_module.qdoc index 50996745c8..44d0a7f8da 100644 --- a/src/qml/doc/src/cmake/qt_query_qml_module.qdoc +++ b/src/qml/doc/src/cmake/qt_query_qml_module.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_query_qml_module.html +\page qt-query-qml-module.html \ingroup cmake-commands-qtqml \title qt_query_qml_module diff --git a/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc b/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc index d989c80fcf..0ef6e421ed 100644 --- a/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc +++ b/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_target_compile_qml_to_cpp.html +\page qt-target-compile-qml-to-cpp.html \ingroup cmake-commands-qtqml \title qt_target_compile_qml_to_cpp 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 126c9767a0..35854d4b95 100644 --- a/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc +++ b/src/qml/doc/src/cmake/qt_target_qml_sources.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_target_qml_sources.html +\page qt-target-qml-sources.html \ingroup cmake-commands-qtqml \title qt_target_qml_sources diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc index 5799fda87e..ac1c751bf2 100644 --- a/src/qml/doc/src/cppintegration/definetypes.qdoc +++ b/src/qml/doc/src/cppintegration/definetypes.qdoc @@ -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_MINOR_VERSION() macro to the class declaration. Clients can import suitable versions of the namespace in order to use the type. For example, suppose there is a \c Message class with \c author and @@ -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" diff --git a/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.cmake b/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.qdocinc index d3c7383d2e..9152726398 100644 --- a/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.cmake +++ b/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.qdocinc @@ -1,3 +1,6 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + \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 diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index 89b52131d9..005bd0be94 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -173,7 +173,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: @@ -260,7 +262,7 @@ // Initialize this using myObject where you would previously // call qmlRegisterSingletonInstance(). - static MySingleton *s_singletonInstance = nullptr; + inline static MySingleton *s_singletonInstance = nullptr; static MySingleton *create(QQmlEngine *, QJSEngine *engine) { @@ -284,7 +286,7 @@ } private: - static QJSEngine *s_engine = nullptr; + inline static QJSEngine *s_engine = nullptr; }; \endcode diff --git a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc index 80dabe45b9..58e2027e1c 100644 --- a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc @@ -29,8 +29,12 @@ The type name has the following requirements: This document is then automatically recognized by the engine as a definition of a QML type. Additionally, a type defined in this manner is automatically made -available to other QML files within the same directory as the engine searches -within the immediate directory when resolving QML type names. +available to other QML files within the same local directory as the engine +searches within the immediate directory when resolving QML type names. + +\note The QML engine does not automatically search remote directories this way. +You have to add a qmldir file if your documents are loaded over the network. See +\l{Importing QML Document Directories}. \section2 Custom QML Type Definition @@ -251,14 +255,14 @@ The same declaration can also be given for C++-defined types. See \section2 ComponentBehavior With this pragma you can restrict components defined in this file to only -create objects within the context of the same file. This holds for inline +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 a file context, you can safely +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 the file scope specify the \c{Bound} +In order to bind the components to their context specify the \c{Bound} argument: \qml @@ -268,7 +272,7 @@ pragma ComponentBehavior: Bound 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 the file context don't receive their own +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 diff --git a/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc index 6e8751af70..93461f1ed7 100644 --- a/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc @@ -20,6 +20,12 @@ Identified modules must be installed into the \l{qtqml-syntax-imports.html#qml-import-path}{import path} in order to be found by the QML engine. +Syntactically, each dot-separated segment of the URI must be a well-formed +ECMAScript Identifier Name. This means, for example, the segments must not start +with a number and they must not contain \e{-} (minus) characters. As the URI +will be translated into directory names, you should restrict it to alphanumeric +characters of the latin alphabet, underscores, and dots. + \section1 Locally Installed Identified Modules A directory of QML and/or C++ files can be shared as an identified module if it @@ -147,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 @@ -164,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/qmldir.qdoc b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc index c6d5e1446b..ac82d8136e 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc @@ -419,7 +419,7 @@ documentation on this, no further action is needed. qmltyperegistrar will automatically generate the \c .qmltypes files. Example: -If your module is in \c /tmp/imports/My/Module, a file caled \c plugins.qmltypes +If your module is in \c /tmp/imports/My/Module, a file called \c plugins.qmltypes should be generated alongside the actual plugin binary. Add the line diff --git a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc index c37fb81401..fca702a278 100644 --- a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc +++ b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc @@ -38,6 +38,14 @@ plugins. Library plugins should limit themselves to registering types, as any manipulation of the engine's root context may cause conflicts or other issues in the library user's code. +\note When using the CMake \l qt_add_qml_module API, a plugin will be generated +automatically for you. It will take care of type registration. +You only need to write a custom plugin if you have special +requirements, such as registering custom image +providers. In that case, pass +\l{NO_GENERATE_PLUGIN_SOURCE} to the \c qt_add_qml_module +call to disable the generation of the default plugin. + The linker might erroneously remove the generated type registration function as an optimization. You can prevent that by declaring a synthetic volatile pointer to the function somewhere in your code. If your module is diff --git a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc index 37298c8caf..7126033431 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc @@ -85,6 +85,11 @@ a file system path. A directory of QML files can also be imported from a remote location if the directory contains a directory listing \c qmldir file. +\note This also holds for the implicit import of the directory a QML document +resides in. If your QML documents are loaded from a remote location, you need +to add qmldir files even if they don't contain any explicit directory import +statements. Otherwise your QML documents won't see each other. + For example, if the \c myapp directory in the previous example was hosted at "http://www.my-example-server.com", and the \c mycomponents directory contained a \c qmldir file defined as follows: diff --git a/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/imports.qdoc index a6158b14af..6e6088049c 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} diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc index bbc5aae0f0..60e90217f4 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc @@ -32,6 +32,7 @@ The set of QML object-type attribute types is as follows: These attributes are discussed in detail below. \section2 The \e id Attribute +\keyword QML.id Every QML object type has exactly one \e id attribute. This attribute is provided by the language itself, and cannot be redefined or overridden by any diff --git a/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc index ef10620422..e497d5d5c8 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc @@ -40,7 +40,7 @@ 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 list must be used in conjunction with a QML object type + \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 @@ -285,16 +285,7 @@ property is only invoked when the property is reassigned to a different object v The \c list type refers to a list of QML objects or values. - A list value can be accessed in a similar way to a JavaScript array: - - \list - \li Values are assigned using the \c[] square bracket syntax with comma-separated values - \li The \c length property provides the number of items in the list - \li Values in the list are accessed using the \c [index] syntax - \endlist - - Values can be dynamically added to the list by using the \c push method, - as if it were a JavaScript Array + Properties of type \c list are empty by default. A \c list can store QML objects or \l{QML Value Types}{value type} values. @@ -311,7 +302,7 @@ property is only invoked when the property is reassigned to a different object v can be assigned to and used as follows: \qml - import QtQuick 2.0 + import QtQuick Item { width: 100; height: 100 @@ -335,7 +326,7 @@ property is only invoked when the property is reassigned to a different object v If the list only contains one object, the square brackets may be omitted: \qml - import QtQuick 2.0 + import QtQuick Item { width: 100; height: 100 @@ -343,17 +334,38 @@ property is only invoked when the property is reassigned to a different object v } \endqml - Objects and values in a list can be replaced with the \c{[]} operator, just - like entries of JavaScript arrays. You can also use \c{push()} to append - entries, or you can set the \c length property of the list to truncate or - extend it. You can not automatically extend the list by assigning to an - index currently out of range, though. Furthermore, if you insert \c null - values into a list of objects, those are converted to \c nullptr entries in + You can also declare your own list properties in QML: + + \qml + import QtQml + + QtObject { + property list<int> intList: [1, 2, 3, 4] + property list<QtObject> objectList + } + \endqml + + Lists can be used much like JavaScript arrays. For example: + + \list + \li Values are assigned using the \c[] square bracket syntax with comma-separated values + \li The \c length property provides the number of items in the list + \li Values in the list are accessed using the \c [index] syntax + \li You can use \c{push()} to append entries + \li You can set the \c length property of the list to truncate or extend it. + \endlist + + However, you can \e{not} automatically extend the list by assigning to an + index currently out of range. Furthermore, if you insert \c null values + into a list of objects, those are converted to \c nullptr entries in the underlying QQmlListProperty. - A list of value types is different from a JavaScript array in one important - aspect: Growing it by setting its length does not produce undefined entries, - but rather default-constructed instances of the value type. + A list of value types is different from a JavaScript array in one further + important aspect: Growing it by setting its length does not produce undefined + entries, but rather default-constructed instances of the value type. + + Similarly, growing a list of object types this way produces null entries, + rather than undefined entries. This value type is provided by the QML language. @@ -461,6 +473,36 @@ property is only invoked when the property is reassigned to a different object v */ /*! + \qmlvaluetype variant + \ingroup qmlvaluetypes + \brief a generic property type. + + The \c variant type is the same as the \c var type. Use \c var instead. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype void + \ingroup qmlvaluetypes + \brief The empty value type. + + The \c void type is exclusively used to type-annotate JavaScript functions + returning \c undefined. For example: + + \qml + function doThings() : void { console.log("hello") } + \endqml + + This is to help tooling analyze calls to such functions and compile them and + their callers to C++. + + You cannot declare \c void properties in QML. + + \sa {QML Value Types} +*/ + +/*! \qmlvaluetype enumeration \ingroup qmlvaluetypes \brief a named enumeration value. diff --git a/src/qml/doc/src/qmltypereference.qdoc b/src/qml/doc/src/qmltypereference.qdoc index a89f89f9f7..da9d08d4e6 100644 --- a/src/qml/doc/src/qmltypereference.qdoc +++ b/src/qml/doc/src/qmltypereference.qdoc @@ -60,8 +60,7 @@ provided: /*! \qmlvaluetype date -\ingroup qtqmlvaluetypes -\ingroup qtquickvaluetypes +\ingroup qmlvaluetypes \brief a date value. The \c date type refers to a date value, including the time of the day. @@ -130,7 +129,7 @@ is automatically converted into a QPointF value. \qmlvaluetype size \ingroup qtqmlvaluetypes \ingroup qtquickvaluetypes -\brief a value with width and height attributes +\brief a value with width and height attributes. The \c size type refers to a value with has \c width and \c height attributes. diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc index 9d0a0e67a8..2da6a8c9e0 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -128,6 +128,20 @@ the QML code to interact with C++ code. \endlist \endomit +\section1 Licenses and Attributions + +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 +modules under following permissive licenses: + +\generatelist{groupsbymodule attributions-qtqml} + \section1 Related Articles and Guides Further information for writing QML applications: @@ -146,30 +160,11 @@ Further information for writing QML applications: results \endlist -\section1 Examples - -\list - \li \l {Qt QML Examples} {Examples} -\endlist - -\section2 Reference +\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 - -\section1 Licenses and Attributions - -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 -modules under following permissive licenses: - -\generatelist{groupsbymodule attributions-qtqml} */ |