Types attachés en QML

Les propriétés et signaux attachés constituent un mécanisme permettant d'annoter les objets avec des propriétés ou signaux supplémentaires qui ne font pas partie de leur type de base. Les propriétés attachées sont accessibles via une syntaxe d'espace de noms qui identifie le type fournissant les propriétés attachées.

Vue d'ensemble

Certains types possèdent des propriétés ou des signaux qui peuvent être attachés à d'autres objets, offrant ainsi des fonctionnalités supplémentaires sans nécessiter d'héritage. On accède à une propriété ou à un signal attaché en préfixant le nom de la propriété ou du signal par le nom du type qui l'attache.

Par exemple, le type ListView possède une propriété attachée appelée isCurrentItem à laquelle on peut accéder sur n'importe quel élément du délégué de ListView:

ListView {
    width: 240
    height: 320
    model: 3
    delegate: Rectangle {
        width: 100
        height: 30
        color: ListView.isCurrentItem ? "red" : "yellow"
    }
}

Ici, ListView.isCurrentItem est une propriété attachée qui est mise à la disposition de chaque élément du délégué par le type ListView.

Propriétés attachées

Les propriétés attachées permettent d'ajouter des propriétés à des objets qui sont par ailleurs définis par un type de base. Les valeurs des propriétés sont stockées à l'extérieur de l'objet et accessibles par le nom du type attaché.

Voici quelques exemples courants :

• ListView propriétés attachées (isCurrentItem, view)
• GridView propriétés attachées
• Keys Propriétés attachées pour la gestion des événements clavier
• Component propriétés attachées (onCompleted, onDestruction)

Signaux attachés

Tout comme les propriétés attachées, les signaux attachés permettent aux types de fournir des gestionnaires de signaux supplémentaires aux objets. Ils sont généralement utilisés pour les événements du cycle de vie.

Par exemple, le type Component fournit des signaux attachés :

Rectangle {
    Component.onCompleted: {
        console.log("Rectangle creation completed")
    }

    Component.onDestruction: {
        console.log("Rectangle is being destroyed")
    }
}

Créer des propriétés attachées en C++

Pour créer des propriétés attachées pour vos propres types en C++, vous devez

1. Créer une classe de propriétés attachées qui hérite de QObject
2. Implémenter les propriétés attachées dans cette classe
3. Ajouter la macro QML_ATTACHED à votre type principal
4. Implémenter une méthode statique qmlAttachedProperties()

Exemple :

class MyAttachedType : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
    QML_ANONYMOUS

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

    int value() const { return m_value; }
    void setValue(int value)
    {
        if (m_value != value) {
            m_value = value;
            emit valueChanged();
        }
    }

signals:
    void valueChanged();

private:
    int m_value = 0;
};

class MyType : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_ATTACHED(MyAttachedType)

public:
    static MyAttachedType *qmlAttachedProperties(QObject *object)
    {
        return new MyAttachedType(object);
    }
};

Utilisation en QML :

Item {
    MyType.value: 42
}

Si le type attachant (MyType dans ce cas) ne fait rien d'autre qu'attacher des propriétés à d'autres objets, vous pouvez le formuler comme une classe unique :

class MyType : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
    QML_ELEMENT
    QML_ATTACHED(MyType)

public:
    static MyType *qmlAttachedProperties(QObject *object)
    {
        return new MyType(object);
    }

    MyType(QObject *parent = nullptr) : QObject(parent) {}

    int value() const { return m_value; }
    void setValue(int value)
    {
        if (m_value != value) {
            m_value = value;
            emit valueChanged();
        }
    }

signals:
    void valueChanged();

private:
    int m_value = 0;
};

Quand utiliser les propriétés attachées

Les propriétés attachées sont utiles dans les cas suivants

• Vous souhaitez ajouter des informations spécifiques au contexte à des éléments (comme ListView's isCurrentItem).
• Les propriétés appartiennent logiquement à un conteneur ou à un contexte plutôt qu'à l'élément lui-même.
• Vous voulez éviter d'encombrer les types de base avec des propriétés spécialisées.