1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
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
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
28 \page qml-c++types.html
29 \title Creating QML Types
30 \brief exposing Qt C++ types into the QML engine
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.
36 \target register-c++-type
37 \section1 Register a Type
39 In an application or a \l{QML Plugins}{plugin}, the \c qmlRegisterType
40 template will register a class to the QML engine.
44 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
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
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
58 The application registers the class to the runtime with the
59 \l{qmlRegisterType()}.
61 \snippet declarative/cppextensions/referenceexamples/adding/main.cpp 0
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
67 The \l {Extending QML - Adding Types Example}{Adding Types} example
68 demonstrates as usage of the \l qmlRegisterType().
70 Alternatively, these functions provide a way for other types of C++ types
71 to be visible in the QML context.
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}
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.
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.
92 \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1
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.
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
106 int qmlRegisterInterface(const char *typeName)
109 This function registers the C++ interface \a T with the QML system as \a
112 Following registration, QML can \l{qml-c++-coercion}{coerce} objects that
113 implement this interface for assignment to appropriately typed properties.
115 \target qml-expose-properties
116 \section1 Exposing Qt C++ Properties
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.
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.
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.
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.
137 Q_PROPERTY(int size READ size WRITE setSize NOTIFY shoeChanged)
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
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
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++.
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.
165 //A read-only property
166 Q_PROPERTY(int size READ size CONSTANT)
169 \section2 Default Property
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
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.
180 Q_CLASSINFO("DefaultProperty", "pipe")
183 The property tagged as default property, \c pipe, can only be an object
184 property, or a list property.
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.
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.
195 \section2 Grouped Properties
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.
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 .
206 \snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml ungrouped
208 Alternatively, the group can be accessed as a set.
209 \snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml grouped
211 A grouped property block is implemented as a read-only object property. The
212 \c shoe property shown is declared like this:
214 \snippet examples/declarative/cppextensions/referenceexamples/grouped/person.h 1
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.
219 Grouped property blocks may declared and accessed be recusively.
221 \l {Extending QML - Grouped Properties Example} shows the complete code used to
222 implement the \c shoe property grouping.
224 \section2 Attached Properties
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.
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
236 \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml 1
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
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.
247 static AttachedPropertiesType *qmlAttachedProperties(QObject *object);
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.
257 \snippet examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h static attached
259 The QML_DECLARE_TYPEINFO() macro can notify the runtime that the type has
260 attached properties with the QML_HAS_ATTACHED_PROPERTIES argument.
262 \snippet examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h declare attached
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.
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.
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
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.
282 Boy { BirthdayParty.rsvp: "2009-06-01" }
286 From C++, including the attaching type implementation, the attachment object
287 for an instance can be accessed using the following method:
291 QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true);
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
301 The \c rsvp properties of each guest in the \c Birthday party is accessible
302 through the \c qmlAttachedPropertiesObject function.
304 \snippet examples/declarative/cppextensions/referenceexamples/attached/main.cpp query rsvp
307 \l {Extending QML - Attached Properties Example}{Attached Properties Example}
308 demonstrates the creation of attached properties with a birthday party
311 \section2 Object and List Properties
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.
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:
323 \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1
325 As long as the property type, in this case \c Person, is registered with QML the
326 property can be assigned.
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:
335 int qmlRegisterInterface(const char *typeName)
338 \c qmlRegisterInterface registers the C++ interface \a T with the QML system
341 Following registration, QML can coerce objects that implement this interface
342 for assignment to appropriately typed properties.
345 \snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0
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.
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{QQmlListProperty}{QQmlListProperty<T>}.
355 \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 2
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.
360 \snippet examples/declarative/cppextensions/referenceexamples/properties/main.cpp register list
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{QQmlListProperty}{QQmlListProperty<T>}
365 for creating list properties.
367 \section2 Sequence Types
369 Certain C++ sequence types are supported transparently in QML as JavaScript
371 In particular, QML currently supports:
376 \o \c {QList<QString>} and \c{QStringList}
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.
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
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.
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
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.
413 The default-constructed values for each sequence type are as follows:
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
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)").
428 \section2 Property Signals
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.
436 Here is the \c host property declaration:
438 \snippet examples/declarative/cppextensions/referenceexamples/binding/birthdayparty.h 0
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.
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.
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
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.
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
479 \snippet examples/declarative/cppextensions/referenceexamples/binding/person.h 0
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.
486 \l {Extending QML - Binding Example} shows the BirthdayParty example updated to
487 include NOTIFY signals for use in binding.
489 \section1 Signals Support
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.
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
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.
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.
512 To use signals from items not created in QML, access their signals with the
513 \l {Connections} element.
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.
521 The \l {Extending QML - Signal Support Example}{Signal Support Example}
522 shows an example application exposing signals to a QML component.
524 \section1 Exposing Methods
526 The Q_INVOKABLE macro exposes any Qt C++ method as a QML method.
528 \snippet examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h 0
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
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
538 An alternative to the Q_INVOKABLE macro is to declare the C++ method as a
539 \l{signals and slot}{slot}.
543 void invite(const QString &name);
546 \section1 Type Revisions and Versions
548 Type revisions and versions allow new properties or methods to exist in the
549 new version while remaining compatible with previous versions.
551 Consider these two QML files:
568 where \c CppItem maps to the C++ class \c QCppItem.
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.
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:
582 class CppElement : public BaseObject
585 Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1)
588 Q_REVISION(1) void rootChanged();
592 To register the new class revision to a particular version the following function is used:
595 template<typename T, int metaObjectRevision>
596 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
599 To register \c CppElement version 1 for \c {MyModule 1.1}:
602 qmlRegisterType<QCppElement,1>("MyModule", 1, 1, "CppElement")
605 \c root is only available when MyModule 1.1 is imported.
607 For the same reason, new elements introduced in later versions should use
608 the minor version argument of qmlRegisterType.
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.
616 You may also register the revision of a base class that your module depends upon
617 using the qmlRegisterRevision() function:
620 template<typename T, int metaObjectRevision>
621 int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
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:
628 qmlRegisterRevision<BaseObject,1>("MyModule", 1, 1);
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.
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.
640 \target qml-c++-coercion
641 \section1 Inheritance and Coercion
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
648 \snippet examples/declarative/cppextensions/referenceexamples/coercion/example.qml 0
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.
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.
664 int qmlRegisterType()
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.
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.
677 Type \a T must inherit QObject, but there are no restrictions on whether it
678 is concrete or the signature of its constructor.
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
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.
687 \target qml-c++-extension
688 \section1 Extension Objects
690 \snippet examples/declarative/cppextensions/referenceexamples/extended/example.qml 0
692 The \c leftMargin property is a new property to an existing C++ type,
693 \l QLineEdit, without modifying its source code.
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.
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
709 The \l qmlRegisterExtendedType() is for registering extended types. Note
710 that it has two forms.
712 template<typename T, typename ExtendedT>
713 int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
715 template<typename T, typename ExtendedT>
716 int qmlRegisterExtendedType()
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.
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
730 The \l{Extending QML - Extension Objects}{Extension Objects} example
731 demonstrates a usage of extension objects.
733 \section1 Property Value Sources
735 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 0
736 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 1
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.
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.
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
751 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/birthdayparty.h 0
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
758 Property value sources are special types that derive from the
759 QQmlPropertyValueSource base class. This base class contains a single method,
760 QQmlPropertyValueSource::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:
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
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.
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 {QQmlPropertyValueSource::}{setTarget()} method. This allows
775 the type to also be used in contexts other than just as a value source.
777 \l {Extending QML - Property Value Source Example} shows the complete code used
778 to implement the \c HappyBirthdaySong property value source.
780 \section1 Optimization and Other Considerations
782 The \l{qml-engine-optimization}{ QML Engine} article suggests possible
783 optimization considerations as memory management and QVariant type usages.