Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QFlags Class

template <typename Enum> class QFlags

La classe QFlags fournit un moyen sûr de stocker des combinaisons OU de valeurs d'énumération. Plus d'informations...

En-tête : #include <QFlags>
CMake : find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake : QT += core
Hérite : QtPrivate::QFlagsStorageHelper

Types publics

Int
enum_type

Fonctions publiques

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

Membres publics statiques

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

Description détaillée

La classe QFlags<Enum> est une classe modèle, où Enum est un type d'énumération. QFlags est utilisée dans tout Qt pour stocker des combinaisons de valeurs d'enum.

L'approche traditionnelle en C++ pour stocker des combinaisons OR de valeurs enum consiste à utiliser une variable int ou uint. L'inconvénient de cette approche est qu'il n'y a aucune vérification de type ; n'importe quelle valeur d'enum peut être combinée avec n'importe quelle autre valeur d'enum et transmise à une fonction qui prend une variable int ou uint.

Depuis Qt 6.9, QFlags supporte les énumérations 64 bits. Il est recommandé d'utiliser des types sous-jacents explicites (fixes) lorsque l'on dépasse les 32 bits, afin de s'assurer que ni l'énumération ni le type QFlags ne changent de taille si un énumérateur est supprimé. Certains compilateurs n'autoriseront le type enum à dépasser 32 bits qu'avec des types sous-jacents explicites.

Qt utilise les QFlags pour assurer la sécurité des types. Par exemple, le type Qt::Alignment est simplement un typedef pour QFlags<Qt::AlignmentFlag>. QLabel::setAlignment() prend un paramètre Qt::Alignment, ce qui signifie que toute combinaison de valeurs Qt::AlignmentFlag ou { } est légale :

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

Si vous essayez de passer une valeur d'un autre enum ou un simple entier différent de 0, le compilateur signalera une erreur. Si vous devez convertir des valeurs entières en drapeaux de manière non typée, vous pouvez utiliser le constructeur explicite de QFlags comme opérateur de conversion.

Si vous souhaitez utiliser QFlags pour vos propres types d'enum, utilisez Q_DECLARE_FLAGS() et Q_DECLARE_OPERATORS_FOR_FLAGS().

Exemple :

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)

Vous pouvez alors utiliser le type MyClass::Options pour stocker des combinaisons de valeurs MyClass::Option.

Les drapeaux et le système des méta-objets

La macro Q_DECLARE_FLAGS() n'expose pas les drapeaux au système de méta-objets, de sorte qu'ils ne peuvent pas être utilisés par Qt Script ou édités dans Qt Widgets Designer. Pour rendre les drapeaux disponibles à ces fins, la macro Q_FLAG() doit être utilisée :

Q_FLAG(Options)

Convention d'appellation

Une convention de dénomination judicieuse pour les types enum et les types QFlags associés consiste à donner un nom singulier au type enum (par exemple, Option) et un nom pluriel au type QFlags (par exemple, Options). Lorsqu'un nom singulier est souhaité pour le type QFlags (par exemple, Alignment), vous pouvez utiliser Flag comme suffixe pour le type enum (par exemple, AlignmentFlag).

Documentation sur les types de membres

[alias] QFlags::Int

Typedef pour le type entier utilisé pour le stockage ainsi que pour la conversion implicite. Soit qintXX ou quintXX, selon que le type sous-jacent de l'enum est signé ou non signé et, depuis Qt 6.9, la taille de l'enum. Typiquement, ce sera qint32 (int) ou quint32 (unsigned).

QFlags::enum_type

Typedef pour le modèle de type Enum.

Documentation des fonctions membres

[constexpr noexcept] QFlags::QFlags()

Construit un objet QFlags sans drapeaux définis.

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

Construit un objet QFlags contenant l'adresse flags.

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

Construit un objet QFlags initialisé avec l'entier flag.

