Enumerations in QML

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