diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/typesystem')
7 files changed, 798 insertions, 747 deletions
diff --git a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc index 5144fe219e..e0929f2879 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc @@ -1,681 +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 around -2000000000 to around 2000000000, - although most types will only accept a reduced range (which they - mention in their documentation). - - Example: - \qml - Item { width: 100; height: 200 } - \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. - - - \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. An exception to this rule is the preemptive - decoding of directory-separator characters (\c '/') - these characters are decoded - to allow the URL to be correctly classified. - - 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. -*/ - -/*! - \obsolete - \qmlbasictype variant - \ingroup qmlbasictypes - \brief a generic property type. - - The \c variant type is a generic property type. It is obsolete and exists only to - support old applications; new applications should use \l var type - properties instead. - - A variant type property can hold any of the \l {QML Basic Types}{basic type} - values: - - \qml - Item { - property variant aNumber: 100 - property variant aString: "Hello world!" - property variant aBool: false - } - \endqml - - When integrating with C++, note that any QVariant value - \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically - converted into a \c variant value, and vice-versa. - - - \section1 Using Scarce Resources with the variant Type - - A \c variant type property can also hold an image or pixmap. - A \c variant 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 variant property from within JavaScript. They - may also explicitly preserve the scarce resource by calling the - "preserve" method on the \c variant property from within JavaScript. - - \section1 Storing Arrays and Objects - - The \c variant type can also hold: - - \list - \li An array of \l {QML Basic Types}{basic type} values - \li A map of key-value pairs with \l {QML Basic Types}{basic-type} values - \endlist - - For example, below is an \c items array and an \c attributes map. Their - contents can be examined using JavaScript \c for loops. Individual array - values are accessible by index, and individual map values are accessible - by key: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - for (var i = 0; i < items.length; i++) - console.log(items[i]) - - for (var prop in attributes) - console.log(prop, "=", attributes[prop]) - } - } - \endqml - - While this is a convenient way to store array and map-type values, you - must be aware that the \c items and \c attributes properties above are \e not - QML objects (and certainly not JavaScript object either) and the key-value - pairs in \c attributes are \e not QML properties. Rather, the \c items - property holds an array of values, and \c attributes holds a set of key-value - pairs. Since they are stored as a set of values, instead of as an object, - their contents \e cannot be modified individually: - - \qml - Item { - property variant items: [1, 2, 3, "four", "five"] - property variant attributes: { 'color': 'red', 'width': 100 } - - Component.onCompleted: { - items[0] = 10 - console.log(items[0]) // This will still be '1'! - attributes.color = 'blue' - console.log(attributes.color) // This will still be 'red'! - } - } - \endqml - - Since it is not possible to individually add or remove items from a list or - object stored in a \c variant, the only way to modify its contents is to - reassign a new value. However, this is not efficient, as it causes the value - to be serialized and deserialized. - - Additionally, since \c items and \c attributes are not QML objects, changing - their individual values do not trigger property change notifications. If - the above example had \c onNumberChanged or \c onAnimalChanged signal - handlers, they would not have been called. If, however, the \c items or - \c attributes properties themselves were reassigned to different values, then - such handlers would be called. - - JavaScript programmers should also note that when a JavaScript object is - copied to an array or map property, the \e contents of the object (that is, - its key-value properties) are copied, rather than the object itself. The - property does not hold a reference to the original JavaScript object, and - extra data such as the object's JavaScript prototype chain is also lost in - the process. - - This basic type is provided by the QML language. - - \sa {QML Basic Types} -*/ - -/*! - \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. */ 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 5f089b5ebc..d4b09ab180 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** 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) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-typesystem-objecttypes.html \title QML Object Types @@ -34,7 +10,7 @@ A QML object type is a type from which a QML object can be instantiated. In syntactic terms, a QML object type is one which can be used to declare an object by specifying the \e{type name} followed by a set of curly braces that -encompasses the attributes of that object. This differs from \e {basic types}, +encompasses the attributes of that object. This differs from \e {value types}, which cannot be used in the same way. For example, \l Rectangle is a QML object type: it can be used to create \c Rectangle type objects. This cannot be done with primitive types such as \c int and \c bool, which are used to hold simple @@ -48,6 +24,9 @@ and registering the type with the QML engine, as discussed in Note that in both cases, the type name must begin with an uppercase letter in order to be declared as a QML object type in a QML file. +For more information about C++ and the different QML integration methods, +see the +\l {Overview - QML and C++ Integration} {C++ and QML integration overview} page. \section1 Defining Object Types from QML @@ -119,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 a5f730e8d4..b1c5bce891 100644 --- a/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc +++ b/src/qml/doc/src/qmllanguageref/typesystem/topic.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** 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) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-typesystem-topic.html \title The QML Type System @@ -46,15 +22,44 @@ Wherever the type definitions come from, the engine will enforce type-safety for properties and instances of those types. -\section1 Basic 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. Objects may have properties of these types, and values of these types may be passed as arguments to methods of objects. -See the \l{qtqml-typesystem-basictypes.html}{QML Basic Types} documentation for -more information about basic types. +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 @@ -64,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: [] @@ -82,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 new file mode 100644 index 0000000000..0bf849b155 --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/typesystem/valuetypes.qdoc @@ -0,0 +1,606 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! +\page qtqml-typesystem-valuetypes.html +\title QML Value Types +\brief Description of QML value types + +QML supports built-in and custom value types. + +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. 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: + +\list +\li A single value (e.g. \l int refers to a single number) +\li A value that contains properties and methods (e.g. \l size refers to a value with \c width and \c height properties) +\li The generic type \l{var}. It can hold values of any other type but is itself a value type. +\endlist + +When a variable or property holds a value type and it is assigned to another +variable or property, then a copy of the value is made. + +\sa {qtqml-typesystem-topic.html}{The QML Type System} + + +\section1 Available Value Types + +Some value 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 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 \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 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 \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++}. +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 Value Types + +Some value 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 +value types do not provide their own property change signals. It is only possible +to create a property change signal handler for the value 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 value 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. + +*/ + +/*! + \qmlvaluetype int + \ingroup qmlvaluetypes + \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 value type is provided by the QML language. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype bool + \ingroup qmlvaluetypes + \brief a binary true/false value. + + The \c bool type refers to a binary true/false value. + + Properties of type \c bool have \c false as their default value. + + Example: + \qml + Item { + focus: true + clip: false + } + \endqml + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype real + \ingroup qmlvaluetypes + + \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 + + \note In QML all reals are stored in double precision, \l + {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} + format. + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype double + \ingroup qmlvaluetypes + + \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. It's the same as \c real. + + Properties of type \c double have \e {0.0} as their default value. + + Example: + \qml + Item { + property double number: 32155.2355 + } + \endqml + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype string + \ingroup qmlvaluetypes + \brief A free form text string. + + 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 + Text { text: "Hello world!" } + \endqml + + Properties of type \c string are empty by default. + + Strings have a \c length attribute that holds the number of characters in + the string. + + 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: + + \qml + var message = "There are %1 items" + var count = 20 + console.log(message.arg(count)) + \endqml + + The example above prints "There are 20 items". + + 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} +*/ + +/*! + \qmlvaluetype url + \ingroup qmlvaluetypes + \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 + + \note In Qt 5, URLs were automatically resolved based on the current context + when assigning them to any \c url property. This made it impossible to + work with relative URLs and it created inconsistent behavior when reading + back a URL previously written to a property. Therefore, the behavior was + changed in Qt 6: URLs are not automatically resolved on assignment anymore. + The individual elements that use URLs have to resolve them themselves. + + \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 {https://datatracker.ietf.org/doc/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 value type is provided by the QML language. + + \sa {QML Value Types} +*/ + + +/*! + \qmlvaluetype list + \ingroup qmlvaluetypes + \brief a list of QML objects. + + The \c list type refers to a list of QML objects or values. + + Properties of type \c list are empty by default. + + A \c list can store QML objects or \l{QML Value Types}{value type} values. + + 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. + + Similarly any \c{QList<T>} of a registered value type \c{T} 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 + + 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 + + Item { + width: 100; height: 100 + states: State { name: "activated" } + } + \endqml + + You can also declare your own list properties in QML: + + \qml + import QtQml + + QtObject { + property list<int> intList: [1, 2, 3, 4] + property list<QtObject> objectList + } + \endqml + + Lists can be used much like JavaScript arrays. For example: + + \list + \li Values are assigned using the \c[] square bracket syntax with comma-separated values + \li The \c length property provides the number of items in the list + \li Values in the list are accessed using the \c [index] syntax + \li You can use \c{push()} to append entries + \li You can set the \c length property of the list to truncate or extend it. + \endlist + + However, you can \e{not} automatically extend the list by assigning to an + index currently out of range. Furthermore, if you insert \c null values + into a list of objects, those are converted to \c nullptr entries in + the underlying QQmlListProperty. + + A list of value types is different from a JavaScript array in one further + important aspect: Growing it by setting its length does not produce undefined + entries, but rather default-constructed instances of the value type. + + Similarly, growing a list of object types this way produces null entries, + rather than undefined entries. + + This value type is provided by the QML language. + + \sa {QML Value Types} +*/ + + /*! + \qmlvaluetype var + \ingroup qmlvaluetypes + \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. + + Properties of type \c var are \c {undefined} by default. + + 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 Value Types} +*/ + +/*! + \qmlvaluetype variant + \ingroup qmlvaluetypes + \brief a generic property type. + + The \c variant type is the same as the \c var type. Use \c var instead. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype void + \ingroup qmlvaluetypes + \brief The empty value type. + + The \c void type is exclusively used to type-annotate JavaScript functions + returning \c undefined. For example: + + \qml + function doThings() : void { console.log("hello") } + \endqml + + This is to help tooling analyze calls to such functions and compile them and + their callers to C++. + + You cannot declare \c void properties in QML. + + \sa {QML Value Types} +*/ + +/*! + \qmlvaluetype enumeration + \ingroup qmlvaluetypes + \brief a named enumeration value. + + 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 value 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 Value Types} + \sa {qtqml-syntax-objectattributes.html#enumeration-attributes}{Enumeration Attributes} +*/ |