Extending QML - Object and List Property Types Example

Exporting C++ Properties.

This example builds on:

The Object and List Property Types example shows how to add object and list properties in QML. This example adds a BirthdayParty type that specifies a birthday party, consisting of a celebrant and a list of guests. People are specified using the People QML type built in the previous example.

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

Declare the BirthdayParty

The BirthdayParty class is declared like this:

class BirthdayParty : public QObject
    Q_PROPERTY(Person *host READ host WRITE setHost)
    Q_PROPERTY(QQmlListProperty<Person> guests READ guests)
    BirthdayParty(QObject *parent = 0);

    Person *host() const;
    void setHost(Person *);

    QQmlListProperty<Person> guests();
    void appendGuest(Person*);
    int guestCount() const;
    Person *guest(int) const;
    void clearGuests();

    static void appendGuest(QQmlListProperty<Person>*, Person*);
    static int guestCount(QQmlListProperty<Person>*);
    static Person* guest(QQmlListProperty<Person>*, int);
    static void clearGuests(QQmlListProperty<Person>*);

    Person *m_host;
    QVector<Person *> m_guests;

The class contains a member to store the celebrant object, and also a QList<Person *> member.

In QML, the type of a list properties - and the guests property is a list of people - are all of type QQmlListProperty<T>. QQmlListProperty is simple value type that contains a set of function pointers. QML calls these function pointers whenever it needs to read from, write to or otherwise interact with the list. In addition to concrete lists like the people list used in this example, the use of QQmlListProperty allows for "virtual lists" and other advanced scenarios.

Define the BirthdayParty

The implementation of BirthdayParty property accessors is straight forward.

Person *BirthdayParty::host() const
    return m_host;

void BirthdayParty::setHost(Person *c)
    m_host = c;

QQmlListProperty<Person> BirthdayParty::guests()
    return QQmlListProperty<Person>(this, this,

void BirthdayParty::appendGuest(Person* p) {

int BirthdayParty::guestCount() const
    return m_guests.count();

Person *BirthdayParty::guest(int index) const
    return m_guests.at(index);

void BirthdayParty::clearGuests() {

Running the Example

The main.cpp file in the example includes a simple shell application that loads and runs the QML snippet shown at the beginning of this page.


Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
create apps
create games
cross platform
native performance
3rd party services
game network
level editor
easiest to learn
biggest time saving
best support