Les énumérations QML

Les énumérations utilisées en QML peuvent être définies soit en QML, soit en C++.

Pour plus d'informations sur la définition des énumérations en QML, voir Attributs des énumérations.

Lorsqu'elles sont définies en C++, les énumérations exposées à QML doivent être marquées par les macros Q_ENUM ou Q_ENUM_NS et faire partie d'un type exposé à QML via les macros QML_NAMED_ELEMENT ou QML_ELEMENT. Pour plus de détails, voir Types d'énumération.

Seuls les types QML nommés peuvent contenir des énumérations utilisables en QML. Chaque énumération doit être entourée d'un type nommé. Les espaces de noms QML sont également des types QML et peuvent contenir des énumérations.

Par conséquent, une valeur d'énumération peut être désignée par <Type>.<Value>. Par exemple, le type Text possède une valeur d'énumération AlignRight:

Text { horizontalAlignment: Text.AlignRight }

Les valeurs d'énumération sont des propriétés de la référence de type produite par le nom du type. Vous pouvez également les récupérer en utilisant la syntaxe des crochets de JavaScript, mais cette méthode est sujette aux erreurs et n'est pas recommandée :

// Avoid this if possible
Text { horizontalAlignment: Text["AlignRight"] }

Utilisation des énumérations en QML

Les énumérations ne sont pas des types distincts en QML, mais des propriétés des types qui les entourent. Une valeur d'énumération est représentée comme le type sous-jacent de l'énumération. Pour la plupart des énumérations, il est prudent d'utiliser le type Number de JavaScript ou le type double de QML pour les stocker. Cependant, cela ne fonctionne pas toujours pour les entiers de 64 bits, car leur plage dépasse la plage d'entiers sûre des doubles de 64 bits. Par conséquent, les énumérations dont les valeurs se situent en dehors de la plage des entiers sûrs (-(2^53 - 1) à 2^53 - 1, inclus) ne peuvent pas être utilisées en toute sécurité en QML. Pour les énumérations dont les valeurs s'inscrivent dans la plage numérique d'un entier signé de 32 bits, vous pouvez utiliser en toute sécurité le type int de QML comme stockage.

Par exemple :

import QtQuick

Item {
    // refer to Text.AlignRight using an int type
    property int enumValue: textItem.horizontalAlignment

    signal valueEmitted(int someValue)

    Text {
        id: textItem
        horizontalAlignment: Text.AlignRight
    }

    // emit valueEmitted() signal, which expects an int, with Text.AlignRight
    Component.onCompleted: valueEmitted(Text.AlignRight)
}

Chaîne de clé de l'énumération <-> Aide à la valeur de la clé

L'objet global Qt fournit des méthodes d'aide qui permettent de faire correspondre le nom d'une clé de l'énumération à sa valeur numérique ou vice versa.

• Qt.enumStringToValue : fait correspondre une chaîne de caractères contenant le nom d'une clé à sa valeur numérique.
• Qt.enumValueToString : associe une valeur au nom d'une clé contenant cette valeur.
• Qt.enumValueToStrings : associe une valeur à une liste de noms de clés ayant cette valeur.

Exemple :

// Main.qml
import QtQml

Item {
    enum E { Black = 0, White = 1, Grey = 2, Gray = 2 }

    // 1 (White)
    property int i: Qt.enumStringToValue(Main.E, "White")

    // "Black"
    property string s: Qt.enumValueToString(Main.E, Main.E.Black)

    // ["Grey", "Gray"]
    property list<string> ss: Qt.enumValueToStrings(Main.E, Main.E.Grey)
}