Back to Qt.io
Contact Us Blog Download Qt
En esta página

QFlags Class

template <typename Enum> class QFlags

La clase QFlags proporciona una forma segura de almacenar combinaciones OR de valores enum. Más...

Cabecera: #include <QFlags>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Inherits: QtPrivate::QFlagsStorageHelper

Tipos Públicos

Int
enum_type

Funciones Públicas

QFlags()
QFlags(Enum flags)
QFlags(QFlag flag)
QFlags(std::initializer_list<Enum> flags)
(since 6.9) QFlags(std::in_place_t, QFlags<T>::Int flags)
QFlags(const QFlags<T> &other)
QFlags<T> &setFlag(Enum flag, bool on = true)
(since 6.2) bool testAnyFlag(Enum flag) const
(since 6.2) bool testAnyFlags(QFlags<T> flags) const
bool testFlag(Enum flag) const
(since 6.2) bool testFlags(QFlags<T> flags) const
(since 6.2) QFlags<T>::Int toInt() const
operator QFlags<T>::Int() const
bool operator!() const
QFlags<T> operator&(int mask) const
QFlags<T> operator&(Enum mask) const
(since 6.2) QFlags<T> operator&(QFlags<T> mask) const
QFlags<T> operator&(uint mask) const
QFlags<T> &operator&=(int mask)
QFlags<T> &operator&=(Enum mask)
(since 6.2) QFlags<T> &operator&=(QFlags<T> mask)
QFlags<T> &operator&=(uint mask)
int &operator=(const QFlags<T> &other)
QFlags<T> operator^(QFlags<T> other) const
QFlags<T> operator^(Enum other) const
QFlags<T> &operator^=(QFlags<T> other)
QFlags<T> &operator^=(Enum other)
QFlags<T> operator|(QFlags<T> other) const
QFlags<T> operator|(Enum other) const
QFlags<T> &operator|=(QFlags<T> other)
QFlags<T> &operator|=(Enum other)
QFlags<T> operator~() const

Miembros Públicos Estáticos

(since 6.2) QFlags<T> fromInt(QFlags<T>::Int i)
(since 6.2) size_t qHash(QFlags<Enum> key, size_t seed = 0)
(since 6.2) bool operator!=(Enum lhs, QFlags<T> rhs)
(since 6.2) bool operator!=(QFlags<T> lhs, Enum rhs)
(since 6.2) bool operator!=(QFlags<T> lhs, QFlags<T> rhs)
(since 6.2) bool operator==(Enum lhs, QFlags<T> rhs)
(since 6.2) bool operator==(QFlags<T> lhs, Enum rhs)
(since 6.2) bool operator==(QFlags<T> lhs, QFlags<T> rhs)

Macros

Q_DECLARE_FLAGS(Flags, Enum)
Q_DECLARE_OPERATORS_FOR_FLAGS(Flags)

Descripción Detallada

La clase QFlags<Enum> es una clase plantilla, donde Enum es un tipo enum. QFlags se usa en todo Qt para almacenar combinaciones de valores enum.

El enfoque tradicional de C++ para almacenar combinaciones OR de valores enum es utilizar una variable int o uint. El inconveniente de este enfoque es que no hay comprobación de tipo en absoluto; cualquier valor enum puede ser OR con cualquier otro valor enum y pasado a una función que tome un int o uint.

Desde Qt 6.9, QFlags soporta enumeraciones de 64 bits. Se recomienda utilizar tipos subyacentes explícitos (fijos) cuando se superen los 32 bits, para garantizar que ni la enumeración ni el tipo QFlags cambian de tamaño si se elimina un enumerador. Algunos compiladores también harán que el tipo enum sólo sea mayor de 32 bits con tipos subyacentes explícitos.

Qt utiliza QFlags para proporcionar seguridad de tipo. Por ejemplo, el tipo Qt::Alignment es simplemente un typedef para QFlags<Qt::AlignmentFlag>. QLabel::setAlignment() toma un parámetro Qt::Alignment, lo que significa que cualquier combinación de valores Qt::AlignmentFlag, o { }, es legal:

label->setAlignment(Qt::AlignLeft | Qt::AlignTop);
label->setAlignment({ });

