En esta página

Cómo escribir extensiones avanzadas de QML con C++

Proyecto base «BirthdayParty»

extending-qml-advanced/advanced1-Base-project

Este tutorial utiliza el ejemplo de una fiesta de cumpleaños para mostrar algunas de las características de QML. El código de las distintas funciones que se explican a continuación se basa en este proyecto de fiesta de cumpleaños y recurre a parte del material del primer tutorial sobre extensiones de QML. A continuación, este sencillo ejemplo se amplía para ilustrar las distintas extensiones de QML que se explican más adelante. El código completo de cada nueva extensión se puede encontrar en los tutoriales, en la ubicación especificada debajo del título de cada sección, o siguiendo el enlace al código que aparece al final de esta página.

El proyecto base define la clase « Person » y la clase « BirthdayParty », que representan a los asistentes y a la propia fiesta, respectivamente.

class Person : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged FINAL)
    Q_PROPERTY(int shoeSize READ shoeSize WRITE setShoeSize NOTIFY shoeSizeChanged FINAL)
    QML_ELEMENT
    ...
    QString m_name;
    int m_shoeSize = 0;
};

class BirthdayParty : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Person *host READ host WRITE setHost NOTIFY hostChanged FINAL)
    Q_PROPERTY(QQmlListProperty<Person> guests READ guests NOTIFY guestsChanged FINAL)
    QML_ELEMENT
    ...
    Person *m_host = nullptr;
    QList<Person *> m_guests;
};

Toda la información sobre la fiesta se puede almacenar en el archivo QML correspondiente.

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

El archivo main.cpp crea una sencilla aplicación de shell que muestra de quién es el cumpleaños y quién está invitado a su fiesta.

    QQmlEngine engine;
    QQmlComponent component(&engine);
    component.loadFromModule("People", "Main");
    std::unique_ptr<BirthdayParty> party{ qobject_cast<BirthdayParty *>(component.create()) };

La aplicación muestra el siguiente resumen de la fiesta.

"Bob Jones" is having a birthday!
They are inviting:
    "Leo Hodges"
    "Jack Smith"
    "Anne Brown"

En las siguientes secciones se explica cómo añadir compatibilidad con los asistentes de « Boy » y « Girl » en lugar de solo « Person » mediante la herencia y la coerción, cómo utilizar propiedades por defecto para asignar implícitamente a los asistentes a la fiesta como invitados, cómo asignar propiedades por grupos en lugar de una por una, cómo utilizar objetos adjuntos para realizar un seguimiento de las respuestas de los invitados, cómo utilizar una fuente de valores de propiedad para mostrar la letra de la canción de «Cumpleaños feliz» a lo largo del tiempo, y cómo exponer objetos de terceros a QML.

Herencia y coerción

extending-qml-advanced/advanced2-Inheritance-and-coercion

En este momento, cada asistente se modela como una persona. Esto resulta un poco demasiado genérico y estaría bien poder saber más sobre los asistentes. Al especializarlos en chicos y chicas, ya podemos hacernos una idea más clara de quiénes van a venir.

Para ello, se introducen las clases « Boy » y « Girl », ambas heredadas de « Person ».

class Boy : public Person
{
    Q_OBJECT
    QML_ELEMENT
public:
    using Person::Person;
};

class Girl : public Person
{
    Q_OBJECT
    QML_ELEMENT
public:
    using Person::Person;
};

La clase ` Person ` permanece inalterada y las clases de C++ ` Boy ` y ` Girl ` son extensiones triviales de la misma. Los tipos y sus nombres en QML se registran en el motor QML mediante ` QML_ELEMENT`.

Ten en cuenta que las propiedades ` host ` y ` guests ` de ` BirthdayParty ` siguen aceptando instancias de ` Person`.

class BirthdayParty : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Person *host READ host WRITE setHost NOTIFY hostChanged FINAL)
    Q_PROPERTY(QQmlListProperty<Person> guests READ guests NOTIFY guestsChanged FINAL)
    QML_ELEMENT
    ...
};

La implementación de la clase Person en sí no ha sufrido cambios. Sin embargo, dado que la clase Person se ha reutilizado como base común para Boy y Girl, ya no debería ser posible instanciar Person directamente desde QML. En su lugar, debería instanciarse explícitamente Boy o Girl.

