1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: http://www.qt-project.org/
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page qml-extending.html
30 \inqmlmodule QtQuick 1
32 \contentspage QML Features
33 \previouspage {Presenting Data with Views}
34 \nextpage {Using QML Bindings in C++ Applications}
35 \title Extending QML Functionalities using C++
37 The QML syntax declaratively describes how to construct an in-memory object
38 tree. In Qt, QML is mainly used to describe a visual scene graph, but it is
39 not conceptually limited to this: the QML format is an abstract description of
40 any object tree. All the QML element types included in Qt are implemented using
41 the C++ extension mechanisms describe on this page. Programmers can use these
42 APIs to add new types that interact with the existing Qt types, or to repurpose
43 QML for their own independent use.
47 \section1 Adding Types
50 \snippet examples/declarative/cppextensions/referenceexamples/adding/example.qml 0
52 The QML snippet shown above instantiates one \c Person instance and sets
53 the \c name and \c shoeSize properties on it. Everything in QML ultimately comes down
54 to either instantiating an object instance, or assigning a property a value.
56 QML relies heavily on Qt's meta object system and can only instantiate classes
57 that derive from QObject. For visual element types, this will usually mean a subclass
58 of QDeclarativeItem; for models used with the view elements, a subclass of QAbstractItemModel;
59 and for arbitrary objects with properties, a direct subclass of QObject.
61 The QML engine has no intrinsic knowledge of any class types. Instead the
62 programmer must register the C++ types with their corresponding QML names.
64 Custom C++ types are registered using a template function:
70 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
73 Calling qmlRegisterType() registers the C++ type \a T with the QML
74 system, and makes it available in QML under the name \a qmlName in
75 library \a uri version \a versionMajor.versionMinor. The \a qmlName
76 can be the same as the C++ type name.
78 Type \a T must be a concrete type that inherits QObject and has a default
83 #include <QtDeclarative> to use qmlRegisterType().
85 Types can be registered by libraries, application code, or by plugins
86 (see QDeclarativeExtensionPlugin).
88 Once registered, all \l {Qt's Property System}{properties} of the
89 supported types are available in QML. QML has intrinsic support for
90 properties of the types listed in the \l{QML Basic Types}
91 document, which includes the following:
94 \o bool, unsigned int, int, float, double, qreal
95 \o QString, QUrl, QColor
96 \o QDate, QTime, QDateTime
97 \o QPoint, QPointF, QSize, QSizeF, QRect, QRectF
101 When a property of a supported type is added to a C++ class, in a QML
102 element based on the C++ class, a \e{value-changed} signal handler
103 will be available. See \l{Signal Support} below.
105 QML is typesafe. Attempting to assign an invalid value to a property
106 will generate an error. For example, assuming the \e{name} property
107 of the \c Person element had a type of QString, this would cause an
117 \l {Extending QML - Adding Types Example} shows the complete code used to create
120 \section1 QML Type Versioning
122 In C++ adding a new method or property cannot break old applications.
123 In QML, however, new methods and properties can change what a name previously
124 resolved to to within a scope chain.
126 For example, consider these two QML files
145 where CppItem maps to the C++ class QCppItem.
147 If the author of QCppItem adds a "root" property to QCppItem in a new version of the module,
148 it will break the above program as \c root.x now resolves to a different value.
149 The solution is to allow the author of QCppItem to state that the new \c root property is
150 only available from a particular version of QCppItem onwards. This permits new properties
151 and features to be added to existing elements without breaking existing programs.
153 QML enables this by allowing the properties, methods and signals of a class to be tagged with
154 a particular \e revision, so that they are only accessible if the relevant module version
155 is imported. In this case, the author can tag the \c root property as being added in
156 \e {revision 1} of the class, and register that revision in version 1.1 of the module.
158 The REVISION tag is used to mark the \c root property as added in revision 1 of the class.
159 Methods such as Q_INVOKABLE's, signals and slots can also be tagged for a
160 revision using the \c Q_REVISION(x) macro:
163 class CppItem : public QObject
166 Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1)
169 Q_REVISION(1) void rootChanged();
173 To register the new class revision to a particular version the following function is used:
176 template<typename T, int metaObjectRevision>
177 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
180 To register \c CppItem version 1 for \c {MyModule 1.1}:
183 qmlRegisterType<QCppItem,1>("MyModule", 1, 1, "CppItem")
186 \c root is only available when MyModule 1.1 is imported.
189 \section1 Object and List Property Types
191 \snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0
193 The QML snippet shown above assigns a \c Person object to the \c BirthdayParty's
194 \c host property, and assigns three \c Person objects to the guests property.
196 QML can set properties of types that are more complex than basic intrinsics like
197 integers and strings. Properties can also be object pointers, Qt interface
198 pointers, lists of object pointers, and lists of Qt interface pointers. As QML
199 is typesafe it ensures that only valid types are assigned to these properties,
200 just like it does for primitive types.
202 Properties that are pointers to objects or Qt interfaces are declared with the
203 Q_PROPERTY() macro, just like other properties. The \c host property
204 declaration looks like this:
206 \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1
208 As long as the property type, in this case \c Person, is registered with QML the
209 property can be assigned.
211 QML also supports assigning Qt interfaces. To assign to a property whose type
212 is a Qt interface pointer, the interface must also be registered with QML. As
213 they cannot be instantiated directly, registering a Qt interface is different
214 from registering a new QML type. The following function is used instead:
219 int qmlRegisterInterface(const char *typeName)
222 This registers the C++ interface \a T with the QML system as \a typeName.
224 Following registration, QML can coerce objects that implement this interface
225 for assignment to appropriately typed properties.
228 The \c guests property is a list of \c Person objects. Properties that are lists
229 of objects or Qt interfaces are also declared with the Q_PROPERTY() macro, just
230 like other properties. List properties must have the type \c {QDeclarativeListProperty<T>}.
231 As with object properties, the type \a T must be registered with QML.
233 The \c guest property declaration looks like this:
235 \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 2
237 \l {Extending QML - Object and List Property Types Example} shows the complete
238 code used to create the \c BirthdayParty type.
240 \section1 Inheritance and Coercion
242 \snippet examples/declarative/cppextensions/referenceexamples/coercion/example.qml 0
244 The QML snippet shown above assigns a \c Boy object to the \c BirthdayParty's
245 \c host property, and assigns three other objects to the \c guests property.
247 QML supports C++ inheritance hierarchies and can freely coerce between known,
248 valid object types. This enables the creation of common base classes that allow
249 the assignment of specialized classes to object or list properties. In the
250 snippet shown, both the \c host and the \c guests properties retain the \c Person
251 type used in the previous section, but the assignment is valid as both the \c Boy
252 and \c Girl objects inherit from \c Person.
254 To assign to a property, the property's type must have been registered with QML.
255 Both the qmlRegisterType() and qmlRegisterInterface() template functions already
256 shown can be used to register a type with QML. Additionally, if a type that acts purely
257 as a base class that cannot be instantiated from QML needs to be
258 registered, the following function can be used:
263 int qmlRegisterType()
266 This registers the C++ type \a T with the QML system. The parameterless call to the template
267 function qmlRegisterType() does not define a mapping between the
268 C++ class and a QML element name, so the type is not instantiable from QML, but
269 it is available for type coercion.
271 Type \a T must inherit QObject, but there are no restrictions on whether it is
272 concrete or the signature of its constructor.
275 QML will automatically coerce C++ types when assigning to either an object
276 property, or to a list property. Only if coercion fails does an assignment
279 \l {Extending QML - Inheritance and Coercion Example} shows the complete
280 code used to create the \c Boy and \c Girl types.
282 \section1 Default Property
284 \snippet examples/declarative/cppextensions/referenceexamples/default/example.qml 0
286 The QML snippet shown above assigns a collection of objects to the
287 \c BirthdayParty's default property.
289 The \e {default property} is a syntactic convenience that allows a type designer to
290 specify a single property as the type's default. The default property is
291 assigned to whenever no explicit property is specified. As a convenience, it is
292 behaviorally identical to assigning to the default property explicitly by name.
294 From C++, type designers mark the default property using a Q_CLASSINFO()
299 Q_CLASSINFO("DefaultProperty", "property")
302 This marks \a property as the class's default property. \a property must be either
303 an object property, or a list property.
305 A default property is optional. A derived class inherits its base class's
306 default property, but may override it in its own declaration. \a property can
307 refer to a property declared in the class itself, or a property inherited from a
311 \l {Extending QML - Default Property Example} shows the complete code used to
312 specify a default property.
314 \section1 Grouped Properties
316 \snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml 1
318 The QML snippet shown above assigns a number of properties to the \c Boy object,
319 including four properties using the grouped property syntax.
321 Grouped properties collect similar properties together into a single named
322 block. Grouped properties can be used to present a nicer API to developers, and
323 may also simplify the implementation of common property collections across
324 different types through implementation reuse.
326 A grouped property block is implemented as a read-only object property. The
327 \c shoe property shown is declared like this:
329 \snippet examples/declarative/cppextensions/referenceexamples/grouped/person.h 1
331 The \c ShoeDescription type declares the properties available to the grouped
332 property block - in this case the \c size, \c color, \c brand and \c price properties.
334 Grouped property blocks may declared and accessed be recusively.
336 \l {Extending QML - Grouped Properties Example} shows the complete code used to
337 implement the \c shoe property grouping.
339 \section1 Attached Properties
341 \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml 1
343 The QML snippet shown above assigns a date to the \c rsvp property using the attached
346 Attached properties allow unrelated types to annotate other types with some
347 additional properties, generally for their own use. Attached properties are
348 identified through the use of the attacher type name, in the case shown
349 \c BirthdayParty, as a prefix to the property name.
351 In the example shown, \c BirthdayParty is called the attaching type, and the
352 \c Boy instance the attachee object instance.
354 For the attaching type, an attached property block is implemented as a new
355 QObject derived type, called the attachment object. The properties on the
356 attachment object are those that become available for use as the attached
359 Any QML type can become an attaching type by declaring the
360 \c qmlAttachedProperties() public function and declaring that the class has
361 QML_HAS_ATTACHED_PROPERTIES:
365 class MyType : public QObject {
371 static AttachedPropertiesType *qmlAttachedProperties(QObject *object);
374 QML_DECLARE_TYPEINFO(MyType, QML_HAS_ATTACHED_PROPERTIES)
376 This returns an attachment object, of type \a AttachedPropertiesType, for the
377 attachee \a object instance. It is customary, though not strictly required, for
378 the attachment object to be parented to \a object to prevent memory leaks.
380 \a AttachedPropertiesType must be a QObject derived type. The properties on
381 this type will be accessible through the attached properties syntax.
383 This method will be called at most once for each attachee object instance. The
384 QML engine will cache the returned instance pointer for subsequent attached
385 property accesses. Consequently the attachment object may not be deleted until
386 \a object is destroyed.
389 Conceptually, attached properties are a \e type exporting a set of additional
390 properties that can be set on \e any other object instance. Attached properties
391 cannot be limited to only attaching to a sub-set of object instances, although
392 their effect may be so limited.
394 For example, a common usage scenario is for a type to enhance the properties
395 available to its children in order to gather instance specific data. Here we
396 add a \c rsvp field to all the guests coming to a birthday party:
399 Boy { BirthdayParty.rsvp: "2009-06-01" }
402 However, as a type cannot limit the instances to which the attachment object
403 must attach, the following is also allowed, even though adding a birthday party
404 rsvp in this context will have no effect.
407 Boy { BirthdayParty.rsvp: "2009-06-01" }
411 From C++, including the attaching type implementation, the attachment object for
412 an instance can be accessed using the following method:
417 QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true);
419 This returns the attachment object attached to \a attachee by the attaching type
420 \a T. If type \a T is not a valid attaching type, this method always returns 0.
422 If \a create is true, a valid attachment object will always be returned,
423 creating it if it does not already exist. If \a create is false, the attachment
424 object will only be returned if it has previously been created.
427 \l {Extending QML - Attached Properties Example} shows the complete code used to
428 implement the rsvp attached property.
430 \section1 Memory Management and QVariant types
432 It is an element's responsibility to ensure that it does not access or return
433 pointers to invalid objects. QML makes the following guarentees:
436 \o An object assigned to a QObject (or QObject-derived) pointer property will be
437 valid at the time of assignment.
439 Following assignment, it is the responsibility of the class to subsequently guard
440 this pointer, either through a class specific method or the generic QPointer class.
442 \o An object assigned to a QVariant will be valid at the time of assignment.
444 When assigning an object to a QVariant property, QML will always use a QMetaType::QObjectStar
445 typed QVariant. It is the responsibility of the class to guard the pointer. A
446 general rule when writing a class that uses QVariant properties is to check the
447 type of the QVariant when it is set and if the type is not handled by your class,
448 reset it to an invalid variant.
450 \o An object assigned to a QObject (or QObject-derived) list property will be
451 valid at the time of assignment.
453 Following assignment, it is the responsibility of the class to subsequently guard
454 this pointer, either through a class specific method or the generic QPointer class.
457 Elements should assume that any QML assigned object can be deleted at any time, and
458 respond accordingly. If documented as such an element need not continue to work in
459 this situation, but it must not crash.
461 \section1 Signal Support
463 \snippet examples/declarative/cppextensions/referenceexamples/signal/example.qml 0
464 \snippet examples/declarative/cppextensions/referenceexamples/signal/example.qml 1
466 The QML snippet shown above associates the evaluation of a JavaScript expression
467 with the emission of a Qt signal.
469 All Qt signals on a registered class become available as special "signal
470 properties" within QML to which the user can assign a single JavaScript
471 expression. The signal property's name is a transformed version of the Qt
472 signal name: "on" is prepended, and the first letter of the signal name upper
473 cased. For example, the signal used in the example above has the following
476 \snippet examples/declarative/cppextensions/referenceexamples/signal/birthdayparty.h 0
478 In classes with multiple signals with the same name, only the final signal
479 is accessible as a signal property. Note that signals with the same name
480 but different parameters cannot be distinguished.
482 Signal parameters become accessible by name to the assigned script. An
483 unnamed parameter cannot be accessed, so care should be taken to name all the
484 signal parameters in the C++ class declaration. The intrinsic types
485 listed in \l{Adding Types}, as well registered object types are permitted as
486 signal parameter types. Using other types is not an error, but the parameter
487 value will not be accessible from script.
489 \l {Extending QML - Signal Support Example} shows the complete code used to
490 implement the onPartyStarted signal property.
492 If you want to use signals from items not created in QML, you can access their
493 signals with the \l {Connections} element.
495 Additionally, if a property is added to a C++ class, all QML elements
496 based on that C++ class will have a \e{value-changed} signal handler
497 for that property. The name of the signal handler is
498 \e{on<Property-name>Changed}, with the first letter of the property
499 name being upper case.
501 \note The QML signal handler will always be named
502 on<Property-name>Changed, regardless of the name used for the NOTIFY
503 signal in C++. We recommend using <property-name>Changed() for the
504 NOTIFY signal in C++.
506 See also \l {Importing Reusable Components}
510 Slots and methods marked Q_INVOKABLE may be called as functions in QML.
512 \snippet examples/declarative/cppextensions/referenceexamples/methods/example.qml 0
514 In this example an invitation is added via an \c {invite()} invokable method of
515 the BirthdayParty element. This function is available in QML by marking the \c {invite()}
516 method with Q_INVOKABLE in the BirthdayParty class:
518 \snippet examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h 0
520 \l {Extending QML - Methods Example} shows the complete code used to
521 implement the invite() method.
523 The \c {invite()} method is similarly available if it is declared as a slot.
525 \section1 Property Value Sources
527 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 0
528 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 1
530 The QML snippet shown above applies a property value source to the \c announcement property.
531 A property value source generates a value for a property that changes over time.
533 Property value sources are most commonly used to do animation. Rather than
534 constructing an animation object and manually setting the animation's "target"
535 property, a property value source can be assigned directly to a property of any
536 type and automatically set up this association.
538 The example shown here is rather contrived: the \c announcement property of the
539 \c BirthdayParty object is a string that is printed every time it is assigned and
540 the \c HappyBirthdaySong value source generates the lyrics of the song
543 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/birthdayparty.h 0
545 Normally, assigning an object to a string property would not be allowed. In
546 the case of a property value source, rather than assigning the object instance
547 itself, the QML engine sets up an association between the value source and
550 Property value sources are special types that derive from the
551 QDeclarativePropertyValueSource base class. This base class contains a single method,
552 QDeclarativePropertyValueSource::setTarget(), that the QML engine invokes when
553 associating the property value source with a property. The relevant part of
554 the \c HappyBirthdaySong type declaration looks like this:
556 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 0
557 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 1
558 \snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 2
560 In all other respects, property value sources are regular QML types. They must
561 be registered with the QML engine using the same macros as other types, and can
562 contain properties, signals and methods just like other types.
564 When a property value source object is assigned to a property, QML first tries
565 to assign it normally, as though it were a regular QML type. Only if this
566 assignment fails does the engine call the \l {QDeclarativePropertyValueSource::}{setTarget()} method. This allows
567 the type to also be used in contexts other than just as a value source.
569 \l {Extending QML - Property Value Source Example} shows the complete code used
570 to implement the \c HappyBirthdaySong property value source.
572 \section1 Property Binding
574 \snippet examples/declarative/cppextensions/referenceexamples/binding/example.qml 0
575 \snippet examples/declarative/cppextensions/referenceexamples/binding/example.qml 1
577 The QML snippet shown above uses a property binding to ensure the
578 \c HappyBirthdaySong's \c name property remains up to date with the \c host.
580 Property binding is a core feature of QML. In addition to assigning literal
581 values, property bindings allow the developer to assign an arbitrarily complex
582 JavaScript expression that may include dependencies on other property values.
583 Whenever the expression's result changes - through a change in one of its
584 constituent values - the expression is automatically reevaluated and
585 the new result assigned to the property.
587 All properties on custom types automatically support property binding. However,
588 for binding to work correctly, QML must be able to reliably determine when a
589 property has changed so that it knows to reevaluate any bindings that depend on
590 the property's value. QML relies on the presence of a
591 \l {Qt's Property System}{NOTIFY signal} for this determination.
593 Here is the \c host property declaration:
595 \snippet examples/declarative/cppextensions/referenceexamples/binding/birthdayparty.h 0
597 The NOTIFY attribute is followed by a signal name. It is the responsibility of
598 the class implementer to ensure that whenever the property's value changes, the
599 NOTIFY signal is emitted. The signature of the NOTIFY signal is not important to QML.
601 To prevent loops or excessive evaluation, developers should ensure that the
602 signal is only emitted whenever the property's value is actually changed. If
603 a property, or group of properties, is infrequently used it is permitted to use
604 the same NOTIFY signal for several properties. This should be done with care to
605 ensure that performance doesn't suffer.
607 To keep QML reliable, if a property does not have a NOTIFY signal, it cannot be
608 used in a binding expression. However, the property can still be assigned
609 a binding as QML does not need to monitor the property for change in that
612 Consider a custom type, \c TestElement, that has two properties, "a" and "b".
613 Property "a" does not have a NOTIFY signal, and property "b" does have a NOTIFY
627 The presence of a NOTIFY signal does incur a small overhead. There are cases
628 where a property's value is set at object construction time, and does not
629 subsequently change. The most common case of this is when a type uses
630 \l {Grouped Properties}, and the grouped property object is allocated once, and
631 only freed when the object is deleted. In these cases, the CONSTANT attribute
632 may be added to the property declaration instead of a NOTIFY signal.
634 \snippet examples/declarative/cppextensions/referenceexamples/binding/person.h 0
636 Extreme care must be taken here or applications using your type may misbehave.
637 The CONSTANT attribute should only be used for properties whose value is set,
638 and finalized, only in the class constructor. All other properties that want
639 to be used in bindings should have a NOTIFY signal instead.
641 \l {Extending QML - Binding Example} shows the BirthdayParty example updated to
642 include NOTIFY signals for use in binding.
644 \section1 Extension Objects
646 \snippet examples/declarative/cppextensions/referenceexamples/extended/example.qml 0
648 The QML snippet shown above adds a new property to an existing C++ type without
649 modifying its source code.
651 When integrating existing classes and technology into QML, their APIs will often
652 need to be tweaked to fit better into the declarative environment. Although
653 the best results are usually obtained by modifying the original classes
654 directly, if this is either not possible or is complicated by some other
655 concerns, extension objects allow limited extension possibilities without
656 direct modifications.
658 Extension objects are used to add additional properties to an existing type.
659 Extension objects can only add properties, not signals or methods. An extended
660 type definition allows the programmer to supply an additional type - known as the
661 extension type - when registering the target class whose properties are
662 transparently merged with the original target class when used from within QML.
664 An extension class is a regular QObject, with a constructor that takes a QObject
665 pointer. When needed (extension class creation is delayed until the first extended
666 property is accessed) the extension class is created and the target object is
667 passed in as the parent. When an extended property on the original is accessed,
668 the appropriate property on the extension object is used instead.
670 When an extended type is installed, one of the
672 template<typename T, typename ExtendedT>
673 int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
675 template<typename T, typename ExtendedT>
676 int qmlRegisterExtendedType()
678 functions should be used instead of the regular \c qmlRegisterType() variations.
679 The arguments are identical to the corresponding non-extension registration functions,
680 except for the ExtendedT parameter which is the type
681 of the extension object.
683 \section1 Optimization
685 Often to develop high performance elements it is helpful to know more about the
686 status of the QML engine. For example, it might be beneficial to delay
687 initializing some costly data structures until after all the properties have been
690 The QML engine defines an interface class called QDeclarativeParserStatus, which contains a
691 number of virtual methods that are invoked at various stages during component
692 instantiation. To receive these notifications, an element implementation inherits
693 QDeclarativeParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro.
698 class Example : public QObject, public QDeclarativeParserStatus
701 Q_INTERFACES(QDeclarativeParserStatus)
703 virtual void componentComplete()
705 qDebug() << "Woohoo! Now to do my costly initialization";