Visión general - Integración de QML y C

QML está diseñado para ser fácilmente extensible mediante código C++. Las clases del módulo Qt Qml permiten cargar y manipular objetos QML desde C++, y la naturaleza de la integración del motor QML con el sistema de metaobjetos de Qt permite invocar funcionalidad C++ directamente desde QML. Esto permite el desarrollo de aplicaciones híbridas que se implementan con una mezcla de código QML, JavaScript y C++.

La integración de QML y C++ ofrece una gran variedad de oportunidades, entre las que se incluyen la posibilidad de:

• Separar el código de la interfaz de usuario del código lógico de la aplicación, implementando el primero con QML y JavaScript dentro de documentos QML, y el segundo con C++.
• utilizar e invocar algunas funciones de C++ desde QML (por ejemplo, para invocar la lógica de la aplicación, utilizar un modelo de datos implementado en C++ o llamar a algunas funciones de una biblioteca de C++ de terceros)
• Acceder a la funcionalidad en el Qt Qml o Qt Quick API de C++ (por ejemplo, para generar imágenes dinámicamente utilizando QQuickImageProvider)
• Implementar sus propios tipos de objetos QML desde C++, ya sea para utilizarlos en su propia aplicación específica o para distribuirlos a terceros.

Para proporcionar algunos datos o funcionalidades de C++ a QML, deben estar disponibles desde una clase derivada de QObject. Gracias a la integración del motor QML con el sistema de metaobjetos, las propiedades, métodos y señales de cualquier clase derivada de QObject son accesibles desde QML, como se describe en Exposición de atributos de tipos C++ a QML. Una vez que una clase de este tipo proporciona la funcionalidad necesaria, puede exponerse a QML de varias formas:

• La clase puede registrarse como un tipo QML instanciable, de modo que pueda instanciarse y utilizarse como cualquier tipo de objeto QML normal desde el código QML.
• La clase puede registrarse como tipo Singleton, de modo que pueda importarse una única instancia de la clase desde el código QML, lo que permite acceder a las propiedades, métodos y señales de la instancia desde QML.

Estos son los métodos más comunes para acceder a la funcionalidad de C++ desde el código QML. La página QML Type Registration Macros ofrece otras opciones y variantes. Además, aparte de la posibilidad de acceder a la funcionalidad de C++ desde QML, el módulo Qt Qml también ofrece formas de hacer lo contrario y manipular objetos QML desde código C++. Consulte Interacción con objetos QML desde C++ para obtener más detalles.

A menudo es deseable exponer algún estado como propiedades globales a QML. Exposing State from C++ to QML describe cómo hacerlo.

El código C++ puede integrarse en una aplicación C++ o en un módulo QML independiente, dependiendo de si se va a distribuir como aplicación independiente o como biblioteca. Un módulo QML puede contener un plugin C++ que el motor QML puede cargar dinámicamente. Esto permite que una aplicación utilice módulos QML que no estaban enlazados en el binario.

También se pueden crear plugins independientes manualmente. Consulte Proporcionar tipos y funcionalidad en un plugin de C++ para obtener más información. Esto no es recomendable.

Por último, se puede incrustar una instancia de la clase en el código QML como propiedad de contexto u objeto de contexto, lo que permite acceder a las propiedades, métodos y señales de la instancia desde QML. Deben evitarse las propiedades de contexto.

Elección del método de integración correcto entre C++ y QML

Para determinar rápidamente qué método de integración es el adecuado para su situación, puede utilizar el siguiente diagrama de flujo:

Para obtener una descripción de las macros del diagrama de flujo, consulte la documentación Definición de tipos QML desde C++.

Exposición de atributos de clases C++ a QML

QML puede ampliarse fácilmente desde C++ gracias a la integración del motor QML con el sistema de metaobjetos Qt. Esta integración permite que las propiedades, métodos y señales de cualquier clase derivada de QObject sean accesibles desde QML: las propiedades pueden leerse y modificarse, los métodos pueden invocarse desde expresiones JavaScript y los manejadores de señales se crean automáticamente para las señales según sea necesario. Además, los valores de enumeración de una clase derivada de QObject son accesibles desde QML.

Consulte Exposición de atributos de tipos C++ a QML para obtener más información.

Definición de tipos QML desde C

Los tipos QML pueden definirse en C++ y registrarse en el sistema de tipos QML. Esto permite instanciar una clase C++ como tipo de objeto QML, lo que permite implementar tipos de objeto personalizados en C++ e integrarlos en el código QML existente. Una clase C++ también puede registrarse para otros fines: por ejemplo, podría registrarse como tipo Singleton para permitir que el código QML importe una única instancia de clase, o podría registrarse para permitir que los valores de enumeración de una clase no instanciable sean accesibles desde QML.

Además, el módulo Qt Qml proporciona mecanismos para definir tipos QML que se integran con conceptos QML como propiedades adjuntas y propiedades predeterminadas.

Para obtener más información sobre el registro y la creación de tipos QML personalizados desde C++, consulte la documentación Definición de tipos QML desde C++.

Incrustación de objetos C++ en QML con propiedades de contexto

Los objetos y valores C++ pueden incrustarse directamente en el contexto (o ámbito) de los objetos QML cargados mediante propiedades de contexto y objetos de contexto. Esto se consigue mediante la clase QQmlContext proporcionada por el módulo Qt Qml que expone datos al contexto de un componente QML, lo que permite inyectar datos de C++ en QML.

Para obtener más información, consulte Incrustación de objetos C++ en QML con propiedades de contexto.

Interacción con objetos QML desde C++

Los tipos de objeto QML pueden instanciarse desde C++ e inspeccionarse para acceder a sus propiedades, invocar sus métodos y recibir sus notificaciones de señales. Esto es posible gracias a que todos los tipos de objeto QML se implementan utilizando clases derivadas de QObject, lo que permite al motor QML cargar e introspeccionar objetos de forma dinámica a través del sistema de metaobjetos Qt.

Para obtener más información sobre el acceso a objetos QML desde C++, consulte la documentación Interacción con objetos QML desde C++ y la sección Exposición de datos de C++ a QML de la página Mejores prácticas.

Conversión de tipos de datos entre QML y C++

Cuando se intercambian valores de datos entre QML y C++, el motor QML los convierte para que tengan los tipos de datos correctos según convenga para su uso desde QML o C++, siempre que el motor conozca los tipos de datos implicados.

Consulte Conversión de tipos de datos entre QML y C++ para obtener información sobre los tipos incorporados admitidos por el motor y cómo se convierten estos tipos para su uso cuando se intercambian entre QML y C++.