diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc')
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc | 122 |
1 files changed, 69 insertions, 53 deletions
diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc index 60e90217f4..2b1803042e 100644 --- a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2017 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -50,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 @@ -200,7 +200,7 @@ definition becomes: An example of property value initialization follows: \qml -import QtQuick 2.0 +import QtQuick Rectangle { color: "red" @@ -222,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 @@ -262,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 @@ -327,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: [ @@ -341,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" } @@ -352,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 @@ -470,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 @@ -498,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 @@ -585,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 @@ -621,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 @@ -671,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: @@ -684,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 @@ -743,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 @@ -776,7 +790,7 @@ may be hidden and become inaccessible.) Here are three examples of signal declarations: \qml -import QtQuick 2.0 +import QtQuick Item { signal clicked @@ -795,7 +809,7 @@ 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. @@ -840,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 @@ -853,7 +867,9 @@ 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 @@ -875,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 @@ -920,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() : real { + function calculateHeight(): real { return rect.width / 2; } @@ -939,14 +955,14 @@ 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 { @@ -991,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 @@ -1015,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 } @@ -1048,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 @@ -1058,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. } } } @@ -1073,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 } } } @@ -1117,8 +1133,8 @@ 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 |