Extending QML Functionalities using C++

Attached Properties

 Boy {
     name: "Leo Hodges"
     shoe { size: 10; color: "black"; brand: "Reebok"; price: 59.95 }

     BirthdayParty.rsvp: "2009-07-06"
 }

The QML snippet shown above assigns a date to the rsvp property using the attached property syntax.

Attached properties allow unrelated types to annotate other types with some additional properties, generally for their own use. Attached properties are identified through the use of the attacher type name, in the case shown BirthdayParty, as a prefix to the property name.

In the example shown, BirthdayParty is called the attaching type, and the Boy instance the attachee object instance.

For the attaching type, an attached property block is implemented as a new QObject derived type, called the attachment object. The properties on the attachment object are those that become available for use as the attached property block.

Any QML type can become an attaching type by declaring the qmlAttachedProperties() public function and declaring that the class has QML_HAS_ATTACHED_PROPERTIES:

 class MyType : public QObject {
     Q_OBJECT
 public:

     ...

     static AttachedPropertiesType *qmlAttachedProperties(QObject *object);
 };

 QML_DECLARE_TYPEINFO(MyType, QML_HAS_ATTACHED_PROPERTIES)

This returns an attachment object, of type AttachedPropertiesType, for the attachee object instance. It is customary, though not strictly required, for the attachment object to be parented to object to prevent memory leaks.

AttachedPropertiesType must be a QObject derived type. The properties on this type will be accessible through the attached properties syntax.

This method will be called at most once for each attachee object instance. The QML engine will cache the returned instance pointer for subsequent attached property accesses. Consequently the attachment object may not be deleted until object is destroyed.

Conceptually, attached properties are a type exporting a set of additional properties that can be set on any other object instance. Attached properties cannot be limited to only attaching to a sub-set of object instances, although their effect may be so limited.

For example, a common usage scenario is for a type to enhance the properties available to its children in order to gather instance specific data. Here we add a rsvp field to all the guests coming to a birthday party:

 BirthdayParty {
     Boy { BirthdayParty.rsvp: "2009-06-01" }
 }

However, as a type cannot limit the instances to which the attachment object must attach, the following is also allowed, even though adding a birthday party rsvp in this context will have no effect.

 GraduationParty {
     Boy { BirthdayParty.rsvp: "2009-06-01" }
 }

From C++, including the attaching type implementation, the attachment object for an instance can be accessed using the following method:

 template<typename T>
 QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true);

This returns the attachment object attached to attachee by the attaching type T. If type T is not a valid attaching type, this method always returns 0.

If create is true, a valid attachment object will always be returned, creating it if it does not already exist. If create is false, the attachment object will only be returned if it has previously been created.

Extending QML - Attached Properties Example shows the complete code used to implement the rsvp attached property.

 BirthdayParty {
     onPartyStarted: console.log("This party started rockin' at " + time);
 }

 signals:
     void partyStarted(const QTime &time);

 BirthdayParty {
     host: Person {
         name: "Bob Jones"
         shoeSize: 12
     }
     guests: [
         Person { name: "Leo Hodges" },
         Person { name: "Jack Smith" },
         Person { name: "Anne Brown" }
     ]

     Component.onCompleted: invite("William Green")
 }

     Q_INVOKABLE void invite(const QString &name);

 BirthdayParty {
     HappyBirthdaySong on announcement { name: "Bob Jones" }
 }

     Q_PROPERTY(QString announcement READ announcement WRITE setAnnouncement)

 class HappyBirthdaySong : public QObject, public QDeclarativePropertyValueSource
 {
     Q_OBJECT
     Q_INTERFACES(QDeclarativePropertyValueSource)
 public:
     HappyBirthdaySong(QObject *parent = 0);

     virtual void setTarget(const QDeclarativeProperty &);
 };

 BirthdayParty {
     id: theParty

     HappyBirthdaySong on announcement { name: theParty.host.name }

     host: Boy {
         name: "Bob Jones"
         shoe { size: 12; color: "white"; brand: "Nike"; price: 90.0 }
     }
 }

     Q_PROPERTY(Person *host READ host WRITE setHost NOTIFY hostChanged)

 TestElement {
     // This is OK
     a: b
 }
 TestElement {
     // Will NOT work
     b: a
 }

     Q_PROPERTY(ShoeDescription *shoe READ shoe CONSTANT)

 QLineEdit {
     leftMargin: 20
 }

 template<typename T, typename ExtendedT>
 int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

 template<typename T, typename ExtendedT>
 int qmlRegisterExtendedType()

 class Example : public QObject, public QDeclarativeParserStatus
 {
     Q_OBJECT
     Q_INTERFACES(QDeclarativeParserStatus)
 public:
     virtual void componentComplete()
     {
         qDebug() << "Woohoo!  Now to do my costly initialization";
     }
 };