Si intenta pasar un valor de otro enum o simplemente un entero distinto de 0, el compilador informará de un error. Si necesitas pasar valores enteros a flags de forma no tipada, puedes usar el constructor explícito QFlags como operador cast.

Si desea utilizar QFlags para sus propios tipos enum, utilice Q_DECLARE_FLAGS() y Q_DECLARE_OPERATORS_FOR_FLAGS().

Ejemplo:

class MyClass_1
{
public:
    enum Option {
        NoOptions = 0x0,
        ShowTabs = 0x1,
        ShowAll = 0x2,
        SqueezeBlank = 0x4
    };
    Q_DECLARE_FLAGS(Options, Option)
    //...
};

Q_DECLARE_OPERATORS_FOR_FLAGS(MyClass_1::Options)

Puede utilizar el tipo MyClass::Options para almacenar combinaciones de valores MyClass::Option.

Flags y el sistema de metaobjetos

La macro Q_DECLARE_FLAGS() no expone las banderas al sistema de meta-objetos, por lo que no pueden ser utilizadas por Qt Script o editadas en Qt Widgets Designer. Para que las banderas estén disponibles para estos propósitos, debe utilizarse la macro Q_FLAG():

Q_FLAG(Options)

Convención de nombres

Una convención de nomenclatura sensata para tipos enum y tipos QFlags asociados es dar un nombre singular al tipo enum (por ejemplo, Option) y un nombre plural al tipo QFlags (por ejemplo, Options). Cuando se desea un nombre singular para el tipo QFlags (por ejemplo, Alignment), se puede utilizar Flag como sufijo para el tipo enum (por ejemplo, AlignmentFlag).

Documentación de tipos de miembros

[alias] QFlags::Int

Typedef para el tipo entero utilizado para el almacenamiento, así como para la conversión implícita. Puede ser qintXX o quintXX, dependiendo de si el tipo subyacente del enum es con o sin signo y, desde Qt 6.9, del tamaño del enum. Típicamente, será qint32 (int) o quint32 (unsigned).

QFlags::enum_type

Typedef para el tipo de plantilla Enum.

Documentación de funciones miembro

[constexpr noexcept] QFlags::QFlags()

Construye un objeto QFlags sin banderas.

[constexpr noexcept] QFlags::QFlags(Enum flags)

Construye un objeto QFlags que almacena el flags.

[constexpr noexcept] QFlags::QFlags(QFlag flag) requires (sizeof(Enum) == sizeof(int))

Construye un objeto QFlags inicializado con el entero flag.

El tipo QFlag es un tipo de ayuda. Al utilizarlo aquí en lugar de int, nos aseguramos de que los valores arbitrarios de enum no se puedan convertir en QFlags, mientras que los valores de enum no tipados (es decir, los valores de int ) sí pueden.

Este constructor sólo está presente para los tipos Enum de 32 bits. Para soportar todos los tamaños de enum, considere el constructor usando std::in_place_t.

[constexpr noexcept] QFlags::QFlags(std::initializer_list<Enum> flags)

Construye un objeto QFlags inicializado con todos los flags combinados usando el operador bitwise OR.

Véase también operator|=() y operator|().

[constexpr noexcept, since 6.9] QFlags::QFlags(std::in_place_t, QFlags<T>::Int flags)

Construye un objeto QFlags inicializado con el entero flags.

Esta función se introdujo en Qt 6.9.

[default] QFlags::QFlags(const QFlags<T> &other)

Construye una copia de other.

[static constexpr noexcept, since 6.2] QFlags<T> QFlags::fromInt(QFlags<T>::Int i)

Construye un objeto QFlags que representa el valor entero i.

Esta función se introdujo en Qt 6.2.

[constexpr noexcept] QFlags<T> &QFlags::setFlag(Enum flag, bool on = true)

Establece la bandera flag si on es true o la desestablece si on es false. Devuelve una referencia a este objeto.

[constexpr noexcept, since 6.2] bool QFlags::testAnyFlag(Enum flag) const

Devuelve true si alguna bandera establecida en flag también está establecida en este objeto flags, en caso contrario false. Si flag no tiene ninguna bandera establecida, el retorno será siempre false.

Esta función se introdujo en Qt 6.2.

Véase también testFlag().

[constexpr noexcept, since 6.2] bool QFlags::testAnyFlags(QFlags<T> flags) const

