Exposer l'état de C++ à QML

Il est souvent souhaitable d'exposer certaines propriétés du C++ à tous les éléments QML d'un composant particulier, à tous les éléments QML d'un module, ou même à tous les éléments QML en général. Vous pouvez le faire en introduisant des singletons ou en ajoutant des propriétés aux objets racines des composants sélectionnés.

Utilisation des singletons

Si vous souhaitez exposer un certain nombre de propriétés globales à tous les éléments d'un module ou à l'ensemble des éléments, vous pouvez définir un singleton en C++. Pour ce faire, ajoutez les macros QML_ELEMENT ou QML_NAMED_ELEMENT et la macro QML_SINGLETON à une classe contenant les propriétés que vous souhaitez exposer en tant que déclarations 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;
};

Vous pouvez désormais accéder à la propriété thing du singleton à partir de tout code QML qui importe ce module :

import QtQml

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

Si vous avez placé vos fichiers QML dans le même répertoire que le module (ce qui est fortement recommandé), le singleton est disponible à partir de l'importation implicite dans votre module. Vous n'avez pas besoin d'importer quoi que ce soit explicitement. Si ce n'est pas le cas, ou si vous souhaitez accéder à la propriété thing depuis d'autres modules, vous devez importer le module auquel appartient le singleton.

Pour définir la valeur de la propriété à partir de C++, vous devrez peut-être récupérer l'instance du singleton. Pour ce faire, vous pouvez utiliser QQmlEngine::singletonInstance. La meilleure façon de procéder est de donner le nom du module et du type en tant que paramètres :

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

Utilisation des propriétés d'objets

Si vous souhaitez exposer certaines propriétés aux seuls éléments QML d'un composant spécifique, vous pouvez les ajouter en tant que propriétés ordinaires à l'objet racine du composant. Afin de vous assurer qu'elles sont effectivement définies dans tous les cas, vous pouvez en faire des propriétés obligatoires. Vous pouvez écrire votre composant QML comme suit :

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."
    }
}

Nous utilisons un ID pour l'élément racine du composant et référençons la propriété par ID et nom à partir de tous les objets internes. Pour que l'ID de l'élément racine soit accessible en toute sécurité à tous les composants imbriqués, nous utilisons ComponentBehavior.

Ensuite, en C++, lorsque vous créez un objet à partir d'un tel composant, vous devez vous assurer d'appeler QQmlComponent::createWithInitialProperties, QQmlApplicationEngine::setInitialProperties, ou QQuickView::setInitialProperties afin d'initialiser les propriétés. En voici un exemple :

    QQmlEngine engine;

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

Cela suppose que l'URI de votre module est MyModule et que le module est disponible dans le chemin d'importation de QML.