Exposer l'état depuis le C++ vers le QML

Il est souvent souhaitable d'exposer certaines propriétés depuis le C++ à tous les éléments QML d'un composant particulier, à tous les éléments QML d'un module, voire à tous les éléments QML en général. Vous pouvez y parvenir en introduisant des singletons ou en ajoutant des propriétés aux objets racines de certains composants.

Utilisation des singletons

Si vous souhaitez exposer un certain nombre de propriétés globales à tous les éléments d'un module ou à tous les éléments en général, vous pouvez définir un singleton en C++. Pour ce faire, ajoutez les macros « QML_ELEMENT » ou « QML_NAMED_ELEMENT » ainsi que la macro « QML_SINGLETON » à une classe contenant les propriétés que vous souhaitez exposer sous forme de 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 depuis n’importe quel 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 accessible via l’importation implicite au sein de votre module. Vous n’avez pas besoin d’importer quoi que ce soit explicitement. Dans le cas contraire, ou si vous souhaitez accéder à la propriété `thing` depuis d’autres modules, vous devez importer le module auquel appartient le singleton.

Afin de définir la valeur de la propriété depuis C++, vous devrez peut-être récupérer l’instance du singleton. Pour cela, vous pouvez utiliser ` QQmlEngine::singletonInstance`. La méthode recommandée consiste à passer un nom de module et un nom de type en paramètres :

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

Utilisation des propriétés d’objet

Si vous souhaitez exposer certaines propriétés uniquement aux éléments QML d’un composant spécifique, vous pouvez les ajouter en tant que propriétés classiques à l’objet racine du composant. Afin de vous assurer qu’elles sont bien définies dans tous les cas, vous pouvez les définir comme propriétés obligatoires. Vous pourriez é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 identifiant pour l’élément racine du composant et référençons la propriété par son identifiant et son nom depuis n’importe quel objet interne. Afin de rendre l’identifiant de l’élément racine 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 veiller à appeler les méthodes ` QQmlComponent::createWithInitialProperties`, ` QQmlApplicationEngine::setInitialProperties` ou ` QQuickView::setInitialProperties ` afin d’initialiser les propriétés. Par exemple :

    QQmlEngine engine;

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

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