doc/src/qml/qmltypes.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 qml-c++types.html
  29 \title Creating QML Types
  30 \brief exposing Qt C++ types into the QML engine
  31
  32 The \l{The QML Engine}{QML engine} can instantiate any Qt C++ construct
  33 such as \l{The Property System}{properties}, functions, and data models into
  34 the QML context allowing the constructs to be accessible from within QML.
  35
  36 \target register-c++-type
  37 \section1 Register a Type
  38
  39     In an application or a \l{QML Plugins}{plugin}, the \c qmlRegisterType
  40     template will register a class to the QML engine.
  41
  42 \code
  43 template<typename T>
  44 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
  45 \endcode
  46
  47     \l qmlRegisterType() registers the C++ type \a T with the QML system, and
  48     makes it available to the QML context under the name \c qmlName in library
  49     \c uri version \c versionMajor.versionMinor. The \c qmlName can be the same
  50     as the C++ type name.
  51
  52     Suppose that a \c Person class defined in a C++ is to be exposed into the
  53     QML context. The class must be a subclass of \l{QObject} and have a default
  54     constructor. The \l{The Property System}{properties} created with the
  55     Q_PROPERTY macro are visible in the QML context as well.
  56     \snippet declarative/cppextensions/referenceexamples/adding/person.h 0
  57
  58     The application registers the class to the runtime with the
  59     \l{qmlRegisterType()}.
  60
  61     \snippet declarative/cppextensions/referenceexamples/adding/main.cpp 0
  62
  63     The Person type is then imported with the \c "People 1.0" module and its
  64     properties are accessible in a QML file.
  65 \snippet declarative/cppextensions/referenceexamples/adding/example.qml 0
  66
  67     The \l {Extending QML - Adding Types Example}{Adding Types} example
  68     demonstrates as usage of the \l qmlRegisterType().
  69
  70     Alternatively, these functions provide a way for other types of C++ types
  71     to be visible in the QML context.
  72     \list
  73     \o \l qmlRegisterUncreatableType() is suited for attached
  74     properties and enum types.
  75     \o \l qmlRegisterTypeNotAvailable() is for
  76     reserving a namespace and suited for generating useful errors.
  77     \o \l qmlRegisterInterface() - for registering base or abstract classes for
  78     \l{qml-c++-coercion}{coercion and inheritance}. This is useful for general
  79     Qt objects or \l{Qt Objects and Interfaces}{pointers} to objects.
  80     \o \l qmlRegisterExtendedType() - for \l{qml-c++-extension}{extended types}
  81     \endlist
  82
  83     \section2 Qt Objects and Interfaces
  84     QML can bind to complex objects such as pointers to objects or lists. As QML
  85     is typesafe, the \l{The QML Engine}{QML engine} ensures that only
  86     valid types are assigned to these properties.
  87
  88     The QML engine treats pointers to objects or Qt interfaces the same
  89     way as regular properties. Thus, the lists or pointers are created as
  90     properties using the Q_PROPERTY() macro.
  91
  92     \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1
  93
  94     The \c host is an \l{qml-expose-properties}{exposed property} that can bind
  95     to objects or lists of objects. The property type, in this case \c Person,
  96     must be \l{register-c++-type}{registered} into the runtime.
  97
  98     QML also supports assigning Qt interfaces. To assign to a property whose
  99     type is a Qt interface pointer, the interface must also be registered with
 100     QML. As they cannot be instantiated directly, registering a Qt interface is
 101     different from registering a new QML type. The following function is used
 102     instead:
 103
 104     \code
 105     template<typename T>
 106     int qmlRegisterInterface(const char *typeName)
 107     \endcode
 108
 109     This function registers the C++ interface \a T with the QML system as \a
 110     typeName.
 111
 112     Following registration, QML can \l{qml-c++-coercion}{coerce} objects that
 113     implement this interface for assignment to appropriately typed properties.
 114
 115 \target qml-expose-properties
 116 \section1 Exposing Qt C++ Properties
 117
 118     The \l{The QML Engine}{QML engine} utilizes Qt's
 119     \l{The Property System}{Property System} and in effect, QML
 120     \l{Property Binding in QML}{property bindings} also use Qt properties.
 121
 122     Essentially, a Qt C++ property has a \i write function, \i read function,
 123     and has a signal function. QML properties are inheritely public, both
 124     readable and writable, albeit type-safe. QML properties may also have
 125     signals which are emitted when the property value or binding changes.
 126
 127     The QML property equivalent of a Qt C++ property is created as a property
 128     with the \l Q_PROPERTY() macro. There needs to be C++ functions assigned as
 129     the property's read, write, and signal handler function.
 130
 131     The \l {register-c++-type}{Register a Type} section mentions that the
 132     \c Person class has properties that are exposed to the QML context. The QML
 133     properties are created with the \c Q_PROPERTY macro. The macro associates
 134     the properties to the read, write, and singal functions in its argument.
 135
 136 \code
 137 Q_PROPERTY(int size READ size WRITE setSize NOTIFY shoeChanged)
 138 \endcode
 139
 140     A \c Shoe class might have an integer property called \c size. We set the \c
 141     size() function as the \c READ function and the \c setSize() function to be
 142     the \c WRITE function. In a QML application, when a property is read, the \c
 143     size() is called and when the property's binding changes, the \c setSize()
 144     is called. The READ function, by definition, must return the same type as
 145     the property.
 146
 147     We may also connect a \l{signals and slots}{signal} to a property. The \c
 148     size property may have a \c shoeChanged signal indicated after the \c NOTIFY
 149     parameter of the macro. The \c shoeChanged becomes a \l{QML Signal and
 150     Handler Event System}{QML signal} and the runtime will create QML handler
 151     called \c onShoeChanged. Whenever the size property's binding changes, the
 152     \c shoeChanged signal is emitted and the \c onShoeChanged handler is
 153     invoked. In the handler, commands such as \l{JavaScript Expressions in
 154     QML}{JavaScript expressions} can perform clean-up operations or call other
 155     functions.
 156
 157     \bold{Note:} The QML signal handler will always be named
 158     on<Property-name>Changed, regardless of the name used for the NOTIFY
 159     signal in C++. We recommend using <property-name>Changed() for the
 160     NOTIFY signal in C++.
 161
 162     We may also make the property a \c read-only property by placing
 163     \c CONSTANT in the parameter. Changing the binding will generate an error.
 164 \code
 165 //A read-only property
 166 Q_PROPERTY(int size READ size CONSTANT)
 167 \endcode
 168
 169 \section2 Default Property
 170
 171     When imported, QML components will bind their children to their designated
 172     \l{default-property}{default property}. This is helpful, for example,
 173     to redirect any declared child components to a property of another
 174     component.
 175
 176     The runtime can set a property to be the default property by tagging the
 177     property with \c DefaultProperty in The Q_CLASSINFO() macro.
 178
 179     \code
 180     Q_CLASSINFO("DefaultProperty", "pipe")
 181     \endcode
 182
 183     The property tagged as default property, \c pipe, can only be an object
 184     property, or a list property.
 185
 186     A default property is optional. A derived class inherits its base class's
 187     default property, but may override it in its own declaration. The \c pipe
 188     property can refer to a property declared in the class itself, or a property
 189     inherited from a base class.
 190
 191     The \l{Extending QML - Default Property Example}{Default Property} example
 192     uses \l{default-property}{default properties} to assign the children of
 193     a component to a specific property.
 194
 195     \section2 Grouped Properties
 196
 197     A property group may be functionally defined as a set of related properties.
 198     For example, the \l{Layouts with Anchors}{anchors} are a group of
 199     related properties. In practice, property groups resemble a parent object
 200     where the individual properties are accessed as children.
 201
 202     A grouped property's member properties are accessed using the
 203     <group>.<property> notation. For example, shoe.color is the way to access
 204     the \c color property in the \c shoe property group .
 205
 206     \snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml ungrouped
 207
 208     Alternatively, the group can be accessed as a set.
 209     \snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml grouped
 210
 211     A grouped property block is implemented as a read-only object property. The
 212     \c shoe property shown is declared like this:
 213
 214     \snippet examples/declarative/cppextensions/referenceexamples/grouped/person.h 1
 215
 216     The \c ShoeDescription type declares the properties available to the grouped
 217     property block - in this case the \c size, \c color, \c brand and \c price properties.
 218
 219     Grouped property blocks may declared and accessed be recusively.
 220
 221     \l {Extending QML - Grouped Properties Example} shows the complete code used to
 222     implement the \c shoe property grouping.
 223
 224     \section2 Attached Properties
 225
 226     Attached properties annotate or add properties to another type or component.
 227     For example, the \l Keys \i{attaching type} contains \i{attached properties}
 228     that other elements may use to respond to key input. Conceptually, attached
 229     properties are a \i type exporting a set of additional properties that can
 230     be set on any other object instance.
 231
 232     The attaching type is a QObject derived type. The properties on the
 233     attaching type are those that become available for use as attached
 234     properties.
 235
 236     \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml 1
 237
 238     The \c BirthdayParty is called the attaching type and the
 239     \c Boy instance the attachee object instance. The property \c rsvp is the
 240     attached property.
 241
 242     Any Qt C++ type can become an attaching type by declaring the \c
 243     qmlAttachedProperties() a public member function and declaring that the
 244     class has QML_HAS_ATTACHED_PROPERTIES.
 245
 246     \code
 247     static AttachedPropertiesType *qmlAttachedProperties(QObject *object);
 248     \endcode
 249
 250     This static pointer returns an attachment object, of type \a
 251     AttachedPropertiesType, for the attachee \a object instance. It is
 252     customary, though not strictly required, for the attachment object to be
 253     parented to \a object to prevent memory leaks.
 254     The \l {Extending QML - Attached Properties Example}{Birthday}
 255     class has \c BirthdayPartyAttached attached properties.
 256
 257     \snippet examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h static attached
 258
 259     The QML_DECLARE_TYPEINFO() macro can notify the runtime that the type has
 260     attached properties with the QML_HAS_ATTACHED_PROPERTIES argument.
 261
 262     \snippet examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h declare attached
 263
 264     The qmlAttachedProperties method will be called at most once for each
 265     attachee object instance. The QML engine will cache the returned instance
 266     pointer for subsequent attached property accesses. Consequently the
 267     attachment object may not be deleted until \a object is destroyed.
 268
 269     A common usage scenario is for a type to enhance the properties
 270     available to its children in order to gather instance specific data.
 271
 272     \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml begin
 273     \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml rsvp
 274     \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml end
 275
 276     However, as a QML type cannot limit the instances to which the attachment
 277     object must attach, the following is also allowed, even though adding a
 278     birthday party rsvp in this context will have no effect. Instead, \c
 279     BirthdayParty could be a separate component with a property \c rsvp.
 280     \code
 281     GraduationParty {
 282         Boy { BirthdayParty.rsvp: "2009-06-01" }
 283     }
 284     \endcode
 285
 286     From C++, including the attaching type implementation, the attachment object
 287     for an instance can be accessed using the following method:
 288
 289     \code
 290     template<typename T>
 291     QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true);
 292     \endcode
 293
 294     This returns the attachment object attached to \a attachee by the attaching
 295     type \a T. If type \a T is not a valid attaching type, this method always
 296     returns 0. If \a create is true, a valid attachment object will always be
 297     returned, creating it if it does not already exist. If \a create is false,
 298     the attachment object will only be returned if it has previously been
 299     created.
 300
 301     The \c rsvp properties of each guest in the \c Birthday party is accessible
 302     through the \c qmlAttachedPropertiesObject function.
 303
 304     \snippet examples/declarative/cppextensions/referenceexamples/attached/main.cpp query rsvp
 305
 306     The
 307     \l {Extending QML - Attached Properties Example}{Attached Properties Example}
 308     demonstrates the creation of attached properties with a birthday party
 309     scenario.
 310
 311 \section2 Object and List Properties
 312
 313     QML can set properties of types that are more complex than basic intrinsics like
 314     integers and strings.  Properties can also be object pointers, Qt interface
 315     pointers,  lists of object pointers, and lists of Qt interface pointers.  As QML
 316     is typesafe it ensures that only valid types are assigned to these properties,
 317     just like it does for primitive types.
 318
 319     Properties that are pointers to objects or Qt interfaces are declared with the
 320     Q_PROPERTY() macro, just like other properties.  The \c host property
 321     declaration looks like this:
 322
 323     \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1
 324
 325     As long as the property type, in this case \c Person, is registered with QML the
 326     property can be assigned.
 327
 328     QML also supports assigning Qt interfaces.  To assign to a property whose type
 329     is a Qt interface pointer, the interface must also be registered with QML.  As
 330     they cannot be instantiated directly, registering a Qt interface is different
 331     from registering a new QML type. The following function is used instead:
 332
 333     \code
 334     template<typename T>
 335     int qmlRegisterInterface(const char *typeName)
 336     \endcode
 337
 338     \c qmlRegisterInterface registers the C++ interface \a T with the QML system
 339     as \a typeName.
 340
 341     Following registration, QML can coerce objects that implement this interface
 342     for assignment to appropriately typed properties.
 343
 344
 345     \snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0
 346
 347     The \c guests property is a \i{list property} of \c Person objects. A list
 348     of \c Person objects are bound to the \c BirthdayParty's \c host property,
 349     and assigns three \c Person objects to the guests property.
 350
 351     Properties that are lists of objects or Qt interfaces are also declared with
 352     the Q_PROPERTY() macro. However, list properties must have the type
 353     \l{QDeclarativeListProperty}{QDeclarativeListProperty<T>}.
 354
 355     \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 2
 356
 357     As with the other property types, the type of list content, \a T, must be
 358     \l{register-c++-type}{registered} into the runtime.
 359
 360     \snippet examples/declarative/cppextensions/referenceexamples/properties/main.cpp register list
 361
 362     \l {Extending QML - Object and List Property Types Example} shows the
 363     complete code used to create the \c BirthdayParty type. For more
 364     information, visit \l{QDeclarativeListProperty}{QDeclarativeListProperty<T>}
 365     for creating list properties.
 366
 367 \section2 Sequence Types
 368
 369     Certain C++ sequence types are supported transparently in QML as JavaScript
 370     Array types.
 371     In particular, QML currently supports:
 372     \list
 373       \o \c {QList<int>}
 374       \o \c {QList<qreal>}
 375       \o \c {QList<bool>}
 376       \o \c {QList<QString>} and \c{QStringList}
 377       \o \c {QList<QUrl>}
 378     \endlist
 379
 380     These sequence types are implemented directly in terms of the underlying C++
 381     sequence. There are two ways in which such sequences can be exposed to QML:
 382     as a Q_PROPERTY of the given sequence type; or as the return type of a
 383     Q_INVOKABLE method. There are some differences in the way these are
 384     implemented, which are important to note.
 385
 386     If the sequence is exposed as a Q_PROPERTY, accessing any value in the
 387     sequence by index will cause the sequence data to be read from the QObject's
 388     property, then a read to occur. Similarly, modifying any value in the
 389     sequence will cause the sequence data to be read, and then the modification
 390     will be performed and the modified sequence will be written back to the
 391     QObject's property.
 392
 393     If the sequence is returned from a Q_INVOKABLE function, access and mutation
 394     is much cheaper, as no QObject property read or write occurs; instead, the
 395     C++ sequence data is accessed and modified directly.
 396
 397     Other sequence types are not supported transparently, and instead an
 398     instance of any other sequence type will be passed between QML and C++ as an
 399     opaque QVariantList.
 400
 401     \bold {Important Note:} There are some minor differences between the
 402     semantics of such sequence Array types and default JavaScript Array types
 403     which result from the use of a C++ storage type in the implementation. In
 404     particular, deleting an element from an Array will result in a
 405     default-constructed value replacing that element, rather than an Undefined
 406     value. Similarly, setting the length property of the Array to a value larger
 407     than its current value will result in the Array being padded out to the
 408     specified length with default-constructed elements rather than Undefined
 409     elements.  Finally, the Qt container classes support signed (rather than
 410     unsigned) integer indexes; thus, attempting to access any index greater
 411     than INT_MAX will fail.
 412
 413     The default-constructed values for each sequence type are as follows:
 414     \table
 415     \row \o QList<int> \o integer value 0
 416     \row \o QList<qreal> \o real value 0.0
 417     \row \o QList<bool> \o boolean value \c {false}
 418     \row \o QList<QString> and QStringList \o empty QString
 419     \row \o QList<QUrl> \o empty QUrl
 420     \endtable
 421
 422     If you wish to remove elements from a sequence rather than simply replace
 423     them with default constructed values, do not use the indexed delete operator
 424     ("delete sequence[i]") but instead use the \c {splice} function
 425     ("sequence.splice(startIndex, deleteCount)").
 426
 427
 428 \section2 Property Signals
 429
 430     All properties on custom types automatically support property binding.
 431     However, for binding to work correctly, QML must be able to reliably
 432     determine when a property has changed so that it knows to reevaluate any
 433     bindings that depend on the property's value. QML relies on the presence of
 434     a \l {Qt's Property System}{NOTIFY signal} for this determination.
 435
 436     Here is the \c host property declaration:
 437
 438     \snippet examples/declarative/cppextensions/referenceexamples/binding/birthdayparty.h 0
 439
 440     The NOTIFY attribute is followed by a signal name. It is the responsibility
 441     of the class implementer to ensure that whenever the property's value
 442     changes, the NOTIFY signal is emitted. The signature of the NOTIFY signal is
 443     not important to QML.
 444
 445     To prevent loops or excessive evaluation, developers should ensure that the
 446     signal is only emitted whenever the property's value is actually changed. If
 447     a property, or group of properties, is infrequently used it is permitted to
 448     use the same NOTIFY signal for several properties. This should be done with
 449     care to ensure that performance doesn't suffer.
 450
 451     To keep QML reliable, if a property does not have a NOTIFY signal, it cannot
 452     be used in a binding expression. However, the property can still be assigned
 453     a binding as QML does not need to monitor the property for change in that
 454     scenario.
 455
 456     Consider a custom type, \c TestElement, that has two properties, \c a and
 457     \c b. Property \c a does \i not have a NOTIFY signal, and property \c b does
 458     have a NOTIFY signal.
 459
 460     \code
 461     TestElement {
 462         // This is OK
 463         a: b
 464     }
 465     TestElement {
 466         // Will NOT work
 467         b: a
 468     }
 469     \endcode
 470
 471     The presence of a NOTIFY signal does incur a small overhead. There are cases
 472     where a property's value is set at object construction time, and does not
 473     subsequently change. The most common case of this is when a type uses \l
 474     {Grouped Properties}, and the grouped property object is allocated once, and
 475     only freed when the object is deleted. In these cases, the CONSTANT
 476     attribute may be added to the property declaration instead of a NOTIFY
 477     signal.
 478
 479     \snippet examples/declarative/cppextensions/referenceexamples/binding/person.h 0
 480
 481     Extreme care must be taken here or applications using your type may misbehave.
 482     The CONSTANT attribute should only be used for properties whose value is set,
 483     and finalized, only in the class constructor.  All other properties that want
 484     to be used in bindings should have a NOTIFY signal instead.
 485
 486     \l {Extending QML -  Binding Example} shows the BirthdayParty example updated to
 487     include NOTIFY signals for use in binding.
 488
 489 \section1 Signals Support
 490
 491     A \l{signals and slots}{signal} in Qt C++ is readily available as a
 492     \l{QML Signal and Handler Event System}{QML signal}. A signal will have
 493     a corresponding signal \i{handler}, created automatically. The handler
 494     name will have \c on prepended at the beginning of the name. The first
 495     character of the signal is uppercased for the signal handler. The
 496     signal parameter is also availabe to the QML signal.
 497
 498     \snippet examples/declarative/cppextensions/referenceexamples/signal/birthdayparty.h 0
 499     The QML engine will create a handler for the \c partyStarted signal
 500     called \c onPartyStarted.
 501     \snippet examples/declarative/cppextensions/referenceexamples/signal/example.qml 0
 502
 503     Classes may have multiple signals with the same name, but only the final
 504     signal is accessible as a QML signal. Note that signals with the same name
 505     but different parameters cannot be distinguished from one another.
 506
 507     Signal parameters are exposed and can be any one of the QML
 508     \l{QML Basic Types}{basic types} as well registered object types. Accessing
 509     unregistered types will not generate an error, but the parameter value will
 510     not be accessible from the handler.
 511
 512     To use signals from items not created in QML, access their signals with the
 513     \l {Connections} element.
 514
 515     Additionally, if a property is added to a C++ class, all QML elements
 516     based on that C++ class will have a \i{value-changed} signal handler
 517     for that property. The name of the signal handler is
 518     \i{on<Property-name>Changed}, with the first letter of the property
 519     name being upper case.
 520
 521     The \l {Extending QML - Signal Support Example}{Signal Support Example}
 522     shows an example application exposing signals to a QML component.
 523
 524 \section1 Exposing Methods
 525
 526     The Q_INVOKABLE macro exposes any Qt C++ method as a QML method.
 527
 528     \snippet examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h 0
 529
 530     In a QML file, we can invoke the method as we would a
 531     \l{JavaScript Expressions in QML}{JavaScript expression}.
 532     \snippet examples/declarative/cppextensions/referenceexamples/methods/example.qml 0
 533
 534     \l {Extending QML - Methods Example}{Methods example} uses the Q_INVOKABLE
 535     method to expose methods and demonstrates some usages of the method in
 536     an application.
 537
 538     An alternative to the Q_INVOKABLE macro is to declare the C++ method as a
 539     \l{signals and slot}{slot}.
 540
 541     \code
 542     slots:
 543         void invite(const QString &name);
 544     \endcode
 545
 546 \section1 Type Revisions and Versions
 547
 548     Type revisions and versions allow new properties or methods to exist in the
 549     new version while remaining compatible with previous versions.
 550
 551     Consider these two QML files:
 552     \code
 553     // main.qml
 554     import QtQuick 1.0
 555     Item {
 556         id: root
 557         MyComponent {}
 558     }
 559     \endcode
 560
 561     \code
 562     // MyComponent.qml
 563     import MyModule 1.0
 564     CppItem {
 565         value: root.x
 566     }
 567     \endcode
 568     where \c CppItem maps to the C++ class \c QCppItem.
 569
 570     If the author of QCppItem adds a \c root property to QCppItem in a new
 571     version of the module, \c root.x now resolves to a different value because
 572     \c root is also the \c id of the top level component. The author could
 573     specify that the new \c root property is available from a specific minor
 574     version. This permits new properties and features to be added to existing
 575     elements without breaking existing programs.
 576
 577     The REVISION tag is used to mark the \c root property as added in revision 1
 578     of the class. Methods such as Q_INVOKABLE's, signals and slots can also be
 579     tagged for a revision using the \c Q_REVISION(x) macro:
 580
 581     \code
 582     class CppElement : public BaseObject
 583     {
 584         Q_OBJECT
 585         Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1)
 586
 587     signals:
 588         Q_REVISION(1) void rootChanged();
 589     };
 590     \endcode
 591
 592     To register the new class revision to a particular version the following function is used:
 593
 594     \code
 595     template<typename T, int metaObjectRevision>
 596     int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
 597     \endcode
 598
 599     To register \c CppElement version 1 for \c {MyModule 1.1}:
 600
 601     \code
 602     qmlRegisterType<QCppElement,1>("MyModule", 1, 1, "CppElement")
 603     \endcode
 604
 605     \c root is only available when MyModule 1.1 is imported.
 606
 607     For the same reason, new elements introduced in later versions should use
 608     the minor version argument of qmlRegisterType.
 609
 610     This feature of the language allows for behavioural changes to be made
 611     without breaking existing applications. Consequently QML module authors
 612     should always remember to document what changed between minor versions, and
 613     QML module users should check that their application still runs correctly
 614     before deploying an updated import statement.
 615
 616     You may also register the revision of a base class that your module depends upon
 617     using the qmlRegisterRevision() function:
 618
 619     \code
 620     template<typename T, int metaObjectRevision>
 621     int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
 622     \endcode
 623
 624     For example, if \c BaseObject is changed and now has a revision 1, you can specify that
 625     your module uses the new revision:
 626
 627     \code
 628     qmlRegisterRevision<BaseObject,1>("MyModule", 1, 1);
 629     \endcode
 630
 631     This is useful when deriving from base classes not declared as part of your
 632     module, e.g. when extending classes from the QtQuick library.
 633
 634     The revision feature of QML allows for behavioral changes without breaking
 635     existing applications. Consequently, QML module authors should always
 636     remember to document what changed between minor versions, and QML module
 637     users should check that their application still runs correctly before
 638     deploying an updated import statement.
 639
 640 \target qml-c++-coercion
 641 \section1 Inheritance and Coercion
 642
 643     QML supports C++ inheritance hierarchies and can freely coerce between
 644     known, valid object types. This enables the creation of common base classes
 645     that allow the assignment of specialized classes to object or list
 646     properties.
 647
 648     \snippet examples/declarative/cppextensions/referenceexamples/coercion/example.qml 0
 649
 650     The QML snippet shown above assigns a \c Boy object to the \c
 651     BirthdayParty's \c host property, and assigns three other objects to the \c
 652     guests property. Both the \c host and the \c guests properties binds to the
 653     \c Person type, but the assignment is valid as both the \c Boy and \c Girl
 654     objects inherit from \c Person.
 655
 656     To assign to a property, the property's type must have been
 657     \l{register-c++-type}{registered} to the \l{The QML Engine}{declarative
 658     runtime}. If a type that acts purely as a base class that cannot be
 659     instantiated from QML needs to be registered as well. The
 660     \l qmlRegisterType() is useful for this occasion.
 661
 662     \code
 663         template<typename T>
 664         int qmlRegisterType()
 665     \endcode
 666
 667     This function registers the C++ type \a T with the QML system. The
 668     parameterless call to the template function qmlRegisterType() does not
 669     define a mapping between the C++ class and a QML element name, so the type
 670     is not instantiable from QML, but it is available for type coercion.
 671
 672     \snippet examples/declarative/cppextensions/referenceexamples/coercion/main.cpp 0
 673     \snippet examples/declarative/cppextensions/referenceexamples/coercion/main.cpp register boy girl
 674     The \c Person class is registered withouth the parameters. Both the
 675     \c Boy and \c Girl class derive from the \c Person class.
 676
 677     Type \a T must inherit QObject, but there are no restrictions on whether it
 678     is concrete or the signature of its constructor.
 679
 680     QML will automatically coerce C++ types when assigning to either an object
 681     property, or to a list property. Only if coercion fails does an assignment
 682     error occur.
 683
 684     The \l{Extending QML - Inheritance and Coercion Example}{Inheritance and Coercion Example}
 685     shows the complete code used to create the \c Boy and \c Girl types.
 686
 687 \target qml-c++-extension
 688 \section1 Extension Objects
 689
 690     \snippet examples/declarative/cppextensions/referenceexamples/extended/example.qml 0
 691
 692     The \c leftMargin property is a new property to an existing C++ type,
 693     \l QLineEdit, without modifying its source code.
 694
 695     When integrating existing classes and technology into QML, APIs will
 696     often need tweaking to fit better into the declarative environment.
 697     Although the best results are usually obtained by modifying the original
 698     classes directly, if this is either not possible or is complicated by some
 699     other concerns, extension objects allow limited extension possibilities
 700     without direct modifications.
 701
 702     \i{Extension objects} add additional properties to an existing type.
 703     Extension objects can only add properties, not signals or methods. An
 704     extended type definition allows the programmer to supply an additional type,
 705     known as the \i{extension type}, when registering the class. The
 706     properties are transparently merged with the original target class when used
 707     from within QML.
 708
 709     The \l qmlRegisterExtendedType() is for registering extended types. Note
 710     that it has two forms.
 711     \code
 712     template<typename T, typename ExtendedT>
 713     int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
 714
 715     template<typename T, typename ExtendedT>
 716     int qmlRegisterExtendedType()
 717     \endcode
 718     functions should be used instead of the regular \c qmlRegisterType() variations.
 719     The arguments are identical to the corresponding non-extension registration functions,
 720     except for the ExtendedT parameter which is the type
 721     of the extension object.
 722
 723     An extension class is a regular QObject, with a constructor that takes a
 724     QObject pointer. However, the extension class creation is delayed until the
 725     first extended property is accessed. The extension class is created and the
 726     target object is passed in as the parent. When the property on the original
 727     is accessed, the corresponding property on the extension object is used
 728     instead.
 729
 730     The \l{Extending QML - Extension Objects}{Extension Objects} example
 731     demonstrates a usage of extension objects.
 732
 733 \section1 Property Value Sources
 734
 735 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 0
 736 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 1
 737
 738 The QML snippet shown above applies a property value source to the \c announcement property.
 739 A property value source generates a value for a property that changes over time.
 740
 741 Property value sources are most commonly used to do animation.  Rather than
 742 constructing an animation object and manually setting the animation's "target"
 743 property, a property value source can be assigned directly to a property of any
 744 type and automatically set up this association.
 745
 746 The example shown here is rather contrived: the \c announcement property of the
 747 \c BirthdayParty object is a string that is printed every time it is assigned and
 748 the \c HappyBirthdaySong value source generates the lyrics of the song
 749 "Happy Birthday".
 750
 751 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/birthdayparty.h 0
 752
 753 Normally, assigning an object to a string property would not be allowed.  In
 754 the case of a property value source, rather than assigning the object instance
 755 itself, the QML engine sets up an association between the value source and
 756 the property.
 757
 758 Property value sources are special types that derive from the
 759 QDeclarativePropertyValueSource base class.  This base class contains a single method,
 760 QDeclarativePropertyValueSource::setTarget(), that the QML engine invokes when
 761 associating the property value source with a property.  The relevant part of
 762 the \c HappyBirthdaySong type declaration looks like this:
 763
 764 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 0
 765 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 1
 766 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 2
 767
 768 In all other respects, property value sources are regular QML types.  They must
 769 be registered with the QML engine using the same macros as other types, and can
 770 contain properties, signals and methods just like other types.
 771
 772 When a property value source object is assigned to a property, QML first tries
 773 to assign it normally, as though it were a regular QML type.  Only if this
 774 assignment fails does the engine call the \l {QDeclarativePropertyValueSource::}{setTarget()} method.  This allows
 775 the type to also be used in contexts other than just as a value source.
 776
 777 \l {Extending QML -  Property Value Source Example} shows the complete code used
 778 to implement the \c HappyBirthdaySong property value source.
 779
 780 \section1 Optimization and Other Considerations
 781
 782 The \l{qml-engine-optimization}{ QML Engine} article suggests possible
 783 optimization considerations as memory management and QVariant type usages.
 784
 785 */