diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc')
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc | 202 |
1 files changed, 105 insertions, 97 deletions
diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc index 787e7b920b..2b1803042e 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.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) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-syntax-objectattributes.html @@ -56,6 +32,7 @@ The set of QML object-type attribute types is as follows: These attributes are discussed in detail below. \section2 The \e id Attribute +\keyword QML.id Every QML object type has exactly one \e id attribute. This attribute is provided by the language itself, and cannot be redefined or overridden by any @@ -73,7 +50,7 @@ by referring to \c myTextInput.text. Now, both items will display the same text: \qml -import QtQuick 2.0 +import QtQuick Column { width: 200; height: 200 @@ -150,7 +127,7 @@ Rectangle { \section4 Valid Types in Custom Property Definitions -Any of the \l {QML Basic Types} aside from the \l enumeration type can be used +Any of the \l {QML Value Types} aside from the \l enumeration type can be used as custom property types. For example, these are all valid property declarations: \qml @@ -164,11 +141,11 @@ Item { (Enumeration values are simply whole number values and can be referred to with the \l int type instead.) -Some basic types are provided by the \c QtQuick module and thus cannot be used -as property types unless the module is imported. See the \l {QML Basic Types} +Some value types are provided by the \c QtQuick module and thus cannot be used +as property types unless the module is imported. See the \l {QML Value Types} documentation for more details. -Note the \l var basic type is a generic placeholder type that can hold any +Note the \l var value type is a generic placeholder type that can hold any type of value, including lists and objects: \code @@ -223,7 +200,7 @@ definition becomes: An example of property value initialization follows: \qml -import QtQuick 2.0 +import QtQuick Rectangle { color: "red" @@ -245,7 +222,7 @@ assignment operator, as shown below: An example of imperative value assignment follows: \qml -import QtQuick 2.0 +import QtQuick Rectangle { id: rect @@ -285,7 +262,7 @@ also known as \l{Property Binding}{property bindings}. Here is an example that shows both kinds of values being assigned to properties: \qml -import QtQuick 2.0 +import QtQuick Rectangle { // both of these are static value assignments on initialization @@ -329,7 +306,7 @@ even though properties of the \c color type store colors and not strings, you are able to assign the string \c "red" to a color property, without an error being reported. -See \l {QML Basic Types} for a list of the types of properties that are +See \l {QML Value Types} for a list of the types of properties that are supported by default. Additionally, any available \l {QML Object Types} {QML object type} may also be used as a property type. @@ -350,7 +327,7 @@ used to hold a list of \l State type objects. The code below initializes the value of this property to a list of three \l State objects: \qml -import QtQuick 2.0 +import QtQuick Item { states: [ @@ -364,7 +341,7 @@ Item { If the list contains a single item, the square brackets may be omitted: \qml -import QtQuick 2.0 +import QtQuick Item { states: State { name: "running" } @@ -375,20 +352,20 @@ A \l list type property may be specified in an object declaration with the following syntax: \code - [default] property list<<objectType>> propertyName + [default] property list<<ObjectType>> propertyName \endcode and, like other property declarations, a property initialization may be combined with the property declaration with the following syntax: \code - [default] property list<<objectType>> propertyName: <value> + [default] property list<<ObjectType>> propertyName: <value> \endcode An example of list property declaration follows: \qml -import QtQuick 2.0 +import QtQuick Rectangle { // declaration without initialization @@ -430,11 +407,10 @@ Text { } \endcode -Grouped property types are basic types which have subproperties. Some of these -basic types are provided by the QML language, while others may only be used if -the Qt Quick module is imported. See the documentation about -\l{QML Basic Types} for more information. - +Grouped property types are types which have subproperties. If a grouped property +type is an object type (as opposed to a value type), the property that holds it +must be read-only. This is to prevent you from replacing the object the +subproperties belong to. \section3 Property Aliases @@ -494,7 +470,7 @@ which is connected to the \c text object of the \l Text child: \qml // Button.qml -import QtQuick 2.0 +import QtQuick Rectangle { property alias buttonText: textItem.text @@ -522,16 +498,6 @@ the other way around. \section4 Considerations for Property Aliases -Aliases are only activated once a component has been fully initialized. An -error is generated when an uninitialized alias is referenced. Likewise, -aliasing an aliasing property will also result in an error. - -\snippet qml/properties.qml alias complete - -When importing a \l{QML Object Types}{QML object type} with a property alias in -the root object, however, the property appear as a regular Qt property and -consequently can be used in alias references. - It is possible for an aliasing property to have the same name as an existing property, effectively overwriting the existing property. For example, the following QML type has a \c color alias property, named the same as the @@ -609,12 +575,12 @@ property \c someText: \qml // MyLabel.qml -import QtQuick 2.0 +import QtQuick Text { default property var someText - text: "Hello, " + someText.text + text: `Hello, ${someText.text}` } \endqml @@ -645,10 +611,34 @@ This is because the default property of \l Item is its \c data property, and any items added to this list for an \l Item are automatically added to its list of \l {Item::children}{children}. -Default properties can be useful for reassigning the children of an item. See -the \l{TabWidget Example}, which uses a default property to -automatically reassign children of the TabWidget as children of an inner -ListView. See also \l {Extending QML}. +Default properties can be useful for reassigning the children of an item. +For example: + +\qml +Item { + default property alias content: inner.children + + Item { + id: inner + } +} +\endqml + +By setting the default property \e alias to \c {inner.children}, any object +assigned as a child of the outer item is automatically reassigned as a child +of the inner item. + +\warning Setting the values of a an element's default list property can be done implicitly or +explicitly. Within a single element's definition, these two methods must not be mixed as that leads +to undefined ordering of the elements in the list. + +\qml +Item { + // Use either implicit or explicit assignement to the default list property but not both! + Rectangle { width: 40 } // implicit + data: [ Rectangle { width: 100 } ] // explicit +} +\endqml \section3 Required Properties @@ -686,8 +676,8 @@ the role names of the view's model, then those properties will be initialized with the model's corresponding values. For more information, visit the \l{Models and Views in Qt Quick} page. -\sa {QQmlComponent::createWithInitialProperties}, {QQmlApplicationEngine::setInitialProperties} -and {QQuickView::setInitialProperties} for ways to initialize required properties from C++. +See \l{QQmlComponent::createWithInitialProperties}, \l{QQmlApplicationEngine::setInitialProperties} +and \l{QQuickView::setInitialProperties} for ways to initialize required properties from C++. \section3 Read-Only Properties @@ -695,12 +685,12 @@ An object declaration may define a read-only property using the \c readonly keyword, with the following syntax: \code - readonly property <propertyType> <propertyName> : <initialValue> + readonly property <propertyType> <propertyName> : <value> \endcode -Read-only properties must be assigned a value on initialization. After a -read-only property is initialized, it no longer possible to give it a value, -whether from imperative code or otherwise. +Read-only properties must be assigned a static value or a binding expression on +initialization. After a read-only property is initialized, you cannot change +its static value or binding expression anymore. For example, the code in the \c Component.onCompleted block below is invalid: @@ -708,7 +698,7 @@ For example, the code in the \c Component.onCompleted block below is invalid: Item { readonly property int someNumber: 10 - Component.onCompleted: someNumber = 20 // doesn't work, causes an error + Component.onCompleted: someNumber = 20 // TypeError: Cannot assign to read-only property } \endqml @@ -730,6 +720,8 @@ with a particular property is as follows: } \endcode +This is commonly referred to as "on" syntax. + It is important to note that the above syntax is in fact an \l{qtqml-syntax-basics.html#object-declarations}{object declaration} which will instantiate an object which acts on a pre-existing property. @@ -765,7 +757,7 @@ For example, the \e onClicked signal handler below is declared within the clicked, causing a console message to be printed: \qml -import QtQuick 2.0 +import QtQuick Item { width: 100; height: 100 @@ -787,7 +779,7 @@ signal for an object type may be defined in an object declaration in a QML document with the following syntax: \code - signal <signalName>[([<type> <parameter name>[, ...]])] + signal <signalName>[([<parameterName>: <parameterType>[, ...]])] \endcode Attempting to declare two signals or methods with the same name in the same @@ -798,17 +790,26 @@ may be hidden and become inaccessible.) Here are three examples of signal declarations: \qml -import QtQuick 2.0 +import QtQuick Item { signal clicked signal hovered() - signal actionPerformed(string action, var actionResult) + signal actionPerformed(action: string, actionResult: int) } \endqml +You can also specify signal parameters in property style syntax: + +\qml +signal actionCanceled(string action) +\endqml + +In order to be consistent with method declarations, you should prefer the +type declarations using colons. + If the signal has no parameters, the "()" brackets are optional. If parameters -are used, the parameter types must be declared, as for the \c string and \c var +are used, the parameter types must be declared, as for the \c string and \c int arguments for the \c actionPerformed signal above. The allowed parameter types are the same as those listed under \l {Defining Property Attributes} on this page. @@ -844,7 +845,7 @@ the \c SquareButton.qml file as shown below, with signals \c activated and Rectangle { id: root - signal activated(real xPosition, real yPosition) + signal activated(xPosition: real, yPosition: real) signal deactivated property int side: 100 @@ -853,7 +854,7 @@ Rectangle { MouseArea { anchors.fill: parent onReleased: root.deactivated() - onPressed: (mouse)=> root.activated(mouse.x, mouse.y) + onPressed: mouse => root.activated(mouse.x, mouse.y) } } \endqml @@ -866,10 +867,16 @@ provided by the client: // myapplication.qml SquareButton { onDeactivated: console.log("Deactivated!") - onActivated: (xPosition, yPosition)=> console.log("Activated at " + xPosition + "," + yPosition) + onActivated: (xPosition, yPosition) => { + console.log(`Activated at ${xPosition}, ${yPosition}`) + } } \endqml +Signal handlers don't have to declare their parameter types because the signal +already specifies them. The arrow function syntax shown above does not support +type annotations. + See the \l {Signal and Handler Event System} for more details on use of signals. @@ -884,12 +891,12 @@ implicitly available through the fact that \l TextInput has a \c onTextChanged signal handler to be called whenever this property changes: \qml -import QtQuick 2.0 +import QtQuick TextInput { text: "Change this!" - onTextChanged: console.log("Text has changed to:", text) + onTextChanged: console.log(`Text has changed to: ${text}`) } \endqml @@ -909,7 +916,7 @@ registering it as a Q_SLOT of the class. Alternatively, a custom method can be added to an object declaration in a QML document with the following syntax: \code - function <functionName>([<parameterName>[, ...]]) { <body> } + function <functionName>([<parameterName>[: <parameterType>][, ...]]) [: <returnType>] { <body> } \endcode Methods can be added to a QML type in order to define standalone, reusable @@ -917,7 +924,8 @@ blocks of JavaScript code. These methods can be invoked either internally or by external objects. Unlike signals, method parameter types do not have to be declared as they -default to the \c var type. +default to the \c var type. You should, however, declare them in order to +help qmlcachegen generate more performant code, and to improve maintainability. Attempting to declare two methods or signals with the same name in the same type block is an error. However, a new method may reuse the name of an existing @@ -928,11 +936,11 @@ Below is a \l Rectangle with a \c calculateHeight() method that is called when assigning the \c height value: \qml -import QtQuick 2.0 +import QtQuick Rectangle { id: rect - function calculateHeight() { + function calculateHeight(): real { return rect.width / 2; } @@ -947,20 +955,20 @@ can then refer to the received \c newX and \c newY parameters to reposition the text: \qml -import QtQuick 2.0 +import QtQuick Item { width: 200; height: 200 MouseArea { anchors.fill: parent - onClicked: (mouse)=> label.moveTo(mouse.x, mouse.y) + onClicked: mouse => label.moveTo(mouse.x, mouse.y) } Text { id: label - function moveTo(newX, newY) { + function moveTo(newX: real, newY: real) { label.x = newX; label.y = newY; } @@ -999,7 +1007,7 @@ ListView. This can be used by each individual delegate object to determine whether it is the currently selected item in the view: \qml -import QtQuick 2.0 +import QtQuick ListView { width: 240; height: 320 @@ -1023,15 +1031,16 @@ been fully created, its \c Component.onCompleted signal handler will automatically be invoked to populate the model: \qml -import QtQuick 2.0 +import QtQuick ListView { width: 240; height: 320 model: ListModel { id: listModel Component.onCompleted: { - for (var i = 0; i < 10; i++) - listModel.append({"Name": "Item " + i}) + for (let i = 0; i < 10; i++) { + append({ Name: `Item ${i}` }) + } } } delegate: Text { text: index } @@ -1056,7 +1065,7 @@ attached properties. This time, the delegate is an \l Item and the colored \l Rectangle is a child of that item: \qml -import QtQuick 2.0 +import QtQuick ListView { width: 240; height: 320 @@ -1066,7 +1075,7 @@ ListView { Rectangle { width: 100; height: 30 - color: ListView.isCurrentItem ? "red" : "yellow" // WRONG! This won't work. + color: ListView.isCurrentItem ? "red" : "yellow" // WRONG! This won't work. } } } @@ -1081,14 +1090,13 @@ it cannot access the \c isCurrentItem attached property as \qml ListView { - //.... delegate: Item { id: delegateItem width: 100; height: 30 Rectangle { width: 100; height: 30 - color: delegateItem.ListView.isCurrentItem ? "red" : "yellow" // correct + color: delegateItem.ListView.isCurrentItem ? "red" : "yellow" // correct } } } @@ -1125,12 +1133,12 @@ Text { property int textType: MyText.TextType.Normal - font.bold: textType == MyText.TextType.Heading - font.pixelSize: textType == MyText.TextType.Heading ? 24 : 12 + font.bold: textType === MyText.TextType.Heading + font.pixelSize: textType === MyText.TextType.Heading ? 24 : 12 } \endqml -More information on enumeration usage in QML can be found in the \l {QML Basic Types} \l enumeration documentation. +More information on enumeration usage in QML can be found in the \l {QML Value Types} \l enumeration documentation. The ability to declare enumerations in QML was introduced in Qt 5.10. |