diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc')
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc | 76 |
1 files changed, 57 insertions, 19 deletions
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} */ /*! |