diff options
Diffstat (limited to 'src/qml/doc/src/syntax/objectattributes.qdoc')
| -rw-r--r-- | src/qml/doc/src/syntax/objectattributes.qdoc | 983 |
1 files changed, 0 insertions, 983 deletions
diff --git a/src/qml/doc/src/syntax/objectattributes.qdoc b/src/qml/doc/src/syntax/objectattributes.qdoc deleted file mode 100644 index f336d14b14..0000000000 --- a/src/qml/doc/src/syntax/objectattributes.qdoc +++ /dev/null @@ -1,983 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** 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 Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtqml-syntax-objectattributes.html -\title QML Object Attributes -\brief Description of QML object type attributes - -Every QML object type has a defined set of attributes. Each instance of an -object type is created with the set of attributes that have been defined for -that object type. There are several different kinds of attributes which -can be specified, which are described below. - -\section1 Attributes in Object Declarations - -An \l{qtqml-syntax-basics.html#object-declarations}{object declaration} in a -QML document defines a new type. It also declares an object hierarchy that -will be instantiated should an instance of that newly defined type be created. - -The set of QML object-type attribute types is as follows: - -\list -\li the \e id attribute -\li property attributes -\li signal attributes -\li signal handler attributes -\li method attributes -\li attached properties and attached signal handler attributes -\endlist - -These attributes are discussed in detail below. - -\section2 The \e id Attribute - -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 -QML object type. - -A value may be assigned to the \e id attribute of an object instance to allow -that object to be identified and referred to by other objects. This \c id must -begin with a lower-case letter or an underscore, and cannot contain characters -other than letters, numbers and underscores. - -Below is a \l TextInput object and a \l Text object. The \l TextInput object's -\c id value is set to "myTextInput". The \l Text object sets its \c text -property to have the same value as the \c text property of the \l TextInput, -by referring to \c myTextInput.text. Now, both items will display the same -text: - -\qml -import QtQuick 2.0 - -Column { - width: 200; height: 200 - - TextInput { id: myTextInput; text: "Hello World" } - - Text { text: myTextInput.text } -} -\endqml - -An object can be referred to by its \c id from anywhere within the -\e {component scope} in which it is declared. Therefore, an \c id value must -always be unique within its component scope. See -\l{qtqml-documents-scope.html}{Scope and Naming Resolution} for more -information. - -Once an object instance is created, the value of its \e id attribute cannot -be changed. While it may look like an ordinary property, the \c id attribute -is \b{not} an ordinary \c property attribute, and special semantics apply -to it; for example, it is not possible to access \c myTextInput.id in the above -example. - - -\section2 Property Attributes - -A property is an attribute of an object that can be assigned a static value -or bound to a dynamic expression. A property's value can be read by other -objects. Generally it can also be modified by another object, unless a -particular QML type has explicitly disallowed this for a specific property. - -\section3 Defining Property Attributes - -A property may be defined for a type in C++ by registering a -Q_PROPERTY of a class which is then registered with the QML type system. -Alternatively, a custom property of an object type may be defined in -an object declaration in a QML document with the following syntax: - -\code - [default] property <propertyType> <propertyName> -\endcode - -In this way an object declaration may \l {Defining Object Types from QML} -{expose a particular value} to outside objects or maintain some internal -state more easily. - -Property names must begin with a lower case letter and can only contain -letters, numbers and underscores. \l {JavaScript Reserved Words} -{JavaScript reserved words} are not valid property names. The \c default -keyword is optional, and modifies the semantics of the property being declared. -See the upcoming section on \l {Default Properties}{default properties} for -more information about the \c default property modifier. - -Declaring a custom property implicitly creates a value-change -\l{Signal attributes}{signal} for that property, as well as an associated -\l{Signal handler attributes}{signal handler} called -\e on<PropertyName>Changed, where \e <PropertyName> is the name of the -property, with the first letter capitalized. - -For example, the following object declaration defines a new type which -derives from the Rectangle base type. It has two new properties, -with a \l{Signal handler attributes}{signal handler} implemented for one of -those new properties: - -\qml -Rectangle { - property color previousColor - property color nextColor - onNextColorChanged: console.log("The next color will be: " + nextColor.toString()) -} -\endqml - -\section4 Valid Types in Custom Property Definitions - -Any of the \l {QML Basic Types} aside from the \l enumeration type can be used -as custom property types. For example, these are all valid property declarations: - -\qml -Item { - property int someNumber - property string someString - property url someUrl -} -\endqml - -(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} -documentation for more details. - -Note the \l var basic type is a generic placeholder type that can hold any -type of value, including lists and objects: - -\code -property var someNumber: 1.5 -property var someString: "abc" -property var someBool: true -property var someList: [1, 2, "three", "four"] -property var someObject: Rectangle { width: 100; height: 100; color: "red" } -\endcode - -Additionally, any \l{QML Object Types}{QML object type} can be used as a -property type. For example: - -\code -property Item someItem -property Rectangle someRectangle -\endcode - -This applies to \l {Defining Object Types from QML}{custom QML types} as well. -If a QML type was defined in a file named \c ColorfulButton.qml (in a directory -which was then imported by the client), then a property of type -\c ColorfulButton would also be valid. - - -\section3 Values of Property Attributes - -The value of a property of an object instance may specified in an -object declaration in two separate ways: -\list - \li a value assignment on initialization - \li an imperative value assignment -\endlist - -The value in either case may be either a binding expression or a static value. - -\section4 Value Assignment on Initialization - -The syntax for assigning a value to a property on initialization is: - -\code - <propertyName> : <value> -\endcode - -An initialization value assignment may be combined with a property definition -in an object declaration, if desired. In that case, the syntax of the property -definition becomes: - -\code - [default] property <propertyType> <propertyName> : <value> -\endcode - -An example of property value initialization follows: - -\qml -import QtQuick 2.0 - -Rectangle { - color: "red" - property color nextColor: "blue" // combined property declaration and initialization -} -\endqml - -\section4 Imperative Value Assignment - -An imperative value assignment is where a property value (either static value -or binding expression) is assigned to a property from imperative JavaScript -code. The syntax of an imperative value assignment is just the JavaScript -assignment operator, as shown below: - -\code - [<objectId>.]<propertyName> = value -\endcode - -An example of imperative value assignment follows: - -\qml -import QtQuick 2.0 - -Rectangle { - id: rect - Component.onCompleted: { - rect.color = "red" - } -} -\endqml - -\section4 Valid Property Values - -As previously noted, there are two kinds of values which may be assigned to a -property: static values, and binding expression values. - -\table - \header - \li Kind - \li Semantics - - \row - \li Static Value - \li A value whose type matches (or can be converted to) that of - the property may be assigned to the property. - - \row - \li Binding Expression - \li A JavaScript expression which may be evaluated, whose result is a - value whose type matches (or can be converted to) that of the - property may be assigned to the property. The expression will be - automatically re-evaluated (and the new result assigned to the - property) by the QML engine should the value of any properties accessed - during evaluation change. -\endtable - -An example of these two types of values being assigned to properties follows: - -\qml -import QtQuick 2.0 - -Rectangle { - // both of these are static value assignments on initialization - width: 400 - height: 200 - - Rectangle { - // both of these are binding expression value assignments on initialization - width: parent.width / 2 - height: parent.height - } -} -\endqml - -In many cases, a string value may be converted automatically to a -different type of value, as QML provides string converters for many property -types (thus you can assign the string \c "red" to a color property). - -It is important to note that in order to assign a binding expression to a -property in an imperative value assignment, the right-hand-side of -the assignment (the binding expression) must be a function returned by the -\l{Qt::binding()}{Qt.binding()} function, which returns a value of the -appropriate type. A binding expression value may be assigned to a property -via an initialization value assignment without using that function (and, in -fact, attempting to do so will result in an error). See the documentation -about \l{qtqml-syntax-propertybinding.html}{property binding} for more -information on the topic. - - -\section3 Type Safety - -Properties are type safe. A property can only be assigned a value that matches -the property type. - -For example, if a property is a real, and if you try to assign a string to it, -you will get an error: - -\code -property int volume: "four" // generates an error; the property's object will not be loaded -\endcode - -Likewise if a property is assigned a value of the wrong type during run time, -the new value will not be assigned, and an error will be generated. - -As noted in a previous section, some property types do not have a natural -value representation, and for those property types the QML engine -automatically performs string-to-typed-value conversion. So, for example, -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 -supported by default. Additionally, any available \l {QML Object Types} -{QML object type} may also be used as a property type. - -\section3 Special Property Types - -\section4 Object List Property Attributes - -A \l list type property can be assigned a list of QML object-type values. -The syntax for defining an object list value is a comma-separated list -surrounded by square brackets: - -\code - [ <item 1>, <item 2>, ... ] -\endcode - -For example, the \l Item type has a \l {Item::states}{states} property that is -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 - -Item { - states: [ - State { name: "loading" }, - State { name: "running" }, - State { name: "stopped" } - ] -} -\endqml - -If the list contains a single item, the square brackets may be omitted: - -\qml -import QtQuick 2.0 - -Item { - states: State { name: "running" } -} -\endqml - -A \l list type property may be specified in an object declaration with the -following syntax: - -\code - [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> -\endcode - -An example of list property declaration follows: - -\qml -import QtQuick 2.0 - -Rectangle { - // declaration without initialization - property list<Rectangle> siblingRects - - // declaration with initialization - property list<Rectangle> childRects: [ - Rectangle { color: "red" }, - Rectangle { color: "blue"} - ] -} -\endqml - -If you wish to declare a property to store a list of values which are not -necessarily QML object-type values, you should declare a \l var property -instead. - - -\section4 Grouped Properties - -In some cases properties contain a logical group of sub-property attributes. -These sub-property attributes can be assigned to using either the dot notation -or group notation. - -For example, the \l Text type has a \l{Text::font.family}{font} group property. Below, -the first \l Text object initializes its \c font values using dot notation, -while the second uses group notation: - -\code -Text { - //dot notation - font.pixelSize: 12 - font.b: true -} - -Text { - //group notation - font { pixelSize: 12; b: true } -} -\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. - - -\section3 Property Aliases - -Property aliases are properties which hold a reference to another property. -Unlike an ordinary property definition, which allocates a new, unique storage -space for the property, a property alias connects the newly declared property -(called the aliasing property) as a direct reference to an existing property -(the aliased property). - -A property alias declaration looks like an ordinary property definition, except -that it requires the \c alias keyword instead of a property type, and the -right-hand-side of the property declaration must be a valid alias reference: - -\code -[default] property alias <name>: <alias reference> -\endcode - -Unlike an ordinary property, an alias can only refer to a object, or the -property of a object, that is within the scope of the \l{QML Object Types} -{type} within which the alias is declared. It cannot contain arbitrary -JavaScript expressions and it cannot refer to objects declared outside of -the scope of its type. Also note the \e {alias reference} is not optional, -unlike the optional default value for an ordinary property; the alias reference -must be provided when the alias is first declared. - -For example, below is a \c Button type with a \c buttonText aliased property -which is connected to the \c text object of the \l Text child: - -\qml -// Button.qml -import QtQuick 2.0 - -Rectangle { - property alias buttonText: textItem.text - - width: 100; height: 30; color: "yellow" - - Text { id: textItem } -} -\endqml - -The following code would create a \c Button with a defined text string for the -child \l Text object: - -\qml -Button { buttonText: "Click Me" } -\endqml - -Here, modifying \c buttonText directly modifies the textItem.text value; it -does not change some other value that then updates textItem.text. If -\c buttonText was not an alias, changing its value would not actually change -the displayed text at all, as property bindings are not bi-directional: the -\c buttonText value would have changed if textItem.text was changed, but not -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 -built-in \l {Rectangle::color} property: - -\snippet qml/properties.qml alias overwrite - -Any object that use this type and refer to its \c color property will be -referring to the alias rather than the ordinary \l {Rectangle::color} property. -Internally, however, the red can correctly set its \c color -property and refer to the actual defined property rather than the alias. - - -\section3 Default Properties - -An object definition can have a single \e default property. A default property -is the property to which a value is assigned if an object is declared within -another object's definition without declaring it as a value for a particular -property. - -Declaring a property with the optional \c default keyword marks it as the -default property. For example, say there is a file MyLabel.qml with a default -property \c someText: - -\qml -// MyLabel.qml -import QtQuick 2.0 - -Text { - default property var someText - - text: "Hello, " + someText.text -} -\endqml - -The \c someText value could be assigned to in a \c MyLabel object definition, -like this: - -\qml -MyLabel { - Text { text: "world!" } -} -\endqml - -This has exactly the same effect as the following: - -\qml -MyLabel { - someText: Text { text: "world!" } -} -\endqml - -However, since the \c someText property has been marked as the default -property, it is not necessary to explicitly assign the \l Text object -to this property. - -You will notice that child objects can be added to any \l {Item}-based type -without explicitly adding them to the \l {Item::children}{children} property. -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{declarative/ui-components/tabwidget}{TabWidget example}, which uses a -default property to automatically reassign children of the TabWidget as -children of an inner ListView. - - -\section3 Read-Only Properties - -An object declaration may define a read-only property using the \c readonly -keyword, with the following syntax: - -\code - readonly property <propertyType> <propertyName> : <initialValue> -\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. - -For example, the code in the \c Component.onCompleted block below is invalid: - -\qml -Item { - readonly property int someNumber: 10 - - Component.onCompleted: someNumber = 20 // doesn't work, causes an error -} -\endqml - -\note A read-only property cannot also be a \l{Default Properties}{default} or -\l {Property Aliases}{alias} property. - - -\section3 Property Modifier Objects - -Properties can have -\l{qtqml-cppintegration-definetypes.html#property-modifier-types} -{property value modifier objects} associated with them. -The syntax for declaring an instance of a property modifier type associated -with a particular property is as follows: - -\code -<PropertyModifierTypeName> on <propertyName> { - // attributes of the object instance -} -\endcode - -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. - -Certain property modifier types may only be applicable to specific property -types, however this is not enforced by the language. For example, the -\c NumberAnimation type provided by \c QtQuick will only animate -numeric-type (such as \c int or \c real) properties. Attempting to use a -\c NumberAnimation with non-numeric property will not result in an error, -however the non-numeric property will not be animated. The behavior of a -property modifier type when associated with a particular property type is -defined by its implementation. - - -\section2 Signal Attributes - -A signal is a notification from an object that some event has occurred: for -example, a property has changed, an animation has started or stopped, or -when an image has been downloaded. The \l MouseArea type, for example, has -a \l {MouseArea::onClicked}{clicked} signal that is emitted when the user clicks -within the mouse area. - -An object can be notified through a \l{Signal handler attributes} -{signal handler} whenever it a particular signal is emitted. A signal handler -is declared with the syntax \e on<Signal> where \e <Signal> is the name of the -signal, with the first letter capitalized. The signal handler must be declared -within the definition of the object that emits the signal, and the handler -should contain the block of JavaScript code to be executed when the signal -handler is invoked. - -For example, the \e onClicked signal handler below is declared within the -\l MouseArea object definition, and is invoked when the \l MouseArea is -clicked, causing a console message to be printed: - -\qml -import QtQuick 2.0 - -Item { - width: 100; height: 100 - - MouseArea { - anchors.fill: parent - onClicked: { - console.log("Click!") - } - } -} -\endqml - -\section3 Defining Signal Attributes - -A signal may be defined for a type in C++ by registering a Q_SIGNAL of a class -which is then registered with the QML type system. Alternatively, a custom -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>[, ...]])] -\endcode - -Attempting to declare two signals or methods with the same name in the same -type block is an error. However, a new signal may reuse the name of an existing -signal on the type. (This should be done with caution, as the existing signal -may be hidden and become inaccessible.) - -Here are three examples of signal declarations: - -\qml -import QtQuick 2.0 - -Item { - signal clicked - signal hovered() - signal actionPerformed(string action, var actionResult) -} -\endqml - -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 -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. - -To emit a signal, invoke it as a method. Any relevant -\l{Signal handler attributes}{signal handlers} will be invoked when the signal -is emitted, and handlers can use the defined signal argument names to access -the respective arguments. - -\section3 Property Change Signals - -QML types also provide built-in \e {property change signals} that are emitted -whenever a property value changes, as previously described in the section on -\l{Property attributes}{property attributes}. See the upcoming section on -\l{Property change signal handlers}{property change signal handlers} for more -information about why these signals are useful, and how to use them. - - -\section2 Signal Handler Attributes - -Signal handlers are a special sort of \l{Method attributes}{method attribute}, -where the method implementation is invoked by the QML engine whenever the -associated signal is emitted. Adding a signal to an object definition in QML -will automatically add an associated signal handler to the object definition, -which has, by default, an empty implementation. Clients can provide an -implementation, to implement program logic. - -Consider the following \c SquareButton type, whose definition is provided in -the \c SquareButton.qml file as shown below, with signals \c activated and -\c deactivated: - -\qml -// SquareButton.qml -Rectangle { - id: root - - signal activated(real xPosition, real yPosition) - signal deactivated - - width: 100; height: 100 - - MouseArea { - anchors.fill: parent - onPressed: root.activated(mouse.x, mouse.y) - onRelased: root.deactivated() - } -} -\endqml - -These signals could be received by any \c SquareButton objects in another QML -file in the same directory, where implementations for the signal handlers are -provided by the client: - -\qml -// myapplication.qml -SquareButton { - onActivated: console.log("Activated at " + xPosition + "," + yPosition) - onDeactivated: console.log("Deactivated!") -} -\endqml - -See the \l {Signal and Handler Event System} for more details on use of -signals. - -\section3 Property Change Signal Handlers - -Signal handlers for property change signal take the syntax form -\e on<Property>Changed where \e <Property> is the name of the property, -with the first letter capitalized. For example, although the \l TextInput type -documentation does not document a \c textChanged signal, this signal is -implicitly available through the fact that \l TextInput has a -\l {TextInput::text}{text} property and so it is possible to write an -\c onTextChanged signal handler to be called whenever this property changes: - -\qml -import QtQuick 2.0 - -TextInput { - text: "Change this!" - - onTextChanged: console.log("Text has changed to:", text) -} -\endqml - - -\section2 Method Attributes - -A method of an object type is a function which may be called to perform some -processing or trigger further events. A method can be connected to a signal so -that it is automatically invoked whenever the signal is emitted. See -\l {Signal and Handler Event System} for more details. - -\section3 Defining Method Attributes - -A method may be defined for a type in C++ by tagging a function of a class -which is then registered with the QML type system with Q_INVOKABLE or by -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> } -\endcode - -Methods can be added to a QML type in order to define standalone, reusable -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. - -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 -method on the type. (This should be done with caution, as the existing method -may be hidden and become inaccessible.) - -Below is a \l Rectangle with a \c calculateHeight() method that is called when -assigning the \c height value: - -\qml -import QtQuick 2.0 -Rectangle { - id: rect - - function calculateHeight() { - return rect.width / 2; - } - - width: 100 - height: calculateHeight() -} -\endqml - -If the method has parameters, they are accessible by name within the method. -Below, when the \l MouseArea is clicked it invokes the \c moveTo() method which -can then refer to the received \c newX and \c newY parameters to reposition the -text: - -\qml -import QtQuick 2.0 - -Item { - width: 200; height: 200 - - MouseArea { - anchors.fill: parent - onClicked: label.moveTo(mouse.x, mouse.y) - } - - Text { - id: label - - function moveTo(newX, newY) { - label.x = newX; - label.y = newY; - } - - text: "Move me!" - } -} -\endqml - - -\section2 Attached Properties and Attached Signal Handlers - -\e {Attached properties} and \e {attached signal handlers} are mechanisms that -enable objects to be annotated with extra properties or signal handlers that -are otherwise unavailable to the object. In particular, they allow objects to -access properties or signals that are specifically relevant to the individual -object. - -A QML type implementation may choose to create an \e {attaching type} with -particular properties and signals. Instances of this type can then be created -and \e attached to specific objects at run time, allowing those objects to -access the properties and signals of the attaching type. These are accessed by -prefixing the properties and respective signal handlers with the name of the -attaching type. - -References to attached properties and handlers take the following syntax form: - -\code -<AttachingType>.<propertyName> -<AttachingType>.on<SignalName> -\endcode - -For example, the \l ListView type has an attached property -\l {ListView::isCurrentItem}{ListView.isCurrentItem} that is available to each delegate object in a -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 - -ListView { - width: 240; height: 320 - model: 3 - delegate: Rectangle { - width: 100; height: 30 - color: ListView.isCurrentItem ? "red" : "yellow" - } -} -\endqml - -In this case, the name of the \e {attaching type} is \c ListView and the -property in question is \c isCurrentItem, hence the attached property is -referred to as \c ListView.isCurrentItem. - -An attached signal handler is referred to in the same way. For example, the -\c Component.isCompleted attached signal handler is commonly used to execute -some JavaScript code when a component's creation process has been completed. -In the example below, once the \l ListModel has been fully created, its -\c Component.onCompleted signal handler will automatically be invoked to -populate the model: - -\qml -import QtQuick 2.0 - -ListView { - width: 240; height: 320 - model: ListModel { - id: listModel - Component.onCompleted: { - for (var i = 0; i < 10; i++) - listModel.append({"Name": "Item " + i}) - } - } - delegate: Text { text: index } -} -\endqml - -Since the name of the \e {attaching type} is \c Component and that type has a -\c completed signal, the attached signal handler is referred to as -\c Component.isCompleted. - - -\section3 A Note About Accessing Attached Properties and Signal Handlers - -A common error is to assume that attached properties and signal handlers are -directly accessible from the children of the object to which these attributes -have been attached. This is not the case. The instance of the -\e {attaching type} is only attached to specific objects, not to the object -and all of its children. - -For example, below is a modified version of the earlier example involving -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 - -ListView { - width: 240; height: 320 - model: 3 - delegate: Item { - width: 100; height: 30 - - Rectangle { - width: 100; height: 30 - color: ListView.isCurrentItem ? "red" : "yellow" // WRONG! This won't work. - } - } -} -\endqml - -This does not work as expected because \c ListView.isCurrentItem is attached -\e only to the root delegate object, and not its children. Since the -\l Rectangle is a child of the delegate, rather than being the delegate itself, -it cannot access the \c isCurrentItem attached property as -\c ListView.isCurrentItem. So instead, the rectangle should access -\c isCurrentItem through the root delegate: - -\qml -ListView { - //.... - delegate: Item { - id: delegateItem - width: 100; height: 30 - - Rectangle { - width: 100; height: 30 - color: delegateItem.ListView.isCurrentItem ? "red" : "yellow" // correct - } - } -} -\endqml - -Now \c delegateItem.ListView.isCurrentItem correctly refers to the -\c isCurrentItem attached property of the delegate. - -*/ |