Devuelve true si alguna bandera establecida en flags también está establecida en este objeto flags, en caso contrario false. Si flags no tiene ninguna bandera establecida, el retorno será siempre false.

Esta función se introdujo en Qt 6.2.

Véase también testFlags().

[constexpr noexcept] bool QFlags::testFlag(Enum flag) const

Devuelve true si la bandera flag está activada, en caso contrario false.

Nota: si flag contiene varios bits establecidos en 1 (por ejemplo, si es un enumerador igual al bitwise-OR de otros enumeradores) entonces esta función devolverá true si y sólo si todos los bits están establecidos en este objeto flags. Por otra parte, si flag no contiene ningún bit establecido a 1 (es decir, su valor como entero es 0), entonces esta función devolverá true si y sólo si este objeto flags tampoco tiene ningún bit establecido a 1.

Véase también testAnyFlag().

[constexpr noexcept, since 6.2] bool QFlags::testFlags(QFlags<T> flags) const

Devuelve true si este objeto flags coincide con el dado flags.

Si flags tiene alguna bandera establecida, este objeto flags coincide precisamente si todas las banderas establecidas en flags también están establecidas en este objeto flags. En caso contrario, cuando flags no tiene ninguna bandera definida, este objeto flags sólo coincide si tampoco tiene ninguna bandera definida.

Esta función se introdujo en Qt 6.2.

Véase también testAnyFlags().

[constexpr noexcept, since 6.2] QFlags<T>::Int QFlags::toInt() const

Devuelve el valor almacenado en el objeto QFlags como un entero. Tenga en cuenta que el entero devuelto puede ser con o sin signo, dependiendo de si el tipo subyacente del enum es con o sin signo.

Esta función se introdujo en Qt 6.2.

Véase también Int.

[constexpr noexcept] QFlags::operator QFlags<T>::Int() const

Devuelve el valor almacenado en el objeto QFlags como un entero.

Véase también Int.

[constexpr noexcept] bool QFlags::operator!() const

Devuelve true si no hay ninguna bandera activada (es decir, si el valor almacenado por el objeto QFlags es 0); en caso contrario, devuelve false.

[constexpr noexcept] QFlags<T> QFlags::operator&(int mask) const

Devuelve un objeto QFlags que contiene el resultado de la operación AND a nivel de bits sobre este objeto y mask.

Este operador está desactivado si la macro QT_TYPESAFE_FLAGS está definida. Tenga en cuenta que tampoco está extendido a 64 bits para QFlags de 64 bits: para soporte de 64 bits, utilice la sobrecarga type-safe.

Véase también operator&=(), operator|(), operator^(), y operator~().

[constexpr noexcept] QFlags<T> QFlags::operator&(Enum mask) const

Se trata de una función sobrecargada.

[constexpr noexcept, since 6.2] QFlags<T> QFlags::operator&(QFlags<T> mask) const

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.2.

[constexpr noexcept] QFlags<T> QFlags::operator&(uint mask) const

Este operador está desactivado si la macro QT_TYPESAFE_FLAGS está definida. Tenga en cuenta que tampoco está extendido a 64 bits para QFlags de 64 bits: para soporte de 64 bits, utilice la sobrecarga type-safe.

Se trata de una función sobrecargada.

[constexpr noexcept] QFlags<T> &QFlags::operator&=(int mask)

Realiza una operación AND a nivel de bits con mask y almacena el resultado en este objeto QFlags. Devuelve una referencia a este objeto.

Este operador está desactivado si la macro QT_TYPESAFE_FLAGS está definida. Tenga en cuenta que tampoco está extendido a 64 bits para QFlags de 64 bits: para soporte de 64 bits, utilice la sobrecarga type-safe.

Véase también operator&(), operator|=() y operator^=().

[constexpr noexcept] QFlags<T> &QFlags::operator&=(Enum mask)

Se trata de una función sobrecargada.

[constexpr noexcept, since 6.2] QFlags<T> &QFlags::operator&=(QFlags<T> mask)

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.2.

[constexpr noexcept] QFlags<T> &QFlags::operator&=(uint mask)

