diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref')
17 files changed, 725 insertions, 366 deletions
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} */ /*! |