Definición de tipos QML desde C++
Al ampliar QML con código C++, se puede registrar una clase de C++ en el sistema de tipos de QML para permitir que dicha clase se utilice como tipo de datos dentro del código QML. Aunque se puede acceder desde QML a las propiedades, métodos y señales de cualquier clase derivada de ` QObject`, tal y como se explica en «Exposición de atributos de tipos de C++ a QML», dicha clase no puede utilizarse como tipo de datos desde QML hasta que se registre en el sistema de tipos. Además, el registro puede ofrecer otras funcionalidades, como permitir que una clase se utilice como un tipo de objeto QML instanciable desde QML, o permitir que se importe y utilice desde QML una instancia singleton de la clase.
Además, el Qt Qml módulo proporciona mecanismos para implementar características específicas de QML, como las propiedades adjuntas y las propiedades por defecto, en C++.
(Tenga en cuenta que varios de los conceptos importantes tratados en este documento se ilustran en el tutorial «Escribir extensiones de QML con C++» ).
NOTA: Todos los encabezados que declaran tipos QML deben ser accesibles sin ningún prefijo desde la ruta de inclusión del proyecto.
Para obtener más información sobre C++ y los diferentes métodos de integración con QML, consulte la página de introducción a la integración de C++ y QML.
Registro de tipos de C++ en el sistema de tipos de QML
Una clase derivada de ` QObject` puede registrarse en el sistema de tipos de QML para permitir que el tipo se utilice como tipo de datos desde el código QML.
El motor permite el registro tanto de tipos instanciables como de tipos no instanciables. El registro de un tipo instanciable permite que una clase de C++ se utilice como definición de un tipo de objeto QML, lo que permite utilizarla en declaraciones de objetos desde el código QML para crear objetos de este tipo. El registro también proporciona al motor metadatos adicionales sobre el tipo, lo que permite que el tipo (y cualquier enumeración declarada por la clase) se utilice como tipo de datos para valores de propiedades, parámetros de métodos y valores de retorno, así como para parámetros de señales que se intercambian entre QML y C++.
Al registrar un tipo no instanciable, la clase también se registra como tipo de datos de esta manera, pero el tipo no puede instanciarse como tipo de objeto QML desde QML. Esto resulta útil, por ejemplo, si un tipo tiene enumeraciones que deben exponerse a QML, pero el tipo en sí no debe ser instanciable.
Para obtener una guía rápida sobre cómo elegir el enfoque correcto para exponer tipos de C++ a QML, consulta «Elegir el método de integración correcto entre C++ y QML».
Requisitos previos
Todas las macros que se mencionan a continuación están disponibles en el archivo de cabecera ` qqmlintegration.h ` del módulo `QtQmlIntegration`.
Debes añadir el siguiente código a los archivos que las utilicen para que las macros estén disponibles:
#include <QtQmlIntegration/qqmlintegration.h>Si ya estás enlazando con el módulo ` QtQml `, puedes utilizar en su lugar el archivo de cabecera ` qqmlregistration.h `, que incluirá ` qqmlintegration.h`, de la siguiente manera:
#include <QtQml/qqmlregistration.h>Además, las declaraciones de tus clases deben encontrarse en encabezados accesibles a través de la ruta de inclusión de tu proyecto. Las declaraciones se utilizan para generar código de registro en tiempo de compilación, y dicho código debe incluir los encabezados que contienen las declaraciones.
Registro de un tipo de objeto instanciable
Cualquier clase de C++ derivada de ` QObject` puede registrarse como la definición de un tipo de objeto QML. Una vez que una clase se ha registrado en el sistema de tipos de QML, puede declararse e instanciarse como cualquier otro tipo de objeto desde el código QML. Una vez creada, una instancia de clase se puede manipular desde QML; tal y como se explica en «Exposición de atributos de tipos de C++ a QML», se puede acceder a las propiedades, métodos y señales de cualquier clase derivada de ` QObject` desde el código QML.
Para registrar una clase derivada de ` QObject` como un tipo de objeto QML instanciable, añade ` QML_ELEMENT ` o ` QML_NAMED_ELEMENT(<name>) ` a la declaración de la clase. También es necesario realizar ajustes en el sistema de compilación. Para qmake, añade ` CONFIG += qmltypes`, ` QML_IMPORT_NAME` y ` QML_IMPORT_MAJOR_VERSION ` a tu archivo de proyecto. En el caso de CMake, el archivo que contiene la clase debe formar parte de una configuración de objetivo con `qt_add_qml_module()`. Esto registrará la clase en el espacio de nombres de tipos bajo la versión principal indicada, utilizando bien el nombre de la clase o bien un nombre especificado explícitamente como nombre de tipo QML. Las versiones secundarias se derivarán de cualquier revisión asociada a propiedades, métodos o señales. La versión secundaria por defecto es 0. Puedes restringir explícitamente la disponibilidad del tipo a versiones secundarias específicas añadiendo la macro QML_ADDED_IN_VERSION() a la declaración de la clase. Los clientes pueden importar las versiones adecuadas del espacio de nombres para utilizar el tipo.
Por ejemplo, supongamos que hay una clase ` Message ` con las propiedades ` author ` y ` creationDate `:
class Message : public QObject
{
Q_OBJECT
Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged)
Q_PROPERTY(QDateTime creationDate READ creationDate WRITE setCreationDate NOTIFY creationDateChanged)
QML_ELEMENT
public:
// ...
};Este tipo se puede registrar añadiendo un espacio de nombres de tipo y un número de versión adecuados al archivo del proyecto. Por ejemplo, para que el tipo esté disponible en el espacio de nombres com.mycompany.messaging con la versión 1.0:
qt_add_qml_module(messaging
URI com.mycompany.messaging
VERSION 1.0
SOURCES
message.cpp message.h
)CONFIG += qmltypes
QML_IMPORT_NAME = com.mycompany.messaging
QML_IMPORT_MAJOR_VERSION = 1Si no se puede acceder al archivo de cabecera en el que se declara la clase desde la ruta de inclusión de tu proyecto, es posible que tengas que modificar dicha ruta para que se pueda compilar el código de registro generado.
INCLUDEPATH += com/mycompany/messagingEl tipo se puede utilizar en una declaración de objeto desde QML, y se pueden leer y escribir sus propiedades, tal y como se muestra en el ejemplo siguiente:
import com.mycompany.messaging
Message {
author: "Amelie"
creationDate: new Date()
}Registro de tipos de valor
Cualquier tipo que incluya la macro ` Q_GADGET ` puede registrarse como tipo de valor de QML. Una vez que dicho tipo se ha registrado en el sistema de tipos de QML, puede utilizarse como tipo de propiedad en el código QML. Se puede manipular una instancia de este tipo desde QML; tal y como se explica en «Exposición de atributos de tipos de C++ a QML», se puede acceder a las propiedades y métodos de cualquier tipo de valor desde el código QML.
A diferencia de los tipos de objeto, los tipos de valor requieren nombres en minúsculas. La forma recomendada de registrarlos es utilizando las macros ` QML_VALUE_TYPE ` o ` QML_ANONYMOUS `. No existe un equivalente a ` QML_ELEMENT `, ya que las clases de C++ suelen tener nombres en mayúsculas. Por lo demás, el registro es muy similar al de los tipos de objeto.
Por ejemplo, supongamos que quieres registrar un tipo de valor person que consta de dos cadenas para el nombre y los apellidos:
class Person
{
Q_GADGET
Q_PROPERTY(QString firstName READ firstName WRITE setFirstName)
Q_PROPERTY(QString lastName READ lastName WRITE setLastName)
QML_VALUE_TYPE(person)
public:
// ...
};Existen algunas limitaciones adicionales sobre lo que se puede hacer con los tipos de valor:
- Los tipos de valor no pueden ser singletons.
- Los tipos de valor deben poder construirse por defecto y mediante copia.
- El uso de « QProperty » como miembro de un tipo de valor resulta problemático. Los tipos de valor se copian, y en ese momento habría que decidir qué hacer con los enlaces existentes en « QProperty ». No se debe utilizar « QProperty » en los tipos de valor.
- Los tipos de valor no pueden proporcionar propiedades adjuntas.
- La API para definir extensiones de tipos de valor (QML_EXTENDED) no es pública y está sujeta a cambios futuros.
Tipos de valor con enumeraciones
Para exponer enumeraciones de un tipo de valor en QML es necesario seguir algunos pasos adicionales.
Los tipos de valor tienen nombres en minúsculas en QML y, por lo general, los tipos con nombres en minúsculas no son accesibles desde el código JavaScript (a menos que se especifique «pragma ValueTypeBehavior: Addressable»). Si tienes un tipo de valor en C++ con una enumeración que deseas exponer a QML, debes exponer la enumeración por separado.
Esto se puede resolver utilizando ` QML_FOREIGN_NAMESPACE`. En primer lugar, deriva de tu tipo de valor para crear un tipo de C++ independiente:
class Person
{
Q_GADGET
Q_PROPERTY(QString firstName READ firstName WRITE setFirstName)
Q_PROPERTY(QString lastName READ lastName WRITE setLastName)
QML_VALUE_TYPE(person)
public:
enum TheEnum { A, B, C };
Q_ENUM(TheEnum)
//...
};
class PersonDerived: public Person
{
Q_GADGET
};A continuación, expón el tipo derivado como un espacio de nombres externo:
namespace PersonDerivedForeign
{
Q_NAMESPACE
QML_NAMED_ELEMENT(Person)
QML_FOREIGN_NAMESPACE(PersonDerived)
}Esto genera un espacio de nombres QML llamado « Person » (en mayúsculas) con una enumeración llamada « TheEnum » y los valores « A », « B » y « C ». A continuación, puedes escribir lo siguiente en QML:
someProperty: Person.AAl mismo tiempo, puedes seguir utilizando tu tipo de valor llamado « person » (en minúsculas) exactamente igual que antes.
Registro de tipos no instanciables
En ocasiones, puede ser necesario registrar una clase derivada de ` QObject` en el sistema de tipos de QML, pero no como un tipo instanciable. Por ejemplo, este es el caso si una clase de C++:
- es un tipo de interfaz que no debe ser instanciable
- es un tipo de clase base que no necesita estar expuesto a QML
- declara alguna enumeración a la que se debe poder acceder desde QML, pero que, por lo demás, no debe ser instanciable
- es un tipo que debe proporcionarse a QML a través de una instancia singleton y no debe ser instanciable desde QML
El Qt Qml módulo proporciona varias macros para registrar tipos no instanciables:
- QML_ANONYMOUS registra un tipo de C++ que no es instanciable y al que no se puede hacer referencia desde QML. Esto permite al motor convertir cualquier tipo heredado que sea instanciable desde QML.
- QML_INTERFACE registra un tipo de interfaz Qt existente. El tipo no es instanciable desde QML y no se pueden declarar propiedades QML con él. Sin embargo, al utilizar propiedades C++ de este tipo desde QML, se realizarán las conversiones de interfaz esperadas.
- QML_UNCREATABLE(razón) en combinación con QML_ELEMENT o QML_NAMED_ELEMENT registra un tipo de C++ con nombre que no es instanciable, pero que debe ser identificable como tipo por el sistema de tipos de QML. Esto resulta útil si se debe poder acceder desde QML a las enumeraciones o propiedades asociadas de un tipo, pero el tipo en sí no debe ser instanciable. El parámetro debe ser un mensaje de error que se emitirá si se detecta un intento de crear una instancia del tipo.
- QML_SINGLETON En combinación con ` QML_ELEMENT ` o ` QML_NAMED_ELEMENT `, registra un tipo singleton que puede importarse desde QML, tal y como se explica a continuación.
Ten en cuenta que todos los tipos de C++ registrados en el sistema de tipos de QML deben derivarse de ` QObject`, incluso si no son instanciables.
Registro de objetos singleton con un tipo singleton
Un tipo singleton permite exponer propiedades, señales y métodos en un espacio de nombres sin que el cliente tenga que instanciar manualmente una instancia del objeto. Los tipos singleton de QObject, en particular, son una forma eficaz y cómoda de proporcionar funcionalidad o valores de propiedades globales.
Ten en cuenta que los tipos singleton no tienen un ` QQmlContext ` asociado, ya que se comparten entre todos los contextos de un motor. Las instancias de tipos singleton ` QObject ` son creadas y gestionadas por el ` QQmlEngine`, y se destruirán cuando se destruya el motor.
Se puede interactuar con un tipo singleton de QObject de manera similar a cualquier otro tipo de QObject o tipo instanciado, salvo que solo existirá una instancia (construida y gestionada por el motor), y a la que se debe hacer referencia por el nombre del tipo en lugar de por su identificador. Se pueden vincular las Q_PROPERTYs de los tipos singleton de QObject, y se pueden utilizar las funciones Q_INVOKABLE de las API de los módulos de QObject en expresiones de controladores de señales. Esto convierte a los tipos singleton en una forma ideal de implementar estilos o temas, y también se pueden utilizar en lugar de las importaciones de scripts «.pragma library» para almacenar el estado global o proporcionar funcionalidad global.
Una vez registrado, un tipo singleton de QObject puede importarse y utilizarse como cualquier otra instancia de QObject expuesta a QML. El siguiente ejemplo da por hecho que se ha registrado un tipo singleton de QObject en el espacio de nombres «MyThemeModule» con la versión 1.0, donde dicho QObject tiene un QColor «color» Q_PROPERTY:
import MyThemeModule 1.0 as Theme
Rectangle {
color: Theme.color // binding.
}Un QJSValue también puede exponerse como un tipo singleton; sin embargo, los clientes deben tener en cuenta que no es posible vincularse a las propiedades de dicho tipo singleton.
Consulte QML_SINGLETON para obtener más información sobre cómo implementar y registrar un nuevo tipo singleton, y cómo utilizar un tipo singleton ya existente. Consulte Singletons en QML para obtener información más detallada sobre los singletons.
Nota: Los valoresde enumeración de los tipos registrados en QML deben comenzar con mayúscula.
Propiedades finales
Las propiedades declaradas como «final» mediante el modificador « FINAL » en « Q_PROPERTY » no pueden sobrescribirse. Esto significa que el motor de QML ignora cualquier propiedad o función con el mismo nombre, ya sea declarada en QML o en C++ en tipos derivados. Se recomienda declarar las propiedades como « FINAL » siempre que sea posible, para evitar sobrescrituras accidentales. La sobrescritura de una propiedad es visible no solo en las clases derivadas, sino también para el código QML que se ejecuta en el contexto de la clase base. Sin embargo, dicho código QML suele esperar la propiedad original. Esto es una fuente frecuente de errores.
Las propiedades declaradas c FINAL o tampoco pueden sobrescribirse mediante funciones en QML ni mediante métodos « Q_INVOKABLE » en C++.
Revisiones y versiones de tipos
Muchas de las funciones de registro de tipos requieren que se especifiquen versiones para el tipo registrado. Las revisiones y versiones de tipos permiten que existan nuevas propiedades o métodos en la nueva versión, al tiempo que se mantiene la compatibilidad con las versiones anteriores.
Consideremos estos dos archivos QML:
// main.qml
import QtQuick 1.0
Item {
id: root
MyType {}
}// MyType.qml
import MyTypes 1.0
CppType {
value: root.x
}donde CppType se corresponde con la clase de C++ CppType.
Si el autor de CppType añade una propiedad root a CppType en una nueva versión de su definición de tipo, root.x ahora se resuelve en un valor diferente, ya que root es también el id del componente de nivel superior. El autor podría especificar que la nueva propiedad root esté disponible a partir de una versión menor concreta. Esto permite añadir nuevas propiedades y características a los tipos existentes sin que los programas actuales dejen de funcionar.
La etiqueta REVISION se utiliza para marcar la propiedad root como añadida en la revisión 1 del tipo. Los métodos, como los de Q_INVOKABLE, las señales y las ranuras, también pueden etiquetarse para una revisión utilizando la macro Q_REVISION:
class CppType : public BaseType
{
Q_OBJECT
Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION(1, 0))
QML_ELEMENT
signals:
Q_REVISION(1, 0) void rootChanged();
};Las revisiones indicadas de esta forma se interpretan automáticamente como versiones menores de la versión principal especificada en el archivo de proyecto. En este caso, ` root ` solo está disponible cuando se importa ` MyTypes ` versión 1.1 o superior. Las importaciones de ` MyTypes ` versión 1.0 no se ven afectadas.
Por la misma razón, los nuevos tipos introducidos en versiones posteriores deben etiquetarse con la macro « QML_ADDED_IN_VERSION ».
Esta característica del lenguaje permite realizar cambios de comportamiento sin que las aplicaciones existentes dejen de funcionar. Por consiguiente, los autores de módulos QML deben recordar siempre documentar qué ha cambiado entre versiones menores, y los usuarios de módulos QML deben comprobar que su aplicación sigue funcionando correctamente antes de implementar una instrucción de importación actualizada.
Las revisiones de una clase base de la que depende tu tipo se registran automáticamente al registrar el propio tipo. Esto resulta útil al derivar de clases base proporcionadas por otros autores, por ejemplo, al extender clases del módulo Qt Quick.
Nota: El motor QML no admite revisiones para propiedades o señales de objetos de propiedades agrupadas y adjuntas.
Registro de objetos de extensión
Al integrar clases y tecnologías existentes en QML, a menudo es necesario ajustar las API para que se adapten mejor al entorno declarativo. Aunque los mejores resultados suelen obtenerse modificando directamente las clases originales, si esto no es posible o resulta complicado por otras razones, los objetos de extensión ofrecen posibilidades limitadas de ampliación de los tipos que controlas sin necesidad de modificaciones directas. No se admite la extensión de los propios tipos de Qt.
Los objetos de extensión añaden propiedades adicionales a un tipo existente. Una definición de tipo extendido permite al programador proporcionar un tipo adicional, conocido como tipo de extensión, al registrar la clase. Sus miembros se fusionan de forma transparente con la clase de destino original cuando se utilizan desde QML. Por ejemplo:
QLineEdit {
leftMargin: 20
}La propiedad « leftMargin » es una nueva propiedad añadida a un tipo de C++ ya existente, « QLineEdit », sin modificar su código fuente.
La macro QML_EXTENDED(extensión) sirve para registrar tipos extendidos. El argumento es el nombre de otra clase que se utilizará como extensión.
También se puede utilizar ` QML_EXTENDED_NAMESPACE(namespace)` para registrar un espacio de nombres —y, en especial, las enumeraciones declaradas en su interior— como extensión de un tipo. Si el tipo que se está extendiendo es en sí mismo un espacio de nombres, hay que utilizar ` QML_NAMESPACE_EXTENDED(namespace)` en su lugar.
Una clase de extensión es una clase normal de tipo « QObject », con un constructor que toma un puntero de tipo « QObject ». Sin embargo, la creación de la clase de extensión se retrasa hasta que se accede a la primera propiedad extendida. La clase de extensión se crea y el objeto de destino se pasa como padre. Cuando se accede a la propiedad del objeto original, se utiliza en su lugar la propiedad correspondiente del objeto de extensión.
Registro de tipos externos
Puede haber tipos de C++ que no se puedan modificar para incluir las macros mencionadas anteriormente. Estos pueden ser tipos de bibliotecas de terceros o tipos que deban cumplir algún contrato que entre en contradicción con la presencia de dichas macros. No obstante, puedes exponer esos tipos a QML utilizando la macro ` QML_FOREIGN `. Para ello, crea una estructura independiente que consista íntegramente en las macros de registro, de la siguiente manera:
// Contains class Immutable3rdParty
#include <3rdpartyheader.h>
struct Foreign
{
Q_GADGET
QML_FOREIGN(Immutable3rdParty)
QML_NAMED_ELEMENT(Accessible3rdParty)
QML_ADDED_IN_VERSION(2, 4)
// QML_EXTENDED, QML_SINGLETON ...
};A partir de este código, se obtiene un tipo QML con los métodos y propiedades de `Immutable3rdParty`, así como los rasgos de QML (por ejemplo: `singleton`, `extended`) especificados en `Foreign`.
Definición de tipos y atributos específicos de QML
Proporcionar propiedades asociadas
En la sintaxis del lenguaje QML existe el concepto de propiedades adjuntas y controladores de señales adjuntos, que son atributos adicionales que se adjuntan a un objeto. Básicamente, dichos atributos son implementados y proporcionados por un tipo de adjunción, y pueden adjuntarse a un objeto de otro tipo. Esto contrasta con las propiedades normales de los objetos, que son proporcionadas por el propio tipo del objeto (o por el tipo heredado del objeto).
Por ejemplo, el archivo « Item » que se muestra a continuación utiliza propiedades adjuntas y controladores adjuntos:
import QtQuick 2.0
Item {
width: 100; height: 100
focus: true
Keys.enabled: false
Keys.onReturnPressed: console.log("Return key was pressed")
}En este caso, el objeto Item puede acceder y establecer los valores de Keys.enabled y Keys.onReturnPressed. Esto permite que el objeto Item acceda a estos atributos adicionales como una extensión de sus propios atributos existentes.
Pasos para implementar objetos adjuntos
Si tomamos como referencia el ejemplo anterior, hay varias partes implicadas:
- Existe una instancia de un tipo de objeto adjunto anónimo, con una propiedad «
enabled» y una señal «returnPressed», que se ha adjuntado al objeto « Item » para permitirle acceder a estos atributos y establecerlos. - El objeto Item es el destinatario de la vinculación, al que se ha vinculado la instancia del tipo de objeto vinculado.
- Keys es el tipo de adjunción, que proporciona al objeto adjunto un calificador con nombre, «Keys», a través del cual puede acceder a los atributos del tipo de objeto adjunto.
Cuando el motor QML procesa este código, crea una única instancia del tipo de objeto adjunto y adjunta esta instancia al objeto ` Item `, proporcionándole así acceso a los atributos ` enabled ` y ` returnPressed ` de la instancia.
Los mecanismos para proporcionar objetos adjuntos pueden implementarse desde C++ creando clases para el tipo de objeto adjunto y el tipo de adjuntador. Para el tipo de objeto adjunto, se debe proporcionar una clase derivada de ` QObject` que defina los atributos a los que podrán acceder los objetos adjuntos. Para el tipo de adjuntador, se debe proporcionar una clase derivada de ` QObject` que:
- implemente una función estática `qmlAttachedProperties()` con la siguiente firma:
static <AttachedPropertiesType> *qmlAttachedProperties(QObject *object);Este método debe devolver una instancia del tipo de objeto adjunto.
El motor QML invoca este método para adjuntar una instancia del tipo de objeto adjunto al elemento al que se adjunta, especificado por el parámetro «
object». Es habitual, aunque no estrictamente obligatorio, que la implementación de este método asigne la instancia devuelta como padre a «object» para evitar fugas de memoria.El motor invoca este método como máximo una vez por cada instancia de objeto «attachee», ya que el motor almacena en caché el puntero de la instancia devuelta para los accesos posteriores a la propiedad adjunta. Por consiguiente, el objeto adjunto no puede eliminarse hasta que se destruya el «
object» del «attachee». - Se declara como tipo de adjunto añadiendo la macro « QML_ATTACHED » (adjunto) a la declaración de la clase. El argumento es el nombre del tipo de objeto adjunto.
Implementación de objetos adjuntos: un ejemplo
Por ejemplo, tomemos el tipo « Message » descrito en un ejemplo anterior:
class Message : public QObject
{
Q_OBJECT
Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged)
Q_PROPERTY(QDateTime creationDate READ creationDate WRITE setCreationDate NOTIFY creationDateChanged)
QML_ELEMENT
public:
// ...
};Supongamos que es necesario activar una señal en un « Message » cuando se publica en un tablón de anuncios, y también realizar un seguimiento de cuándo ha caducado el mensaje en dicho tablón. Dado que no tiene sentido añadir estos atributos directamente a un « Message », ya que los atributos son más relevantes para el contexto del tablón de mensajes, podrían implementarse como atributos adjuntos a un objeto « Message » que se proporcionan a través de un calificador «MessageBoard». En términos de los conceptos descritos anteriormente, las partes implicadas aquí son:
- Una instancia de un tipo de objeto adjunto anónimo, que proporciona una señal
publishedy una propiedadexpired. Este tipo lo implementaMessageBoardAttachedTypea continuación - Un objeto `
Message`, que será el objeto adjunto - El tipo «
MessageBoard», que será el tipo de «attaching» utilizado por los objetos «Message» para acceder a los atributos adjuntos
A continuación se muestra un ejemplo de implementación. En primer lugar, debe existir un tipo de objeto adjunto con las propiedades y señales necesarias a las que pueda acceder el «attachee»:
class MessageBoardAttachedType : public QObject
{
Q_OBJECT
Q_PROPERTY(bool expired READ expired WRITE setExpired NOTIFY expiredChanged)
QML_ANONYMOUS
public:
MessageBoardAttachedType(QObject *parent);
bool expired() const;
void setExpired(bool expired);
signals:
void published();
void expiredChanged();
};A continuación, el tipo de acoplamiento, ` MessageBoard`, debe declarar un método ` qmlAttachedProperties() ` que devuelva una instancia del tipo de objeto acoplado tal y como lo implementa `MessageBoardAttachedType`. Además, ` MessageBoard ` debe declararse como tipo de acoplamiento mediante la macro ` QML_ATTACHED()`:
class MessageBoard : public QObject
{
Q_OBJECT
QML_ATTACHED(MessageBoardAttachedType)
QML_ELEMENT
public:
static MessageBoardAttachedType *qmlAttachedProperties(QObject *object)
{
return new MessageBoardAttachedType(object);
}
};Ahora, un tipo ` Message ` puede acceder a las propiedades y señales del tipo de objeto adjunto:
Message {
author: "Amelie"
creationDate: new Date()
MessageBoard.expired: creationDate < new Date("January 01, 2015 10:45:00")
MessageBoard.onPublished: console.log("Message by", author, "has been
published!")
}Además, la implementación en C++ puede acceder a la instancia del objeto adjunto que se haya vinculado a cualquier objeto llamando a la función ` qmlAttachedPropertiesObject()`.
Por ejemplo:
Message *msg = someMessageInstance();
MessageBoardAttachedType *attached =
qobject_cast<MessageBoardAttachedType*>(qmlAttachedPropertiesObject<MessageBoard>(msg));
qDebug() << "Value of MessageBoard.expired:" << attached->expired();Propagación de propiedades asociadas
QQuickAttachedPropertyPropagator puede subclasificarse para propagar propiedades asociadas desde un objeto padre a sus hijos, de forma similar a la propagación de font y palette. Admite la propagación a través de items, popups y windows.
Tipos de modificadores de propiedades
Un tipo de modificador de propiedad es un tipo especial de objeto QML. Una instancia de un tipo de modificador de propiedad afecta a una propiedad (de una instancia de objeto QML) a la que se aplica. Existen dos tipos diferentes de modificadores de propiedad:
- interceptores de escritura de valores de propiedad
- fuentes de valor de propiedad
Un interceptor de escritura de valores de propiedad se puede utilizar para filtrar o modificar los valores a medida que se escriben en las propiedades. Actualmente, el único interceptor de escritura de valores de propiedad compatible es el tipo « Behavior », proporcionado por la importación « QtQuick ».
Una fuente de valor de propiedad se puede utilizar para actualizar automáticamente el valor de una propiedad a lo largo del tiempo. Los clientes pueden definir sus propios tipos de fuentes de valor de propiedad. Los diversos tipos de animación de propiedades que proporciona la importación QtQuick son ejemplos de fuentes de valor de propiedad.
Las instancias de tipos de modificadores de propiedades se pueden crear y aplicar a una propiedad de un objeto QML mediante la sintaxis «<ModifierType> on <propertyName>», tal y como muestra el siguiente ejemplo:
import QtQuick 2.0
Item {
width: 400
height: 50
Rectangle {
width: 50
height: 50
color: "red"
NumberAnimation on x {
from: 0
to: 350
loops: Animation.Infinite
duration: 2000
}
}
}Esto se conoce comúnmente como sintaxis «on».
Los clientes pueden registrar sus propios tipos de fuentes de valor de propiedad, pero actualmente no pueden registrar interceptores de escritura de valores de propiedad.
Fuentes de valores de propiedad
Las fuentes de valores de propiedad son tipos de QML que pueden actualizar automáticamente el valor de una propiedad a lo largo del tiempo, utilizando la sintaxis « <PropertyValueSource> on <property> ». Por ejemplo, los diversos tipos de animación de propiedades que ofrece el módulo « QtQuick » son ejemplos de fuentes de valores de propiedad.
Una fuente de valor de propiedad se puede implementar en C++ creando una subclase de ` QQmlPropertyValueSource ` y proporcionando una implementación que escriba diferentes valores en una propiedad a lo largo del tiempo. Cuando la fuente de valor de propiedad se aplica a una propiedad utilizando la sintaxis ` <PropertyValueSource> on <property> ` en QML, el motor le proporciona una referencia a dicha propiedad para que el valor de la misma pueda actualizarse.
Por ejemplo, supongamos que hay una clase ` RandomNumberGenerator ` que se va a utilizar como fuente de valores de propiedad, de modo que, cuando se aplique a una propiedad de QML, actualice el valor de la propiedad con un número aleatorio diferente cada 500 milisegundos. Además, se puede proporcionar un `maxValue` a este generador de números aleatorios. Esta clase se puede implementar de la siguiente manera:
class RandomNumberGenerator : public QObject, public QQmlPropertyValueSource
{
Q_OBJECT
Q_INTERFACES(QQmlPropertyValueSource)
Q_PROPERTY(int maxValue READ maxValue WRITE setMaxValue NOTIFY maxValueChanged);
QML_ELEMENT
public:
RandomNumberGenerator(QObject *parent)
: QObject(parent), m_maxValue(100)
{
QObject::connect(&m_timer, SIGNAL(timeout()), SLOT(updateProperty()));
m_timer.start(500);
}
int maxValue() const;
void setMaxValue(int maxValue);
virtual void setTarget(const QQmlProperty &prop) { m_targetProperty = prop; }
signals:
void maxValueChanged();
private slots:
void updateProperty() {
m_targetProperty.write(QRandomGenerator::global()->bounded(m_maxValue));
}
private:
QQmlProperty m_targetProperty;
QTimer m_timer;
int m_maxValue;
};Cuando el motor de QML detecta un uso de ` RandomNumberGenerator ` como fuente de valor de propiedad, invoca a ` RandomNumberGenerator::setTarget() ` para proporcionar al tipo la propiedad a la que se ha aplicado la fuente de valor. Cuando el temporizador interno de ` RandomNumberGenerator ` se activa cada 500 milisegundos, escribirá un nuevo valor numérico en esa propiedad especificada.
Una vez que la clase RandomNumberGenerator se ha registrado en el sistema de tipos de QML, puede utilizarse desde QML como fuente de valores de propiedad. A continuación, se utiliza para cambiar el ancho de un Rectangle cada 500 milisegundos:
import QtQuick 2.0
Item {
width: 300; height: 300
Rectangle {
RandomNumberGenerator on width { maxValue: 300 }
height: 100
color: "red"
}
}En todos los demás aspectos, las fuentes de valores de propiedad son tipos QML normales que pueden tener propiedades, señales, métodos, etc., pero con la capacidad añadida de que pueden utilizarse para modificar valores de propiedad mediante la sintaxis <PropertyValueSource> on <property>.
Cuando se asigna un objeto de fuente de valor de propiedad a una propiedad, QML primero intenta asignarlo de forma normal, como si se tratara de un tipo QML habitual. Solo si esta asignación falla, el motor llama al método setTarget(). Esto permite que el tipo también se utilice en contextos distintos al de una mera fuente de valor.
Especificación de propiedades predeterminadas y propiedades padre para tipos de objetos QML
Cualquier tipo derivado de ` QObject` que esté registrado como un tipo de objeto QML instanciable puede especificar opcionalmente una propiedad por defecto para dicho tipo. Una propiedad por defecto es aquella a la que se asignan automáticamente los hijos de un objeto si no se les asigna a ninguna propiedad específica.
La propiedad por defecto se puede establecer llamando a la macro Q_CLASSINFO() para una clase con un valor específico de «DefaultProperty». Por ejemplo, la clase MessageBoard que se muestra a continuación especifica su propiedad messages como la propiedad por defecto de la clase:
class MessageBoard : public QObject
{
Q_OBJECT
Q_PROPERTY(QQmlListProperty<Message> messages READ messages)
Q_CLASSINFO("DefaultProperty", "messages")
QML_ELEMENT
public:
QQmlListProperty<Message> messages();
private:
QList<Message *> m_messages;
};Esto permite que los elementos secundarios de un objeto ` MessageBoard ` se asignen automáticamente a su propiedad ` messages ` si no se asignan a una propiedad específica. Por ejemplo:
MessageBoard {
Message { author: "Naomi" }
Message { author: "Clancy" }
}Si messages no se hubiera establecido como propiedad por defecto, cualquier objeto Message tendría que asignarse explícitamente a la propiedad messages, tal y como se muestra a continuación:
MessageBoard {
messages: [
Message { author: "Naomi" },
Message { author: "Clancy" }
]
}(Por cierto, la propiedad Item::data es su propiedad por defecto. Cualquier objeto de tipo Item añadido a esta propiedad data también se añade a la lista de Item::children, por lo que el uso de la propiedad por defecto permite declarar hijos visuales para un elemento sin asignarlos explícitamente a la propiedad children.)
Además, puedes declarar una «ParentProperty» Q_CLASSINFO() para indicar al motor QML qué propiedad debe denotar el objeto padre en la jerarquía QML. Por ejemplo, el tipo Message podría declararse de la siguiente manera:
class Message : public QObject
{
Q_OBJECT
Q_PROPERTY(QObject* board READ board BINDABLE boardBindable)
Q_PROPERTY(QString author READ author BINDABLE authorBindable)
Q_CLASSINFO("ParentProperty", "board")
QML_ELEMENT
public:
Message(QObject *parent = nullptr) : QObject(parent) { m_board = parent; }
QObject *board() const { return m_board.value(); }
QBindable<QObject *> boardBindable() { return QBindable<QObject *>(&m_board); }
QString author() const { return m_author.value(); }
QBindable<QString> authorBindable() { return QBindable<QString>(&m_author); }
private:
QProperty<QObject *> m_board;
QProperty<QString> m_author;
};Definir la propiedad «parent» permite a qmllint y a otras herramientas comprender mejor la intención de tu código y evita falsas alertas en algunos accesos a propiedades.
Definición de elementos visuales con el módulo Qt Quick
Al crear interfaces de usuario con el Qt Quick módulo, todos los objetos QML que vayan a representarse visualmente deben derivar del tipo ` Item `, ya que es el tipo base para todos los objetos visuales en Qt Quick. Este tipo ` Item ` está implementado por la clase C++ ` QQuickItem `, que proporciona el Qt Quick módulo. Por lo tanto, se debe crear una subclase de esta clase cuando sea necesario implementar un tipo visual en C++ que pueda integrarse en una interfaz de usuario basada en QML.
Consulte la documentación de QQuickItem para obtener más información. Además, el tutorial «Escritura de extensiones QML con C++» muestra cómo se puede implementar en C++ un elemento visual basado en QQuickItem e integrarlo en una interfaz de usuario basada en Qt Quick.
Recepción de notificaciones para la inicialización de objetos
Para algunos tipos de objetos QML personalizados, puede resultar útil retrasar la inicialización de determinados datos hasta que se haya creado el objeto y se hayan establecido todas sus propiedades. Por ejemplo, esto puede ser necesario si la inicialización es costosa o si no debe realizarse hasta que se hayan inicializado todos los valores de las propiedades.
El Qt Qml módulo proporciona la clase ` QQmlParserStatus ` para crear subclases con estos fines. Define varios métodos virtuales que se invocan en distintas fases durante la instanciación del componente. Para recibir estas notificaciones, una clase de C++ debe heredar de ` QQmlParserStatus ` y, además, notificarlo al metasistema de Qt mediante la macro ` Q_INTERFACES()`.
Por ejemplo:
class MyQmlType : public QObject, public QQmlParserStatus
{
Q_OBJECT
Q_INTERFACES(QQmlParserStatus)
QML_ELEMENT
public:
virtual void componentComplete()
{
// Perform some initialization here now that the object is fully created
}
};Véase también « QML Type Registration Macros » y «Descripción general: integración de QML y C++».
© 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.