class Person : public QObject
{
    ...
    QML_ELEMENT
    QML_UNCREATABLE("Person is an abstract base class.")
    ...
};

Aunque queremos impedir la instanciación de Person desde QML, sigue siendo necesario registrarlo en el motor de QML para que pueda utilizarse como tipo de propiedad y para que otros tipos puedan ser convertidos a él. Esto es lo que hace la macro QML_UNCREATABLE. Dado que los tres tipos — Person, Boy y Girl — se han registrado en el sistema QML, al asignarlos, QML convierte automáticamente (y de forma segura en cuanto al tipo) los objetos de Boy y Girl en un Person.

Con estos cambios, ahora podemos especificar la fiesta de cumpleaños con la información adicional sobre los asistentes de la siguiente manera.

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

Propiedades por defecto

extending-qml-advanced/advanced3-Default-properties

Actualmente, en el archivo QML, cada propiedad se asigna de forma explícita. Por ejemplo, a la propiedad host se le asigna un Boy y a la propiedad guests se le asigna una lista de Boy o Girl. Esto es sencillo, pero se puede simplificar un poco más para este caso de uso concreto. En lugar de asignar la propiedad guests de forma explícita, podemos añadir los objetos Boy y Girl directamente dentro de la fiesta y hacer que se asignen a guests de forma implícita. Tiene sentido que todos los asistentes que especifiquemos, y que no sean el anfitrión, sean invitados. Este cambio es puramente sintáctico, pero puede aportar una sensación más natural en muchas situaciones.

La propiedad guests puede designarse como la propiedad por defecto de BirthdayParty. Esto significa que cada objeto creado dentro de un BirthdayParty se añade implícitamente a la propiedad por defecto guests. El código QML resultante tiene este aspecto.

BirthdayParty {
    host: Boy {
        name: "Bob Jones"
        shoeSize: 12
    }

    Boy { name: "Leo Hodges" }
    Boy { name: "Jack Smith" }
    Girl { name: "Anne Brown" }
}

El único cambio necesario para habilitar este comportamiento es añadir la anotación de información de clase ` DefaultProperty ` a ` BirthdayParty ` para designar ` guests ` como su propiedad por defecto.

class BirthdayParty : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Person *host READ host WRITE setHost NOTIFY hostChanged FINAL)
    Q_PROPERTY(QQmlListProperty<Person> guests READ guests NOTIFY guestsChanged FINAL)
    Q_CLASSINFO("DefaultProperty", "guests")
    QML_ELEMENT
    ...
};

Es posible que ya estés familiarizado con este mecanismo. La propiedad por defecto para todos los descendientes de ` Item ` en QML es la propiedad ` data `. Todos los elementos que no se añadan explícitamente a una propiedad de un ` Item ` se añadirán a ` data`. Esto aclara la estructura y reduce el ruido innecesario en el código.

Propiedades agrupadas

extending-qml-advanced/advanced4-Grouped-properties

Se necesita más información sobre los zapatos de los invitados. Además de su talla, también queremos almacenar el color, la marca y el precio de los zapatos. Esta información se almacena en una clase ` ShoeDescription `.

class ShoeDescription : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int size READ size WRITE setSize NOTIFY shoeChanged FINAL)
    Q_PROPERTY(QColor color READ color WRITE setColor NOTIFY shoeChanged FINAL)
    Q_PROPERTY(QString brand READ brand WRITE setBrand NOTIFY shoeChanged FINAL)
    Q_PROPERTY(qreal price READ price WRITE setPrice NOTIFY shoeChanged FINAL)
    ...
};

Ahora cada persona tiene dos propiedades: una de « name » y otra de «descripción del zapato» shoe.

class Person : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged FINAL)
    Q_PROPERTY(ShoeDescription *shoe READ shoe WRITE setShoe NOTIFY shoeChanged FINAL)
    ...
};

Especificar los valores para cada elemento de la descripción del zapato funciona, pero resulta un poco repetitivo.

    Girl {
        name: "Anne Brown"
        shoe.size: 7
        shoe.color: "red"
        shoe.brand: "Job Macobs"
        shoe.price: 99.99
    }

