diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc')
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc | 570 |
1 files changed, 5 insertions, 565 deletions
diff --git a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc index 5716f6c386..e0929f2879 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc @@ -1,570 +1,10 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-typesystem-basictypes.html \title QML Basic Types -\brief Description of basic types provided by the Qt QML module +\keyword QML Basic Types +\brief QML Value Types used to be called "Basic Types" -QML supports a number of basic types. - -A \e{basic type} is one that refers to a simple value, such as an \c int -or a \c string. This contrasts with a \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types}, -which refers to an object with properties, signals, methods and so on. Unlike an object type, -a basic 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. - -Basic types can be used to refer to: - -\list -\li A single value (e.g. \l int refers to a single number, \l var can refer to a single list of items) -\li A value that contains a simple set of property-value pairs (e.g. \l size refers to a value with \c width and \c height attributes) -\endlist - -When a variable or property holds a basic type and it is assigned to another -variable or property, then a copy of the value is made. In JavaScript, this -value is called a primitive value. - -\sa {qtqml-typesystem-topic.html}{The QML Type System} - - -\section1 Supported Basic Types - -Some basic types are supported by the engine by default and do not require an -\l {Import Statements}{import statement} to be used, while others do require -the client to import the module which provides them. -All of the basic 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 enumeration cannot be used directly as the enumeration must be defined by a registered QML object type -\endlist - -\section2 Basic Types Provided By The QML Language - -The basic types supported natively in the QML language are listed below: -\annotatedlist qmlbasictypes - -\section2 Basic Types Provided By QML Modules - -QML modules may extend the QML language with more basic types. -For example, the basic types provided by the \c QtQuick module are listed below: -\annotatedlist qtquickbasictypes - -The \l{QtQml::Qt}{Qt} global object provides useful functions for manipulating values of basic types. - -Currently only QML modules which are provided by Qt may provide their -own basic types, however this may change in future releases of Qt QML. -In order to use types provided by a particular QML module, clients -must import that module in their QML documents. - -\section1 Property Change Behavior for Basic Types - -Some basic types have properties: for example, the \l font type has -\c pixelSize, \c family and \c bold properties. Unlike properties of -\l{qtqml-typesystem-topic.html#qml-object-types}{object types}, properties of -basic types do not provide their own property change signals. It is only possible -to create a property change signal handler for the basic type property itself: - -\code -Text { - // invalid! - onFont.pixelSizeChanged: doSomething() - - // also invalid! - font { - onPixelSizeChanged: doSomething() - } - - // but this is ok - onFontChanged: doSomething() -} -\endcode - -Be aware, however, that a property change signal for a basic type is emitted -whenever \e any of its attributes have changed, as well as when the property itself -changes. Take the following code, for example: - -\qml -Text { - onFontChanged: console.log("font changed") - - Text { id: otherText } - - focus: true - - // changing any of the font attributes, or reassigning the property - // to a different font value, will invoke the onFontChanged handler - Keys.onDigit1Pressed: font.pixelSize += 1 - Keys.onDigit2Pressed: font.b = !font.b - Keys.onDigit3Pressed: font = otherText.font -} -\endqml - -In contrast, properties of an \l{qtqml-typesystem-topic.html#qml-object-types}{object type} -emit their own property change signals, and a property change signal handler for an object-type -property is only invoked when the property is reassigned to a different object value. - -*/ - -/*! - \qmlbasictype int - \ingroup qmlbasictypes - \brief a whole number, e.g. 0, 10, or -20. - - The \c int type refers to a whole number, e.g. 0, 10, or -20. - - The possible \c int values range from -2147483648 to 2147483647, - although most types will only accept a reduced range (which they - mention in their documentation). - - Example: - \qml - NumberAnimation { loops: 5 } - \endqml - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype bool - \ingroup qmlbasictypes - \brief a binary true/false value. - - The \c bool type refers to a binary true/false value. - - Example: - \qml - Item { - focus: true - clip: false - } - \endqml - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype real - \ingroup qmlbasictypes - - \brief a number with a decimal point. - - The \c real type refers to a number with decimal point, e.g. 1.2 or -29.8. - - Example: - \qml - Item { width: 100.45; height: 150.82 } - \endqml - - \b{Note:} In QML all reals are stored in double precision, \l - {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} - format. - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype double - \ingroup qmlbasictypes - - \brief a number with a decimal point, stored in double precision. - - The \c double type refers to a number with a decimal point and is stored in double precision, \l - {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format. - - Example: - \qml - Item { - property double number: 32155.2355 - } - \endqml - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype string - \ingroup qmlbasictypes - \brief a free form text string. - - The \c string type refers to a free form text string in quotes, e.g. "Hello world!". - - Example: - \qml - Text { text: "Hello world!" } - \endqml - - 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. - - 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. - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \qmlbasictype url - \ingroup qmlbasictypes - \brief a resource locator. - - The \c url type refers to a resource locator (like a file name, for example). It can be either - absolute, e.g. "http://qt-project.org", or relative, e.g. "pics/logo.png". A relative URL is - resolved relative to the URL of the containing component. - - For example, the following assigns a valid URL to the \l {Image::source} - property, which is of type \c url: - - \qml - Image { source: "pics/logo.png" } - \endqml - - When integrating with C++, note that any QUrl value - \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically - converted into a \c url value, and vice-versa. - - Alternatively you may convert your \c url to a \l{https://developer.mozilla.org/en-US/docs/Web/API/URL}{URL} object - in order to access and modify its components: - \qml - var urlObject = new URL(url); - \endqml - - \section1 Using the url Type - - When a relative URL is written to a \c url type property, it is converted - into a URL object, so \b {matching the URL value against the input string - value will fail}. Instead, convert the string to a URL using Qt.resolvedUrl() - for means of comparison, and use \c toString() to get the contents of the URL: - - \qml - Image { - source: "pics/logo.png" - - Component.onCompleted: { - // This prints 'false'. Although "pics/logo.png" was the input string, - // it's been converted from a string to a URL, so these two are not the same. - console.log(source == "pics/logo.png") - - // This prints 'true' as Qt.resovledUrl() converts the string into a - // URL with the correctly resolved path - console.log(source == Qt.resolvedUrl("pics/logo.png")) - - // This prints the absolute path, e.g. "file:///path/to/pics/logo.png" - console.log(source.toString()) - } - } - \endqml - - \note When referring to files stored with the \l{resources.html}{Qt Resource System} - from within QML, you should use "qrc:///" instead of ":/" as QML requires URL paths. - Relative URLs resolved from within that file will use the same protocol. - - Additionally, URLs may contain encoded characters using the 'percent-encoding' scheme - specified by \l {http://tools.ietf.org/html/rfc3986}{RFC 3986}. These characters - will be preserved within properties of type \c url, to allow QML code to - construct precise URL values. - - For example, a local file containing a '#' character, which would normally be - interpreted as the beginning of the URL 'fragment' element, can be accessed by - encoding the characters of the file name: - - \qml - Image { source: encodeURIComponent("/tmp/test#1.png") } - \endqml - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - - -/*! - \qmlbasictype list - \ingroup qmlbasictypes - \brief a list of QML objects. - - The \c list type refers to a list of QML objects. - - 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 - - A \c list can only store QML objects, and cannot contain any - \l {QML Basic Types}{basic type} values. (To store basic types within a - list, use the \l var type instead.) - - When integrating with C++, note that any QQmlListProperty value - \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically - converted into a \c list value, and vice-versa. - - - \section1 Using the list Type - - For example, the \l Item type has a \l {Item::}{states} list-type property that - can be assigned to and used as follows: - - \qml - import QtQuick 2.0 - - Item { - width: 100; height: 100 - - states: [ - State { name: "activated" }, - State { name: "deactivated" } - ] - - Component.onCompleted: { - console.log("Name of first state:", states[0].name) - for (var i = 0; i < states.length; i++) - console.log("state", i, states[i].name) - } - } - \endqml - - The defined \l State objects will be added to the \c states list - in the order in which they are defined. - - If the list only contains one object, the square brackets may be omitted: - - \qml - import QtQuick 2.0 - - Item { - width: 100; height: 100 - states: State { name: "activated" } - } - \endqml - - Note that objects cannot be individually added to or removed from - the list once created; to modify the contents of a list, it must be - reassigned to a new list. - - \note The \c list type is not recommended as a type for custom properties. - The \c var type should be used instead for this purpose as - lists stored by the \c var type can be manipulated with greater - flexibility from within QML. - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - - /*! - \qmlbasictype var - \ingroup qmlbasictypes - \brief a generic property type. - - The \c var type is a generic property type that can refer to any data type. - - It is equivalent to a regular JavaScript variable. - For example, var properties can store numbers, strings, objects, - arrays and functions: - - \qml - Item { - property var aNumber: 100 - property var aBool: false - property var aString: "Hello world!" - property var anotherString: String("#FF008800") - property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5) - property var aRect: Qt.rect(10, 10, 10, 10) - property var aPoint: Qt.point(10, 10) - property var aSize: Qt.size(10, 10) - property var aVector3d: Qt.vector3d(100, 100, 100) - property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })] - property var anObject: { "foo": 10, "bar": 20 } - property var aFunction: (function() { return "one"; }) - } - \endqml - - \section1 Change Notification Semantics - - It is important to note that changes in regular properties of JavaScript - objects assigned to a var property will \b{not} trigger updates of bindings - that access them. The example below will display "The car has 4 wheels" as - the change to the wheels property will not cause the reevaluation of the - binding assigned to the "text" property: - - \qml - Item { - property var car: new Object({wheels: 4}) - - Text { - text: "The car has " + car.wheels + " wheels"; - } - - Component.onCompleted: { - car.wheels = 6; - } - } - \endqml - - If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"} - then the text would be updated to say "The car has 6 wheels", since the - car property itself would be changed, which causes a change notification - to be emitted. - - \section1 Property Value Initialization Semantics - - The QML syntax defines that curly braces on the right-hand-side of a - property value initialization assignment denote a binding assignment. - This can be confusing when initializing a \c var property, as empty curly - braces in JavaScript can denote either an expression block or an empty - object declaration. If you wish to initialize a \c var property to an - empty object value, you should wrap the curly braces in parentheses. - - For example: - \qml - Item { - property var first: {} // nothing = undefined - property var second: {{}} // empty expression block = undefined - property var third: ({}) // empty object - } - \endqml - - In the previous example, the \c first property is bound to an empty - expression, whose result is undefined. The \c second property is bound to - an expression which contains a single, empty expression block ("{}"), which - similarly has an undefined result. The \c third property is bound to an - expression which is evaluated as an empty object declaration, and thus the - property will be initialized with that empty object value. - - Similarly, a colon in JavaScript can be either an object property value - assignment, or a code label. Thus, initializing a var property with an - object declaration can also require parentheses: - - \qml - Item { - property var first: { example: 'true' } // example is interpreted as a label - property var second: ({ example: 'true' }) // example is interpreted as a property - property var third: { 'example': 'true' } // example is interpreted as a property - Component.onCompleted: { - console.log(first.example) // prints 'undefined', as "first" was assigned a string - console.log(second.example) // prints 'true' - console.log(third.example) // prints 'true' - } - } - \endqml - - \sa {QML Basic Types} -*/ -/* - TODO Qt 5.1: see explanation in expressions.qdoc - \section1 Using Scarce Resources with the var Type - - A \c var type property can also hold an image or pixmap. - A \c var which contains a QPixmap or QImage is known as a - "scarce resource" and the declarative engine will attempt to - automatically release such resources after evaluation of any JavaScript - expression which requires one to be copied has completed. - - Clients may explicitly release such a scarce resource by calling the - "destroy" method on the \c var property from within JavaScript. They - may also explicitly preserve the scarce resource by calling the - "preserve" method on the \c var property from within JavaScript. - - This basic type is provided by the QML language. -*/ - -/*! - \qmlbasictype enumeration - \ingroup qmlbasictypes - \brief a named enumeration value. - - The \c enumeration type refers to a named enumeration value. - - Each named value can be referred to as \c {<Type>.<value>}. For - example, the \l Text type has an \c AlignRight enumeration value: - - \qml - Text { horizontalAlignment: Text.AlignRight } - \endqml - - (For backwards compatibility, the enumeration value may also be - specified as a string, e.g. "AlignRight". This form is not - recommended for new code.) - - When integrating with C++, note that any \c enum value - \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically - converted into an \c enumeration value, and vice-versa. - - This basic type is provided by the QML language. Some enumeration values - are provided by the QtQuick import. - - \section1 Using the enumeration Type in QML - - The \c enumeration type is a representation of a C++ \c enum type. It is - not possible to refer to the \c enumeration type in QML itself; instead, the - \l int or \l var types can be used when referring to \c enumeration values - from QML code. - - For example: - - \qml - import QtQuick 2.0 - - Item { - // refer to Text.AlignRight using an int type - property int enumValue: textItem.horizontalAlignment - - signal valueEmitted(int someValue) - - Text { - id: textItem - horizontalAlignment: Text.AlignRight - } - - // emit valueEmitted() signal, which expects an int, with Text.AlignRight - Component.onCompleted: valueEmitted(Text.AlignRight) - } - \endqml - - \sa {QML Basic Types} - \sa {qtqml-syntax-objectattributes.html#enumeration-attributes}{Enumeration Attributes} +See \l{qtqml-typesystem-valuetypes.html} for the documentation of QML value types. */ |