Interacción con objetos QML desde C++
Todos los tipos de objetos QML son tipos derivados de ` QObject`, tanto si están implementados internamente por el motor como si han sido definidos por fuentes de terceros. Esto significa que el motor QML puede utilizar el Sistema de Objetos Meta de Qt para instanciar dinámicamente cualquier tipo de objeto QML e inspeccionar los objetos creados.
Esto resulta útil para crear objetos QML desde código C++, ya sea para mostrar un objeto QML que se pueda representar visualmente o para integrar datos de objetos QML no visuales en una aplicación C++. Una vez creado un objeto QML, se puede inspeccionar desde C++ con el fin de leer y escribir en sus propiedades, invocar métodos y recibir notificaciones de señales.
Para obtener más información sobre C++ y los diferentes métodos de integración con QML, consulta la página de descripción general de la integración entre C++ y QML.
Carga de objetos QML desde C++
Un documento QML se puede cargar con ` QQmlComponent ` o ` QQuickView`. ` QQmlComponent ` carga un documento QML como un objeto C++ que luego se puede modificar desde el código C++. ` QQuickView ` también hace esto, pero como ` QQuickView ` es una clase derivada de ` QWindow`, el objeto cargado también se representará visualmente; ` QQuickView ` se utiliza generalmente para integrar un objeto QML representable en la interfaz de usuario de una aplicación.
Por ejemplo, supongamos que hay un archivo MyItem.qml con el siguiente aspecto:
import QtQuick
Item {
width: 100; height: 100
}Este documento QML se puede cargar con QQmlComponent o QQuickView mediante el siguiente código C++. El uso de un QQmlComponent requiere llamar a QQmlComponent::create() para crear una nueva instancia del componente, mientras que un QQuickView crea automáticamente una instancia del componente, a la que se puede acceder mediante QQuickView::rootObject():
| |
Este object es la instancia del componente MyItem.qml que se ha creado. Ahora puedes modificar las propiedades del elemento utilizando QObject::setProperty() o QQmlProperty::write():
object->setProperty("width", 500);
QQmlProperty(object, "width").write(500);La diferencia entre QObject::setProperty() y QQmlProperty::write() es que esta última, además de establecer el valor de la propiedad, también eliminará el enlace. Por ejemplo, supongamos que la asignación width anterior hubiera sido un enlace a height:
width: heightSi el height del Item cambiara tras la llamada a object->setProperty("width", 500), el width se actualizaría de nuevo, ya que el enlace permanece activo. Sin embargo, si el height cambia tras la llamada a QQmlProperty(object, "width").write(500), el width no se modificará, ya que el enlace ya no existe.
Como alternativa, puedes convertir el objeto a su tipo real y llamar a los métodos con seguridad en tiempo de compilación. En este caso, el objeto base de MyItem.qml es un Item, que viene definido por la clase QQuickItem:
QQuickItem *item = qobject_cast<QQuickItem*>(object);
item->setWidth(500);También puedes conectarte a cualquier señal o llamar a métodos definidos en el componente utilizando ` QMetaObject::invokeMethod()` y ` QObject::connect()`. Consulta «Invocación de métodos QML y conexión a señales QML» más abajo para obtener más detalles.
Acceso a objetos QML a través de interfaces C++ bien definidas
La mejor forma de interactuar con QML desde C++ es definir una interfaz para ello en C++ y acceder a ella desde el propio QML. Con otros métodos, la refactorización del código QML puede provocar fácilmente que se rompa la interacción entre QML y C++. Además, esto ayuda a comprender mejor la interacción entre el código QML y el de C++, ya que el hecho de que se gestione a través de QML facilita su comprensión tanto para los usuarios como para herramientas como qmllint. Acceder a QML desde C++ dará lugar a un código QML que no se puede entender sin verificar manualmente que ningún código C++ externo esté modificando un componente QML determinado, e incluso así, el alcance del acceso podría cambiar con el tiempo, lo que convierte el uso continuado de esta estrategia en una carga de mantenimiento.
Para que QML controle la interacción, primero hay que definir una interfaz en C++:
class CppInterface : public QObject
{
Q_OBJECT
QML_ELEMENT
// ...
};Con un enfoque basado en QML, se puede interactuar con esta interfaz de dos maneras:
Singletons
Una opción consiste en registrar la interfaz como un singleton añadiendo la macro QML_SINGLETON a la interfaz, lo que la hace accesible a todos los componentes. A continuación, se puede acceder a la interfaz mediante una simple instrucción de importación:
import my.company.module
Item {
Component.onCompleted: {
CppInterface.foo();
}
}Utiliza este enfoque si necesitas que tu interfaz esté disponible en más lugares además del componente raíz, ya que limitarte a pasar un objeto requeriría transmitirlo explícitamente a otros componentes a través de una propiedad o recurrir al método lento y no recomendado de utilizar el acceso sin calificar.
Propiedades iniciales
Otra opción es marcar la interfaz como no creable mediante ` QML_UNCREATABLE ` y proporcionársela al componente QML raíz utilizando ` QQmlComponent::createWithInitialProperties()` y una propiedad obligatoria en el lado de QML.
Tu componente raíz podría tener un aspecto similar al siguiente:
import QtQuick
Item {
required property CppInterface interface
Component.onCompleted: {
interface.foo();
}
}Al marcar la propiedad como obligatoria aquí, se evita que el componente se cree sin que se haya establecido la propiedad de la interfaz.
A continuación, puedes inicializar tu componente de la misma forma que se describe en «Carga de objetos QML desde C++», salvo que debes utilizar ` createWithInitialProperties()`:
component.createWithInitialProperties(QVariantMap{{u"interface"_s, QVariant::fromValue<CppInterface *>(new CppInterface)}});Este método es el más recomendable si sabes que tu interfaz solo tiene que estar disponible para el componente raíz. Además, permite conectarse a las señales y ranuras de la interfaz con mayor facilidad desde el lado de C++.
Si ninguno de estos métodos se adapta a tus necesidades, quizá te interese investigar el uso de modelos de C++.
Acceso a objetos QML cargados por nombre de objeto
Los componentes QML son, en esencia, árboles de objetos con elementos hijos que a su vez tienen elementos hermanos y sus propios elementos hijos. Los objetos hijos de los componentes QML se pueden localizar utilizando la propiedad ` QObject::objectName ` con ` QObject::findChild()`. Por ejemplo, si el elemento raíz de MyItem.qml tuviera un elemento hijo Rectangle:
import QtQuick
Item {
width: 100; height: 100
Rectangle {
anchors.fill: parent
objectName: "rect"
}
}El elemento secundario se podría localizar así:
Ten en cuenta que un objeto puede tener varios hijos con el mismo « objectName ». Por ejemplo, « ListView » crea varias instancias de su delegado, por lo que, si su delegado se declara con un «objectName» concreto, el « ListView » tendrá varios hijos con el mismo « objectName ». En este caso, se puede utilizar « QObject::findChildren()» para encontrar todos los hijos con un « objectName » coincidente.
Advertencia: Aunque es posible acceder a objetos QML desde C++ y manipularlos, no es el enfoque recomendado, salvo con fines de prueba y creación de prototipos. Uno de los puntos fuertes de la integración entre QML y C++ es la capacidad de implementar interfaces de usuario en QML separadas de la lógica de C++ y del backend de datos, y esto falla si el lado de C++ empieza a manipular QML directamente. Este enfoque también dificulta la modificación de la interfaz de usuario de QML sin afectar a su equivalente en C++.
Acceso a los miembros de un tipo de objeto QML desde C++
Propiedades
Se puede acceder automáticamente desde C++ a cualquier propiedad declarada en un objeto QML. Supongamos un elemento QML como este:
El valor de la propiedad « someNumber » se puede establecer y leer utilizando « QQmlProperty », o « QObject::setProperty()» y « QObject::property()»:
QQmlEngine engine;
QQmlComponent component(&engine, "MyItem.qml");
QObject*object = component.create();
qDebug() << "Property value:" << QQmlProperty::read(object, "someNumber").toInt();
QQmlProperty::write(objeto, «someNumber», 5000);
qDebug() << "Property value:" << object->property("someNumber").toInt();
object->setProperty("someNumber", 100);Siempre debes utilizar QObject::setProperty(), QQmlProperty o QMetaProperty::write() para modificar el valor de una propiedad de QML, con el fin de garantizar que el motor de QML detecte el cambio en la propiedad. Por ejemplo, supongamos que tienes un tipo personalizado PushButton con una propiedad buttonText que refleja internamente el valor de una variable miembro m_buttonText. Modificar la variable miembro directamente de esta forma no es una buena idea:
//bad code
QQmlComponent component(engine, "MyButton.qml");
PushButton *button = qobject_cast<PushButton*>(component.create());
button->m_buttonText = "Click me";Dado que el valor se modifica directamente, esto elude el sistema de metaobjetos de Qt y el motor QML no detecta el cambio en la propiedad. Esto significa que los enlaces de propiedad a buttonText no se actualizarían y que no se invocarían los controladores de onButtonTextChanged.
Invocación de métodos QML
Todos los métodos QML están expuestos al sistema de metaobjetos y pueden invocarse desde C++ mediante QMetaObject::invokeMethod(). Se pueden especificar los tipos de los parámetros y del valor de retorno tras el carácter de dos puntos, tal y como se muestra en el fragmento de código siguiente. Esto puede resultar útil, por ejemplo, cuando se desea conectar una señal en C++ con una firma determinada a un método definido en QML. Si se omiten los tipos, la firma de C++ utilizará ` QVariant`.
A continuación se muestra una aplicación en C++ que llama a un método QML utilizando QMetaObject::invokeMethod():
| QML | |
| C++ | |
Fíjate en el parámetro y el tipo de retorno especificados después de los dos puntos. Puedes utilizar tipos de valor y tipos de objeto como nombres de tipo.
Si se omite el tipo o se especifica como « var » en QML, deberá pasar « QVariant » como tipo con « Q_RETURN_ARG()» y « Q_ARG()» al llamar a « QMetaObject::invokeMethod ».
Conexión a señales de QML
Todas las señales de QML están disponibles automáticamente para C++ y se pueden conectar mediante ` QObject::connect()` como cualquier señal normal de Qt C++. A su vez, cualquier señal de C++ puede ser recibida por un objeto QML mediante controladores de señales.
A continuación se muestra un componente QML con una señal denominada qmlSignal que se emite con un parámetro de tipo cadena. Esta señal se conecta a la ranura de un objeto C++ mediante QObject::connect(), de modo que el método cppSlot() se invoca cada vez que se emite qmlSignal:
|
Un tipo de objeto QML en un parámetro de señal se traduce a un puntero a la clase en 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.