QML Enumerations | Qt Qml | Qt 6.11.1
Description: Description of QML Enumerations

- Qt 6.11
- Qt Qml
- The QML Reference
- The QML Type System
- QML Enumerations
- Qt 6.11.1 Reference Documentation

QML Value Types ◦ QML Sequence Types

# QML Enumerations

Enumerations used in QML can be defined either in QML or in C++.

For information on defining enumerations in QML, see Enumeration Attributes.

When defined in C++, enumerations exposed to QML must be marked with the Q_ENUM or Q_ENUM_NS macros and be part of a type exposed to QML via the QML_NAMED_ELEMENT or QML_ELEMENT macros. For more details, see Enumeration Types.

Only named QML types can hold enumerations usable in QML. Each enumeration must have a surrounding named type. QML Namespaces are also QML types and can hold enums.

As a result, an enumeration value can be referred to as `<Type>.<Value>`. For example, the Text type has an `AlignRight` enumeration value:

     Text { horizontalAlignment: Text.AlignRight }

Enumeration values are properties of the type reference produced by the type name. You can also retrieve them using JavaScript’s square bracket syntax, though this is error-prone and not recommended:

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

## Using Enumerations in QML

Enumerations are not separate types in QML but are properties of their surrounding types. An enumeration value is represented as the underlying type of the enumeration. For most enumerations, it is safe to use JavaScript's Number type or QML's double type to store them. However, this does not always work for 64-bit integers, as their range exceeds the safe integer range of 64-bit doubles. Therefore, enumerations with values outside the safe integer range (-(2^53 - 1) to 2^53 - 1, inclusive) cannot be safely used in QML. For enumerations with values that fit into the numeric range of a 32-bit signed integer, you can safely use the QML int type as storage.

For example:

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

### Enumeration key string <-> key value helpers

The Qt global object provides helper methods that can map the name of a key in the enumeration to its numeric value or vice versa.

- Qt.enumStringToValue: maps a string containing the name of a key to its numerical value
- Qt.enumValueToString: maps a value to the name of a key with that value
- Qt.enumValueToStrings: maps a value to a list of names of the keys with that value

Example:

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

See also QML Value Types, Enumeration Attributes, Enumeration Types, QtQml::Qt::enumStringToValue, QtQml::Qt::enumValueToString, and QtQml::Qt::enumValueToStrings.

QML Value Types ◦ QML Sequence Types