Este operador está desactivado si la macro QT_TYPESAFE_FLAGS está definida. Tenga en cuenta que tampoco está extendido a 64 bits para QFlags de 64 bits: para soporte de 64 bits, utilice la sobrecarga type-safe.

Se trata de una función sobrecargada.

[default] int &QFlags::operator=(const QFlags<T> &other)

Asigna other a este objeto y devuelve una referencia a este objeto.

[constexpr noexcept] QFlags<T> QFlags::operator^(QFlags<T> other) const

Devuelve un objeto QFlags que contiene el resultado de la operación XOR a nivel de bit sobre este objeto y other.

Véase también operator^=(), operator&(), operator|() y operator~().

[constexpr noexcept] QFlags<T> QFlags::operator^(Enum other) const

Se trata de una función sobrecargada.

[constexpr noexcept] QFlags<T> &QFlags::operator^=(QFlags<T> other)

Realiza una operación XOR a nivel de bit con other y almacena el resultado en este objeto QFlags. Devuelve una referencia a este objeto.

Véase también operator^(), operator&=() y operator|=().

[constexpr noexcept] QFlags<T> &QFlags::operator^=(Enum other)

Se trata de una función sobrecargada.

[constexpr noexcept] QFlags<T> QFlags::operator|(QFlags<T> other) const

Devuelve un objeto QFlags que contiene el resultado de la operación bitwise OR sobre este objeto y other.

Véase también operator|=(), operator^(), operator&() y operator~().

[constexpr noexcept] QFlags<T> QFlags::operator|(Enum other) const

Se trata de una función sobrecargada.

[constexpr noexcept] QFlags<T> &QFlags::operator|=(QFlags<T> other)

Realiza una operación OR a nivel de bits con other y almacena el resultado en este objeto QFlags. Devuelve una referencia a este objeto.

Véase también operator|(), operator&=() y operator^=().

[constexpr noexcept] QFlags<T> &QFlags::operator|=(Enum other)

Se trata de una función sobrecargada.

[constexpr noexcept] QFlags<T> QFlags::operator~() const

Devuelve un objeto QFlags que contiene la negación bit a bit de este objeto.

Véase también operator&(), operator|() y operator^().

No miembros relacionados

[constexpr noexcept, since 6.2] template <typename Enum> size_t qHash(QFlags<Enum> key, size_t seed = 0)

Devuelve el valor hash para key, usando seed para sembrar el cálculo.

Esta función se introdujo en Qt 6.2.

[constexpr noexcept, since 6.2] bool operator!=(QFlags<T> lhs, QFlags<T> rhs)

[constexpr noexcept, since 6.2] bool operator!=(QFlags<T> lhs, Enum rhs)

[constexpr noexcept, since 6.2] bool operator!=(Enum lhs, QFlags<T> rhs)

Compara lhs y rhs para desigualdad; los dos argumentos se consideran diferentes si no representan exactamente el mismo valor (máscara de bits).

Estas funciones se introdujeron en Qt 6.2.

[constexpr noexcept, since 6.2] bool operator==(QFlags<T> lhs, QFlags<T> rhs)

[constexpr noexcept, since 6.2] bool operator==(QFlags<T> lhs, Enum rhs)

[constexpr noexcept, since 6.2] bool operator==(Enum lhs, QFlags<T> rhs)

Compara lhs y rhs en busca de igualdad; los dos argumentos se consideran iguales si representan exactamente el mismo valor (máscara de bits).

Estas funciones se introdujeron en Qt 6.2.

Documentación de macros

Q_DECLARE_FLAGS(Flags, Enum)

La macro Q_DECLARE_FLAGS() se expande a

typedef QFlags<Enum> Flags;

Enum es el nombre de un tipo enum existente, mientras que Flags es el nombre del QFlags<Enum> typedef.

Consulte la documentación de QFlags para más detalles.

Véase también Q_DECLARE_OPERATORS_FOR_FLAGS().

Q_DECLARE_OPERATORS_FOR_FLAGS(Flags)

La macro Q_DECLARE_OPERATORS_FOR_FLAGS() declara las funciones de operador global bitwise operator|(), operator&(), operator^(), operator~() y sus formas de asignación: &=, |=, y ^=. para Flags, que es del tipo QFlags<T>.

Consulte la documentación de QFlags para más detalles.

Véase también Q_DECLARE_FLAGS().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.