Le type QFlag est un type d'aide. En l'utilisant ici au lieu de int, nous nous assurons que les valeurs arbitraires d'un enum ne peuvent pas être moulées dans un QFlags, alors que les valeurs d'un enum non typé (c'est-à-dire les valeurs int ) le peuvent.

Ce constructeur n'est présent que pour les types Enum 32 bits. Pour prendre en charge toutes les tailles d'énumération, envisagez le constructeur en utilisant std::in_place_t.

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

Construit un objet QFlags initialisé avec tous les flags combinés à l'aide de l'opérateur bitwise OR.

Voir aussi operator|=() et operator|().

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

Construit un objet QFlags initialisé avec l'entier flags.

Cette fonction a été introduite dans Qt 6.9.

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

Construit une copie de other.

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

Construit un objet QFlags représentant la valeur entière i.

Cette fonction a été introduite dans Qt 6.2.

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

Définit l'indicateur flag si on est true ou l'annule si on est false. Renvoie une référence à cet objet.

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

Renvoie true si l'un des drapeaux définis dans flag est également défini dans cet objet flags, sinon false. Si flag n'a pas de drapeau défini, le retour sera toujours false.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi testFlag().

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

Renvoie true si l'un des drapeaux définis dans flags est également défini dans cet objet flags, sinon false. Si flags n'a pas de drapeau défini, le retour sera toujours false.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi testFlags().

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

Renvoie true si l'indicateur flag est activé, sinon false.

Remarque : si flag contient plusieurs bits à 1 (par exemple, s'il s'agit d'un énumérateur égal au OU bit à bit d'autres énumérateurs), cette fonction renverra true si et seulement si tous les bits sont activés dans cet objet flags. En revanche, si flag ne contient aucun bit à 1 (c'est-à-dire que sa valeur en tant qu'entier est 0), cette fonction renverra true si et seulement si cet objet flags n'a pas non plus de bits à 1.

Voir aussi testAnyFlag().

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

Renvoie true si cet objet flags correspond à flags.

Si flags a des drapeaux définis, cet objet flags correspond précisément si tous les drapeaux définis dans flags sont également définis dans cet objet flags. Sinon, si flags n'a pas de drapeaux définis, cet objet flags ne correspond que s'il n'a pas non plus de drapeaux définis.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi testAnyFlags().

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

Renvoie la valeur stockée dans l'objet QFlags sous la forme d'un entier. Notez que l'entier retourné peut être signé ou non signé, selon que le type sous-jacent de l'enum est signé ou non signé.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi Int.

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

Renvoie la valeur stockée dans l'objet QFlags sous la forme d'un entier.

Voir aussi Int.

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

Renvoie true si aucun drapeau n'est défini (c'est-à-dire si la valeur stockée par l'objet QFlags est 0) ; sinon, renvoie false.

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

Renvoie un objet QFlags contenant le résultat de l'opération ET bit à bit sur cet objet et mask.

Cet opérateur est désactivé si la macro QT_TYPESAFE_FLAGS est définie. Notez qu'il n'est pas non plus étendu à 64 bits pour QFlags 64 bits : pour le support 64 bits, utilisez la surcharge type-safe.

Voir aussi operator&=(), operator|(), operator^() et operator~().

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

Il s'agit d'une fonction surchargée.

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

Il s'agit d'une fonction surchargée.

Cette fonction a été introduite dans Qt 6.2.

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

Cet opérateur est désactivé si la macro QT_TYPESAFE_FLAGS est définie. Notez qu'il n'est pas non plus étendu à 64 bits pour QFlags 64 bits : pour la prise en charge de 64 bits, utilisez la surcharge de sécurité de type.

Il s'agit d'une fonction surchargée.

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

Effectue une opération ET bit à bit avec mask et stocke le résultat dans cet objet QFlags. Renvoie une référence à cet objet.

Cet opérateur est désactivé si la macro QT_TYPESAFE_FLAGS est définie. Notez qu'il n'est pas non plus étendu à 64 bits pour QFlags 64 bits : pour la prise en charge 64 bits, utilisez la surcharge type-safe.

Voir aussi operator&(), operator|=() et operator^=().

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

Il s'agit d'une fonction surchargée.

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

Il s'agit d'une fonction surchargée.

Cette fonction a été introduite dans Qt 6.2.

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

Cet opérateur est désactivé si la macro QT_TYPESAFE_FLAGS est définie. Notez qu'il n'est pas non plus étendu à 64 bits pour QFlags 64 bits : pour la prise en charge de 64 bits, utilisez la surcharge de sécurité de type.

Il s'agit d'une fonction surchargée.

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

Affecte other à cet objet et renvoie une référence à cet objet.

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

Renvoie un objet QFlags contenant le résultat de l'opération XOR bit à bit sur cet objet et other.

Voir aussi operator^=(), operator&(), operator|() et operator~().

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

Il s'agit d'une fonction surchargée.

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

Effectue une opération XOR par bit avec other et stocke le résultat dans cet objet QFlags. Renvoie une référence à cet objet.

Voir aussi operator^(), operator&=() et operator|=().

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

Il s'agit d'une fonction surchargée.

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

Renvoie un objet QFlags contenant le résultat de l'opération OU bit à bit sur cet objet et other.

Voir aussi operator|=(), operator^(), operator&() et operator~().

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

Il s'agit d'une fonction surchargée.

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

Effectue une opération OR bit à bit avec other et stocke le résultat dans cet objet QFlags. Renvoie une référence à cet objet.

Voir aussi operator|(), operator&=() et operator^=().

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

Il s'agit d'une fonction surchargée.

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

Renvoie un objet QFlags qui contient la négation bit à bit de cet objet.

Voir aussi operator&(), operator|() et operator^().

Non-membres apparentés

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

Renvoie la valeur de hachage pour key, en utilisant seed comme base de calcul.

Cette fonction a été introduite dans 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)

Compare lhs et rhs pour l'inégalité ; les deux arguments sont considérés comme différents s'ils ne représentent pas exactement la même valeur (bitmask).

Ces fonctions ont été introduites dans 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)

Compare lhs et rhs pour vérifier l'égalité ; les deux arguments sont considérés comme égaux s'ils représentent exactement la même valeur (masque de bits).

Ces fonctions ont été introduites dans Qt 6.2.

Documentation sur les macros

Q_DECLARE_FLAGS(Flags, Enum)

La macro Q_DECLARE_FLAGS() se développe en

typedef QFlags<Enum> Flags;

Enum est le nom d'un type d'énumération existant, tandis que Flags est le nom du typage QFlags<Enum>.

Voir la documentation de QFlags pour plus de détails.

Voir également Q_DECLARE_OPERATORS_FOR_FLAGS().

Q_DECLARE_OPERATORS_FOR_FLAGS(Flags)

La macro Q_DECLARE_OPERATORS_FOR_FLAGS() déclare les fonctions globales d'opérateurs bitwise operator|(), operator&(), operator^(), operator~() et leurs formes d'affectation : &=, |= et ^=. pour Flags, qui est de type QFlags<T>.

Voir la documentation de QFlags pour plus de détails.

Voir également 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.