src/qml/doc/src/cppintegration/data.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qtqml-cppintegration-data.html
  29 \title Exposing Data from C++ to QML
  30 \brief Description of how to expose data from C++ to QML
  31
  32
  33 // XXX TODO The content of "Exposing C++ Functionality To QML" and
  34 // "Exposing Data From C++ To QML" should probably be grouped together
  35 // on the same page, or separated in a more distinct way.
  36 // [CA]: I'm not so sure.  Functions vs Data is separate and distinct.
  37 // I like the separation of pages, to be honest.
  38
  39
  40 \section1 Ownership Semantics
  41
  42 The ownership of data transferred from C++ to QML always remains with C++ in all
  43 cases, except for one (where a QObject is returned from a method invocation).
  44 More information about that possible ownership change is included
  45 below.  Furthermore, QML respects the normal QObject parent ownership
  46 semantics of Qt C++, and won't ever take ownership of a QObject which
  47 already has a parent.
  48
  49 \section1 Context Properties
  50
  51 Data from C++ may be exposed to QML via context properties.
  52 Since all expressions evaluated in QML are evaluated in a
  53 particular context, if the context is modified, all bindings
  54 in that context will be re-evaluated, and thus this method
  55 should be used with care (or only during initialization).
  56
  57 \section1 Instance Property Access
  58
  59 Data from a registered C++ type may be exposed as a property
  60 which has been declared using the Q_PROPERTY macro.  Such a
  61 property will be accessible from QML code.
  62
  63
  64
  65 \target properties-cpp
  66
  67 Any \l {The Property System}{Qt properties} - that is, those declared with the Q_PROPERTY()
  68 macro - are accessible from QML. Here is a modified version of the \l {Embedding C++ objects into
  69 QML components}{earlier example} on this page; here, the \c ApplicationData class has a \c backgroundColor
  70 property. This property can be written to and read from QML:
  71
  72 \table
  73 \row
  74 \li \snippet qml/qtbinding/properties-cpp/applicationdata.h 0
  75 \li \snippet qml/qtbinding/properties-cpp/MyItem.qml 0
  76 \endtable
  77
  78 Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal for the
  79 \c backgroundColor property. If a Qt property does not have an associated NOTIFY signal,
  80 the property cannot be used for \l{Property Binding}, as the QML engine would not be
  81 notified when the value changes. If you are using custom types in QML, make sure their
  82 properties have NOTIFY signals so that they can be used in property bindings.
  83
  84 See \l {Tutorial: Extending QML with C++} for further details and examples
  85 on using Qt properties with QML.
  86
  87
  88
  89
  90 \section1 Supported Data Types
  91
  92 Any C++ data that is used from QML - whether as custom properties, or parameters for signals or
  93 functions - must be of a type that is recognizable by QML.
  94
  95 By default, QML recognizes the following data types:
  96
  97 // XXX TODO This list should refer to "QML Basic Types" list to refer to the type conversions
  98
  99 \list
 100 \li bool
 101 \li unsigned int, int
 102 \li float, double, qreal
 103 \li QString
 104 \li QUrl
 105 \li QColor
 106 \li QDate, QTime, QDateTime
 107 \li QPoint, QPointF
 108 \li QSize, QSizeF
 109 \li QRect, QRectF
 110 \li QVariant
 111 \li QVariantList, QVariantMap
 112 \li QObject*
 113 \li Enumerations declared with Q_ENUMS()
 114 \endlist
 115
 116 To allow a custom C++ type to be created or used in QML, the C++ class must be registered as a QML
 117 type using qmlRegisterType(), as shown in the \l {Defining new QML elements} section above.
 118
 119
 120
 121
 122 \section2 JavaScript Arrays and Objects
 123
 124 There is built-in support for automatic type conversion between QVariantList and JavaScript
 125 arrays, and QVariantMap and JavaScript objects.
 126
 127 For example, the function defined in QML below left expects two arguments, an array and an object, and prints
 128 their contents using the standard JavaScript syntax for array and object item access. The C++ code
 129 below right calls this function, passing a QVariantList and a QVariantMap, which are automatically
 130 converted to JavaScript array and object values, repectively:
 131
 132 \table
 133 \header
 134 \li Type
 135 \li String format
 136 \li Example
 137 \row
 138 \li \snippet qml/qtbinding/variantlistmap/MyItem.qml 0
 139 \li \snippet qml/qtbinding/variantlistmap/main.cpp 0
 140 \endtable
 141
 142 This produces output like:
 143
 144 \code
 145 Array item: 10
 146 Array item: #00ff00
 147 Array item: bottles
 148 Object item: language = QML
 149 Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST)
 150 \endcode
 151
 152 Similarly, if a C++ type uses a QVariantList or QVariantMap type for a property or method
 153 parameter, the value can be created as a JavaScript array or object in the QML
 154 side, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++.
 155
 156
 157 \section2 Using Enumerations of a Custom Type
 158
 159 To use an enumeration from a custom C++ component, the enumeration must be declared with Q_ENUMS() to
 160 register it with Qt's meta object system. For example, the following C++ type has a \c Status enum:
 161
 162 \snippet qml/qtbinding/enums/imageviewer.h start
 163 \snippet qml/qtbinding/enums/imageviewer.h end
 164
 165 Providing the \c ImageViewer class has been registered using qmlRegisterType(), its \c Status enum can
 166 now be used from QML:
 167
 168 \snippet qml/qtbinding/enums/standalone.qml 0
 169
 170 The C++ type must be registered with QML to use its enums. If your C++ type is not instantiable, it
 171 can be registered using qmlRegisterUncreatableType().  To be accessible from QML, the names of enum values
 172 must begin with a capital letter.
 173
 174 See the \l {Tutorial: Extending QML with C++}{Writing QML extensions with C++} tutorial and
 175 the \l{Extending QML with C++} reference documentation for
 176 more information.
 177
 178
 179 \section2 Using Enumeration Values as Signal and Method Parameters
 180
 181 C++ signals may pass enumeration values as signal parameters to QML, providing that the enumeration
 182 and the signal are declared within the same class, or that the enumeration value is one of those declared
 183 in the \l {Qt}{Qt Namespace}.
 184
 185 Likewise, invokable C++ method parameters may be enumeration values providing
 186 that the enumeration and the method are declared within the same class, or that
 187 the enumeration value is one of those declared in the \l {Qt}{Qt Namespace}.
 188
 189 Additionally, if a C++ signal with an enum parameter should be connectable to a QML function using the
 190 \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals}{connect()}
 191 function, the enum type must be registered using qRegisterMetaType().
 192
 193 For QML signals, enum values may be used as signal parameters using the \c int type:
 194
 195 \snippet qml/qtbinding/enums/standalone.qml 1
 196
 197
 198
 199
 200 \section2 Automatic Type Conversion from Strings
 201
 202 As a convenience, some basic types can be specified in QML using format strings to make it easier to
 203 pass simple values from QML to C++.
 204
 205 \table
 206 \header
 207 \li Type
 208 \li String format
 209 \li Example
 210 \row
 211 \li QColor
 212 \li Color name, "#RRGGBB", "#RRGGBBAA"
 213 \li "red", "#ff0000", "#ff000000"
 214 \row
 215 \li QDate
 216 \li "YYYY-MM-DD"
 217 \li "2010-05-31"
 218 \row
 219 \li QPoint
 220 \li "x,y"
 221 \li "10,20"
 222 \row
 223 \li QRect
 224 \li "x,y,WidthxHeight"
 225 \li "50,50,100x100"
 226 \row
 227 \li QSize
 228 \li "WidthxHeight"
 229 \li "100x200"
 230 \row
 231 \li QTime
 232 \li "hh:mm:ss"
 233 \li "14:22:55"
 234 \row
 235 \li QUrl
 236 \li URL string
 237 \li "http://www.example.com"
 238 \row
 239 \li QVector3D
 240 \li "x,y,z"
 241 \li "0,1,0"
 242 \row
 243 \li Enumeration value
 244 \li Enum value name
 245 \li "AlignRight"
 246 \endtable
 247
 248 (More details on these string formats and types can be found in the
 249 \l {QML Basic Types}{basic type documentation}.)
 250
 251 These string formats can be used to set QML \c property values and pass arguments to C++
 252 functions. This is demonstrated by various examples on this page; in the above
 253 \l{#properties-cpp}{Qt properties example}, the \c ApplicationData class has a \c backgroundColor
 254 property of a QColor type, which is set from the QML code with the string "red" rather rather
 255 than an actual QColor object.
 256
 257 If it is preferred to pass an explicitly-typed value rather than a string, the global
 258 \l{QmlGlobalQtObject}{Qt object} provides convenience functions for creating some of the object
 259 types listed above. For example, \l{QML:Qt::rgba()}{Qt.rgba()} creates a QColor value from four
 260 RGBA values. The QColor returned from this function could be used instead of a string to set
 261 a QColor-type property or to call a C++ function that requires a QColor parameter.
 262
 263
 264
 265
 266 \section1 Data Returned from Instance Method Invocation
 267
 268 A registered C++ type may have functions flagged with the
 269 Q_INVOKABLE flag defined.  Those functions of an instance of
 270 such a type will be accessible from QML.  The function may
 271 have a return value, which will be converted to a JavaScript
 272 value when accessed from a JavaScript expression in QML.
 273
 274 Note that if the return value is a QObject pointer (or a
 275 pointer to a QObject-derived type), the QML engine will assume
 276 ownership of it unless the object has had its ownership previously
 277 explicitly set (to QQmlEngine::CppOwnership).
 278
 279
 280
 281
 282
 283 \section2 Embedding C++ Objects into QML Components
 284
 285 When loading a QML scene into a C++ application, it can be useful to directly embed C++ data into
 286 the QML object. QQmlContext enables this by exposing data to the context of a QML
 287 component, allowing data to be injected from C++ into QML.
 288
 289 For example, here is a QML item that refers to a \c currentDateTime value that does not exist in
 290 the current scope:
 291
 292 \snippet qml/qtbinding/context/MyItem.qml 0
 293
 294 This \c currentDateTime value can be set directly by the C++ application that loads the QML
 295 component, using QQmlContext::setContextProperty():
 296
 297 \snippet qml/qtbinding/context/main.cpp 0
 298
 299 Context properties can hold either QVariant or QObject* values. This means custom C++ objects can
 300 also be injected using this approach, and these objects can be modified and read directly in QML.
 301 Here, we modify the above example to embed a QObject instance instead of a QDateTime value, and the QML code
 302 invokes a method on the object instance:
 303
 304 \table
 305 \row
 306 \li
 307 \snippet qml/qtbinding/context-advanced/applicationdata.h 0
 308 \codeline
 309 \snippet qml/qtbinding/context-advanced/main.cpp 0
 310 \li
 311 \snippet qml/qtbinding/context-advanced/MyItem.qml 0
 312 \endtable
 313
 314 (Note that date/time values returned from C++ to QML can be formatted through
 315 \l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.)
 316
 317 If the QML item needs to receive signals from the context property, it can connect to them using the
 318 \l Connections element. For example, if \c ApplicationData has a signal named \c
 319 dataChanged(), this signal can be connected to using an \c onDataChanged handler within
 320 a \l Connections object:
 321
 322 \snippet qml/qtbinding/context-advanced/connections.qml 0
 323
 324 Context properties can be useful for using C++ based data models in a QML view. See the
 325 \l {quick/modelviews/stringlistmodel}{String ListModel},
 326 \l {quick/modelviews/objectlistmodel}{Object ListModel} and
 327 \l {quick/modelviews/abstractitemmodel}{AbstractItemModel} models for
 328 respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel
 329 in QML views.
 330
 331 Also see the QQmlContext documentation for more information.
 332
 333
 334
 335
 336
 337
 338 \section1 Exposing Qt C++ Properties
 339
 340     The \l{QQmlEngine}{QML engine} utilizes Qt's
 341     \l{The Property System}{Property System} and in effect, QML
 342     \l{Property Binding}{property bindings} also use Qt properties.
 343
 344     Essentially, a Qt C++ property has a \e write function, \e read function,
 345     and has a signal function. QML properties are inheritely public, both
 346     readable and writable, albeit type-safe. QML properties may also have
 347     signals which are emitted when the property value or binding changes.
 348
 349     The QML property equivalent of a Qt C++ property is created as a property
 350     with the \l Q_PROPERTY() macro. There needs to be C++ functions assigned as
 351     the property's read, write, and signal handler function.
 352
 353     The \l {Creating QML Object Types from C++}{Register a Type} section mentions that the
 354     \c Person class has properties that are exposed to the QML context. The QML
 355     properties are created with the \c Q_PROPERTY macro. The macro associates
 356     the properties to the read, write, and singal functions in its argument.
 357
 358 \code
 359 Q_PROPERTY(int size READ size WRITE setSize NOTIFY shoeChanged)
 360 \endcode
 361
 362     A \c Shoe class might have an integer property called \c size. We set the \c
 363     size() function as the \c READ function and the \c setSize() function to be
 364     the \c WRITE function. In a QML application, when a property is read, the \c
 365     size() is called and when the property's binding changes, the \c setSize()
 366     is called. The READ function, by definition, must return the same type as
 367     the property.
 368
 369     We may also connect a \l{signals and slots}{signal} to a property. The \c
 370     size property may have a \c shoeChanged signal indicated after the \c NOTIFY
 371     parameter of the macro. The \c shoeChanged becomes a \l{QML Signal and
 372     Handler Event System}{QML signal} and the runtime will create QML handler
 373     called \c onShoeChanged. Whenever the size property's binding changes, the
 374     \c shoeChanged signal is emitted and the \c onShoeChanged handler is
 375     invoked. In the handler, commands such as \l{JavaScript Expressions in
 376     QML}{JavaScript expressions} can perform clean-up operations or call other
 377     functions.
 378
 379     \b{Note:} The QML signal handler will always be named
 380     on<Property-name>Changed, regardless of the name used for the NOTIFY
 381     signal in C++. We recommend using <property-name>Changed() for the
 382     NOTIFY signal in C++.
 383
 384     We may also make the property a \c read-only property by placing
 385     \c CONSTANT in the parameter. Changing the binding will generate an error.
 386 \code
 387 //A read-only property
 388 Q_PROPERTY(int size READ size CONSTANT)
 389 \endcode
 390
 391 \section2 Default Property
 392
 393     When imported, QML components will bind their children to their designated
 394     \l{default-property}{default property}. This is helpful, for example,
 395     to redirect any declared child components to a property of another
 396     component.
 397
 398     The runtime can set a property to be the default property by tagging the
 399     property with \c DefaultProperty in The Q_CLASSINFO() macro.
 400
 401     \code
 402     Q_CLASSINFO("DefaultProperty", "pipe")
 403     \endcode
 404
 405     The property tagged as default property, \c pipe, can only be an object
 406     property, or a list property.
 407
 408     A default property is optional. A derived class inherits its base class's
 409     default property, but may override it in its own declaration. The \c pipe
 410     property can refer to a property declared in the class itself, or a property
 411     inherited from a base class.
 412
 413     The \l{Extending QML - Default Property Example}{Default Properties} example
 414     uses \l{default-property}{default properties} to assign the children of
 415     a component to a specific property.
 416
 417     \section2 Grouped Properties
 418
 419     A property group may be functionally defined as a set of related properties.
 420     For example, the \l{Layouts with Anchors}{anchors} are a group of
 421     related properties. In practice, property groups resemble a parent object
 422     where the individual properties are accessed as children.
 423
 424     A grouped property's member properties are accessed using the
 425     <group>.<property> notation. For example, shoe.color is the way to access
 426     the \c color property in the \c shoe property group .
 427
 428     \snippet examples/qml/cppextensions/referenceexamples/grouped/example.qml ungrouped
 429
 430     Alternatively, the group can be accessed as a set.
 431     \snippet examples/qml/cppextensions/referenceexamples/grouped/example.qml grouped
 432
 433     A grouped property block is implemented as a read-only object property. The
 434     \c shoe property shown is declared like this:
 435
 436     \snippet examples/qml/cppextensions/referenceexamples/grouped/person.h 1
 437
 438     The \c ShoeDescription type declares the properties available to the grouped
 439     property block - in this case the \c size, \c color, \c brand and \c price properties.
 440
 441     Grouped property blocks may declared and accessed be recusively.
 442
 443     \l {Extending QML - Grouped Properties Example} shows the complete code used to
 444     implement the \c shoe property grouping.
 445
 446     \section2 Attached Properties
 447
 448     Attached properties annotate or add properties to another type or component.
 449     For example, the \l Keys \e{attaching type} contains \e{attached properties}
 450     that other elements may use to respond to key input. Conceptually, attached
 451     properties are a \e type exporting a set of additional properties that can
 452     be set on any other object instance.
 453
 454     The attaching type is a QObject derived type. The properties on the
 455     attaching type are those that become available for use as attached
 456     properties.
 457
 458     \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml 1
 459
 460     The \c BirthdayParty is called the attaching type and the
 461     \c Boy instance the attachee object instance. The property \c rsvp is the
 462     attached property.
 463
 464     Any Qt C++ type can become an attaching type by declaring the \c
 465     qmlAttachedProperties() a public member function and declaring that the
 466     class has QML_HAS_ATTACHED_PROPERTIES.
 467
 468     \code
 469     static AttachedPropertiesType *qmlAttachedProperties(QObject *object);
 470     \endcode
 471
 472     This static pointer returns an attachment object, of type \a
 473     AttachedPropertiesType, for the attachee \a object instance. It is
 474     customary, though not strictly required, for the attachment object to be
 475     parented to \a object to prevent memory leaks.
 476     The \l {Extending QML - Attached Properties Example}{Birthday}
 477     class has \c BirthdayPartyAttached attached properties.
 478
 479     \snippet examples/qml/cppextensions/referenceexamples/attached/birthdayparty.h static attached
 480
 481     The QML_DECLARE_TYPEINFO() macro can notify the runtime that the type has
 482     attached properties with the QML_HAS_ATTACHED_PROPERTIES argument.
 483
 484     \snippet examples/qml/cppextensions/referenceexamples/attached/birthdayparty.h declare attached
 485
 486     The qmlAttachedProperties method will be called at most once for each
 487     attachee object instance. The QML engine will cache the returned instance
 488     pointer for subsequent attached property accesses. Consequently the
 489     attachment object may not be deleted until \a object is destroyed.
 490
 491     A common usage scenario is for a type to enhance the properties
 492     available to its children in order to gather instance specific data.
 493
 494     \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml begin
 495     \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml rsvp
 496     \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml end
 497
 498     However, as a QML type cannot limit the instances to which the attachment
 499     object must attach, the following is also allowed, even though adding a
 500     birthday party rsvp in this context will have no effect. Instead, \c
 501     BirthdayParty could be a separate component with a property \c rsvp.
 502     \code
 503     GraduationParty {
 504         Boy { BirthdayParty.rsvp: "2009-06-01" }
 505     }
 506     \endcode
 507
 508     From C++, including the attaching type implementation, the attachment object
 509     for an instance can be accessed using the following method:
 510
 511     \code
 512     template<typename T>
 513     QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true);
 514     \endcode
 515
 516     This returns the attachment object attached to \a attachee by the attaching
 517     type \a T. If type \a T is not a valid attaching type, this method always
 518     returns 0. If \a create is true, a valid attachment object will always be
 519     returned, creating it if it does not already exist. If \a create is false,
 520     the attachment object will only be returned if it has previously been
 521     created.
 522
 523     The \c rsvp properties of each guest in the \c Birthday party is accessible
 524     through the \c qmlAttachedPropertiesObject function.
 525
 526     \snippet examples/qml/cppextensions/referenceexamples/attached/main.cpp query rsvp
 527
 528     The
 529     \l {Extending QML - Attached Properties Example}{Attached Properties Example}
 530     demonstrates the creation of attached properties with a birthday party
 531     scenario.
 532
 533 \section2 Object and List Properties
 534
 535     QML can set properties of types that are more complex than basic intrinsics like
 536     integers and strings.  Properties can also be object pointers, Qt interface
 537     pointers,  lists of object pointers, and lists of Qt interface pointers.  As QML
 538     is typesafe it ensures that only valid types are assigned to these properties,
 539     just like it does for primitive types.
 540
 541     Properties that are pointers to objects or Qt interfaces are declared with the
 542     Q_PROPERTY() macro, just like other properties.  The \c host property
 543     declaration looks like this:
 544
 545     \snippet examples/qml/cppextensions/referenceexamples/properties/birthdayparty.h 1
 546
 547     As long as the property type, in this case \c Person, is registered with QML the
 548     property can be assigned.
 549
 550     QML also supports assigning Qt interfaces.  To assign to a property whose type
 551     is a Qt interface pointer, the interface must also be registered with QML.  As
 552     they cannot be instantiated directly, registering a Qt interface is different
 553     from registering a new QML type. The following function is used instead:
 554
 555     \code
 556     template<typename T>
 557     int qmlRegisterInterface(const char *typeName)
 558     \endcode
 559
 560     \c qmlRegisterInterface registers the C++ interface \a T with the QML system
 561     as \a typeName.
 562
 563     Following registration, QML can coerce objects that implement this interface
 564     for assignment to appropriately typed properties.
 565
 566
 567     \snippet examples/qml/cppextensions/referenceexamples/properties/example.qml 0
 568
 569     The \c guests property is a \e{list property} of \c Person objects. A list
 570     of \c Person objects are bound to the \c BirthdayParty's \c host property,
 571     and assigns three \c Person objects to the guests property.
 572
 573     Properties that are lists of objects or Qt interfaces are also declared with
 574     the Q_PROPERTY() macro. However, list properties must have the type
 575     \l{QQmlListProperty}{QQmlListProperty<T>}.
 576
 577     \snippet examples/qml/cppextensions/referenceexamples/properties/birthdayparty.h 2
 578
 579     As with the other property types, the type of list content, \a T, must be
 580     \l{Creating QML Object Types from C++}{registered} into the runtime.
 581
 582     \snippet examples/qml/cppextensions/referenceexamples/properties/main.cpp register list
 583
 584     \l {Extending QML - Object and List Property Types Example} shows the
 585     complete code used to create the \c BirthdayParty type. For more
 586     information, visit \l{QQmlListProperty}{QQmlListProperty<T>}
 587     for creating list properties.
 588
 589 \section2 Sequence Types
 590
 591     Certain C++ sequence types are supported transparently in QML as JavaScript
 592     Array types.
 593     In particular, QML currently supports:
 594     \list
 595       \li \c {QList<int>}
 596       \li \c {QList<qreal>}
 597       \li \c {QList<bool>}
 598       \li \c {QList<QString>} and \c{QStringList}
 599       \li \c {QList<QUrl>}
 600     \endlist
 601
 602     These sequence types are implemented directly in terms of the underlying C++
 603     sequence. There are two ways in which such sequences can be exposed to QML:
 604     as a Q_PROPERTY of the given sequence type; or as the return type of a
 605     Q_INVOKABLE method. There are some differences in the way these are
 606     implemented, which are important to note.
 607
 608     If the sequence is exposed as a Q_PROPERTY, accessing any value in the
 609     sequence by index will cause the sequence data to be read from the QObject's
 610     property, then a read to occur. Similarly, modifying any value in the
 611     sequence will cause the sequence data to be read, and then the modification
 612     will be performed and the modified sequence will be written back to the
 613     QObject's property.
 614
 615     If the sequence is returned from a Q_INVOKABLE function, access and mutation
 616     is much cheaper, as no QObject property read or write occurs; instead, the
 617     C++ sequence data is accessed and modified directly.
 618
 619     Other sequence types are not supported transparently, and instead an
 620     instance of any other sequence type will be passed between QML and C++ as an
 621     opaque QVariantList.
 622
 623     \b {Important Note:} There are some minor differences between the
 624     semantics of such sequence Array types and default JavaScript Array types
 625     which result from the use of a C++ storage type in the implementation. In
 626     particular, deleting an element from an Array will result in a
 627     default-constructed value replacing that element, rather than an Undefined
 628     value. Similarly, setting the length property of the Array to a value larger
 629     than its current value will result in the Array being padded out to the
 630     specified length with default-constructed elements rather than Undefined
 631     elements.  Finally, the Qt container classes support signed (rather than
 632     unsigned) integer indexes; thus, attempting to access any index greater
 633     than INT_MAX will fail.
 634
 635     The default-constructed values for each sequence type are as follows:
 636     \table
 637     \row \li QList<int> \li integer value 0
 638     \row \li QList<qreal> \li real value 0.0
 639     \row \li QList<bool> \li boolean value \c {false}
 640     \row \li QList<QString> and QStringList \li empty QString
 641     \row \li QList<QUrl> \li empty QUrl
 642     \endtable
 643
 644     If you wish to remove elements from a sequence rather than simply replace
 645     them with default constructed values, do not use the indexed delete operator
 646     ("delete sequence[i]") but instead use the \c {splice} function
 647     ("sequence.splice(startIndex, deleteCount)").
 648
 649
 650
 651
 652 \section1 Property Value Sources
 653
 654 \snippet examples/qml/cppextensions/referenceexamples/valuesource/example.qml 0
 655 \snippet examples/qml/cppextensions/referenceexamples/valuesource/example.qml 1
 656
 657 The QML snippet shown above applies a property value source to the \c announcement property.
 658 A property value source generates a value for a property that changes over time.
 659
 660 Property value sources are most commonly used to do animation.  Rather than
 661 constructing an animation object and manually setting the animation's "target"
 662 property, a property value source can be assigned directly to a property of any
 663 type and automatically set up this association.
 664
 665 The example shown here is rather contrived: the \c announcement property of the
 666 \c BirthdayParty object is a string that is printed every time it is assigned and
 667 the \c HappyBirthdaySong value source generates the lyrics of the song
 668 "Happy Birthday".
 669
 670 \snippet examples/qml/cppextensions/referenceexamples/valuesource/birthdayparty.h 0
 671
 672 Normally, assigning an object to a string property would not be allowed.  In
 673 the case of a property value source, rather than assigning the object instance
 674 itself, the QML engine sets up an association between the value source and
 675 the property.
 676
 677 Property value sources are special types that derive from the
 678 QQmlPropertyValueSource base class.  This base class contains a single method,
 679 QQmlPropertyValueSource::setTarget(), that the QML engine invokes when
 680 associating the property value source with a property.  The relevant part of
 681 the \c HappyBirthdaySong type declaration looks like this:
 682
 683 \snippet examples/qml/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 0
 684 \snippet examples/qml/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 1
 685 \snippet examples/qml/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 2
 686
 687 In all other respects, property value sources are regular QML types.  They must
 688 be registered with the QML engine using the same macros as other types, and can
 689 contain properties, signals and methods just like other types.
 690
 691 When a property value source object is assigned to a property, QML first tries
 692 to assign it normally, as though it were a regular QML type.  Only if this
 693 assignment fails does the engine call the \l {QQmlPropertyValueSource::}{setTarget()} method.  This allows
 694 the type to also be used in contexts other than just as a value source.
 695
 696 \l {Extending QML -  Property Value Source Example} shows the complete code used
 697 to implement the \c HappyBirthdaySong property value source.
 698
 699
 700
 701 */