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