diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc')
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc | 983 |
1 files changed, 983 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc new file mode 100644 index 0000000000..f336d14b14 --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/syntax/objectattributes.qdoc @@ -0,0 +1,983 @@ +/**************************************************************************** +** +** 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. + +*/ |