Exposición de estados de C++ a QML

A menudo es deseable exponer algunas propiedades de C++ a todos los elementos QML de un componente en particular, a todos los elementos QML de un módulo, o incluso a todos los elementos QML en general. Puede hacerlo introduciendo singletons o añadiendo propiedades a los objetos raíz de determinados componentes.

Uso de singletons

Si desea exponer una serie de propiedades globales a todos los elementos de un módulo o a todos los elementos en general, puede definir un singleton en C++. Para ello, añada las macros QML_ELEMENT o QML_NAMED_ELEMENT y la macro QML_SINGLETON a una clase que contenga las propiedades que desea exponer como declaraciones Q_PROPERTY:

// Singleton.h
class Singleton : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int thing READ thing WRITE setThing NOTIFY thingChanged FINAL)
    QML_ELEMENT
    QML_SINGLETON

public:
    Singleton(QObject *parent = nullptr) : QObject(parent) {}

    int thing() const { return m_value; }
    void setThing(int v)
    {
        if (v != m_value) {
            m_value = v;
            emit thingChanged();
        }
    }

signals:
    void thingChanged();

private:
    int m_value = 12;
};

Ahora puedes acceder a la propiedad thing del singleton desde cualquier código QML que importe este módulo:

import QtQml

QtObject {
    objectName: "The thing is " + Singleton.thing
}

Si has colocado tus archivos QML en el mismo directorio que el módulo (lo cual es muy recomendable), el singleton estará disponible desde la importación implícita dentro de tu módulo. No necesitas importar nada explícitamente. En caso contrario, o si quieres acceder a la propiedad thing desde otros módulos, sí necesitas importar el módulo al que pertenece el singleton.

Para establecer el valor de la propiedad desde C++, puede que necesites recuperar la instancia del singleton. Para ello puede utilizar QQmlEngine::singletonInstance. La forma preferida de hacerlo es dando un módulo y un nombre de tipo como parámetros:

    Singleton *singleton
            = engine->singletonInstance<Singleton *>("MyModule", "Singleton");
    singleton->setThing(77);

Uso de propiedades de objeto

Si desea exponer algunas propiedades sólo a los elementos QML de un componente específico, puede añadirlas como propiedades normales al objeto raíz del componente. Para asegurarse de que se establecen en todos los casos, puede convertirlas en propiedades obligatorias. Puede escribir su componente QML de la siguiente manera:

pragma ComponentBehavior: Bound

import QtQuick

Window {
    id: root
    visible: true

    required property int thing

    Text {
        anchors.fill: parent
        text: "The thing is " + root.thing
    }

    component Inner: QtObject {
        objectName: "I can see " + root.thing + " because I'm bound."
    }
}

Utilizamos un ID para el elemento raíz del componente y referenciamos la propiedad por ID y nombre desde cualquier objeto interno. Para que el ID del elemento raíz esté disponible de forma segura para cualquier componente anidado, utilizamos ComponentBehavior.

Luego, en C++, cuando se crea un objeto a partir de un componente de este tipo, hay que asegurarse de llamar a QQmlComponent::createWithInitialProperties, QQmlApplicationEngine::setInitialProperties, o QQuickView::setInitialProperties para inicializar las propiedades. Por ejemplo:

    QQmlEngine engine;

    QQmlComponent component(&engine, "MyModule", "RequiredProperties");
    QScopedPointer<QObject> o(component.createWithInitialProperties({
            {"thing", 11}
    }));

Suponiendo que el URI del módulo sea MyModule y que el módulo esté disponible en la ruta de importación de QML.