// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-typesystem-enumerations.html
\title QML Enumerations
\brief Description of QML Enumerations

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

For information on defining enumerations in QML, see
\l{QML Object Attributes#enumeration-attributes}{Enumeration Attributes}.

When defined in C++, enumerations exposed to QML must be marked with the
\l{Q_ENUM} or \l{Q_ENUM_NS} macros and be part of a type exposed to QML via the
\l{QML_NAMED_ELEMENT} or \l{QML_ELEMENT} macros. For more details, see
\l{Data Type Conversion Between QML and C++#enumeration-types}{Enumeration Types}.

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

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

\qml
Text { horizontalAlignment: Text.AlignRight }
\endqml

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:

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

\section1 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
\e Number type or QML's \e 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 \e int type as storage.

For example:

\qml
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)
}
\endqml

\sa {QML Value Types}
\sa {QML Object Attributes#enumeration-attributes}{Enumeration Attributes}
\sa {Data Type Conversion Between QML and C++#enumeration-types}{Enumeration Types}

\section2 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.

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

Example:
\qml
// 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)
}
\endqml

\sa QtQml::Qt::enumStringToValue
\sa QtQml::Qt::enumValueToString
\sa QtQml::Qt::enumValueToStrings
*/
