É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, consultez la section Attributs d'énumération.

Lorsqu’elles sont définies en C++, les énumérations exposées à QML doivent être marquées à l’aide des 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, consultez la section 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 référencée sous la forme <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 générée par le nom du type. Vous pouvez également les récupérer à l’aide de la syntaxe des crochets de JavaScript, bien que cette méthode soit source d’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 constituent pas des types distincts en QML, mais sont des propriétés des types qui les entourent. Une valeur d’énumération est représentée par le type sous-jacent de l’énumération. Pour la plupart des énumérations, on peut utiliser sans risque le type ` Number` de JavaScript ou le type `double ` de QML pour les stocker. Cependant, cela ne fonctionne pas toujours pour les entiers 64 bits, car leur plage dépasse la plage d’entiers sûre des doubles 64 bits. Par conséquent, les énumérations dont les valeurs se situent en dehors de la plage d'entiers sûre (de -(2^53 - 1) à 2^53 - 1 inclus) ne peuvent pas être utilisées en toute sécurité dans 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 pour les stocker.

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)
}

Aides pour la conversion entre chaîne de caractère de clé d’énumération et valeur de clé

L’objet global Qt fournit des méthodes d’aide permettant de mapper le nom d’une clé de l’énumération à sa valeur numérique, ou inversement.

• Qt.enumStringToValue : associe une chaîne de caractères contenant le nom d’une clé à sa valeur numérique
• Qt.enumValueToString : associe une valeur au nom de la clé correspondant à cette valeur
• Qt.enumValueToStrings : associe une valeur à une liste des noms des 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)
}