Las propiedades agrupadas ofrecen una forma más elegante de asignar estas propiedades. En lugar de asignar los valores a cada propiedad una por una, los valores individuales se pueden pasar como un grupo a la propiedad ` shoe `, lo que hace que el código sea más legible. No es necesario realizar ningún cambio para habilitar esta función, ya que está disponible de forma predeterminada en todo QML.

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

Propiedades adjuntas

extending-qml-advanced/advanced5-Attached-properties

Ha llegado el momento de que el anfitrión envíe las invitaciones. Para llevar un registro de qué invitados han respondido a la invitación y cuándo, necesitamos un lugar donde almacenar esa información. Almacenarla en el propio objeto ` BirthdayParty ` no sería lo más adecuado. Una forma mejor sería almacenar las respuestas como objetos adjuntos al objeto `party`.

En primer lugar, declaramos la clase ` BirthdayPartyAttached `, que contiene las respuestas de los invitados.

class BirthdayPartyAttached : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QDate rsvp READ rsvp WRITE setRsvp NOTIFY rsvpChanged FINAL)
    QML_ANONYMOUS
    ...
};

A continuación, la vinculamos a la clase ` BirthdayParty ` y definimos ` qmlAttachedProperties() ` para que devuelva el objeto vinculado.

class BirthdayParty : public QObject
{
    ...
    QML_ATTACHED(BirthdayPartyAttached)
    ...
    static BirthdayPartyAttached *qmlAttachedProperties(QObject *);

};

Ahora, los objetos adjuntos se pueden utilizar en QML para almacenar la información de confirmación de asistencia de los invitados.

BirthdayParty {
    Boy {
        name: "Robert Campbell"
        BirthdayParty.rsvp: Date.fromLocaleString(Qt.locale(), "2023-03-01", "yyyy-MM-dd")
    }

    Boy {
        name: "Leo Hodges"
        shoe { size: 10; color: "black"; brand: "Reebok"; price: 59.95 }
        BirthdayParty.rsvp: Date.fromLocaleString(Qt.locale(), "2023-03-03", "yyyy-MM-dd")
    }

    host: Boy {
        name: "Jack Smith"
        shoe { size: 8; color: "blue"; brand: "Puma"; price: 19.95 }
    }
}

Por último, se puede acceder a la información de la siguiente manera.

            QDate rsvpDate;
            QObject *attached = qmlAttachedPropertiesObject<BirthdayParty>(guest, false);

            if (attached)
                rsvpDate = attached->property("rsvp").toDate();

El programa muestra el siguiente resumen de la fiesta que se celebrará.

"Jack Smith" is having a birthday!
He is inviting:
    "Robert Campbell" RSVP date: "Wed Mar 1 2023"
    "Leo Hodges" RSVP date: "Mon Mar 6 2023"

Fuente de valor de propiedad

extending-qml-advanced/advanced6-Property-value-source

Durante la fiesta, los invitados tienen que cantar para el anfitrión. Sería útil que el programa pudiera mostrar la letra adaptada a la ocasión para ayudar a los invitados. Para ello, se utiliza una fuente de valores de propiedad para generar las estrofas de la canción a lo largo del tiempo.

class HappyBirthdaySong : public QObject, public QQmlPropertyValueSource
{
    Q_OBJECT
    Q_INTERFACES(QQmlPropertyValueSource)
    ...
    void setTarget(const QQmlProperty &) override;

};

Se añade la clase HappyBirthdaySong como fuente de valor. Debe heredar de QQmlPropertyValueSource e implementar la interfaz QQmlPropertyValueSource con la macro Q_INTERFACES. La función setTarget() se utiliza para definir sobre qué propiedad actúa esta fuente. En este caso, la fuente de valores escribe en la propiedad announcement del BirthdayParty para mostrar la letra a lo largo del tiempo. Cuenta con un temporizador interno que hace que la propiedad announcement del se establezca repetidamente en la siguiente línea de la letra.

En QML, se crea una instancia de « HappyBirthdaySong » dentro de « BirthdayParty ». La palabra clave « on » de su firma se utiliza para especificar la propiedad a la que se dirige la fuente de valor, en este caso « announcement ». La propiedad « name » del objeto « HappyBirthdaySong » también está vinculada al nombre del anfitrión de la fiesta.

BirthdayParty {
    id: party
    HappyBirthdaySong on announcement {
        name: party.host.name
    }
    ...
}

El programa muestra la hora a la que comenzó la fiesta utilizando la señal « partyStarted » y, a continuación, muestra una y otra vez los siguientes versos de «Feliz cumpleaños».

Happy birthday to you,
Happy birthday to you,
Happy birthday dear Bob Jones,
Happy birthday to you!

Integración de objetos externos

extending-qml-advanced/advanced7-Foreign-objects-integration

En lugar de limitarse a mostrar la letra en la consola, a los asistentes les gustaría utilizar una pantalla más sofisticada con soporte para colores. Les gustaría integrarla en el proyecto, pero actualmente no es posible configurar la pantalla desde QML porque procede de una biblioteca de terceros. Para resolverlo, es necesario exponer los tipos necesarios al motor QML, de modo que sus propiedades puedan modificarse directamente en QML.

La pantalla se puede controlar mediante la clase ThirdPartyDisplay. Cuenta con propiedades para definir el contenido y los colores de primer plano y de fondo del texto que se va a mostrar.

class Q_DECL_EXPORT ThirdPartyDisplay : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString content READ content WRITE setContent NOTIFY contentChanged FINAL)
    Q_PROPERTY(QColor foregroundColor READ foregroundColor WRITE setForegroundColor NOTIFY colorsChanged FINAL)
    Q_PROPERTY(QColor backgroundColor READ backgroundColor WRITE setBackgroundColor NOTIFY colorsChanged FINAL)
    ...
};

Para exponer este tipo a QML, podemos registrarlo en el motor mediante ` QML_ELEMENT`. Sin embargo, dado que no se puede modificar la clase, no basta con añadirle simplemente ` QML_ELEMENT `. Para registrar el tipo en el motor, es necesario registrarlo desde el exterior. Para ello sirve QML_FOREIGN. Cuando se utiliza en un tipo junto con otras macros de QML, estas últimas no se aplican al tipo en el que residen, sino al tipo externo designado por QML_FOREIGN.

class ForeignDisplay : public QObject
{
    Q_OBJECT
    QML_NAMED_ELEMENT(ThirdPartyDisplay)
    QML_FOREIGN(ThirdPartyDisplay)
};

De esta forma, BirthdayParty cuenta ahora con una nueva propiedad con el texto «display».

class BirthdayParty : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Person *host READ host WRITE setHost NOTIFY hostChanged FINAL)
    Q_PROPERTY(QQmlListProperty<Person> guests READ guests NOTIFY guestsChanged FINAL)
    Q_PROPERTY(QString announcement READ announcement WRITE setAnnouncement NOTIFY announcementChanged FINAL)
    Q_PROPERTY(ThirdPartyDisplay *display READ display WRITE setDisplay NOTIFY displayChanged FINAL)
    ...
};

Además, en QML, los colores del texto de la tercera pantalla, la más elegante, se pueden establecer de forma explícita.

BirthdayParty {
    display: ThirdPartyDisplay {
        foregroundColor: "black"
        backgroundColor: "white"
    }
    ...
}

Al establecer la propiedad ` announcement ` de `BirthdayParty`, ahora se envía el mensaje a la pantalla elegante en lugar de mostrarlo directamente.

void BirthdayParty::setAnnouncement(const QString &announcement)
{
    if (m_announcement != announcement) {
        m_announcement = announcement;
        emit announcementChanged();
    }
    m_display->setContent(announcement);
}

La salida tiene entonces este aspecto, repitiéndose una y otra vez de forma similar a la sección anterior.

[Fancy ThirdPartyDisplay] Happy birthday to you,
[Fancy ThirdPartyDisplay] Happy birthday to you,
[Fancy ThirdPartyDisplay] Happy birthday dear Bob Jones,
[Fancy ThirdPartyDisplay] Happy birthday to you!

Véase también Especificación de propiedades predeterminadas y de superclase para tipos de objetos QML, Propiedades agrupadas, Proporcionar propiedades adjuntas, Fuentes de valores de propiedades y Registro de tipos externos.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.