QFlags Class
template <typename Enum> class QFlagsThe QFlags class provides a type-safe way of storing OR-combinations of enum values. More...
Header: | #include <QFlags> |
CMake: | find_package(Qt6 COMPONENTS Core REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake: | QT += core |
Public Types
Public Functions
QFlags(const QFlags<T> &other) | |
QFlags(std::initializer_list<Enum> flags) | |
QFlags(QFlag flag) | |
QFlags(Enum flags) | |
QFlags() | |
int & | operator=(const QFlags<T> &) |
QFlags<T> & | setFlag(Enum flag, bool on = true) |
bool | testAnyFlag(Enum flag) const |
bool | testAnyFlags(QFlags<T> flags) const |
bool | testFlag(Enum flag) const |
bool | testFlags(QFlags<T> flags) const |
QFlags::Int | toInt() const |
QFlags::Int | operator QFlags::Int() const |
bool | operator!() const |
QFlags<T> | operator&(int mask) const |
QFlags<T> | operator&(uint mask) const |
QFlags<T> | operator&(QFlags<T> other) const |
QFlags<T> | operator&(Enum other) const |
QFlags<T> & | operator&=(int mask) |
QFlags<T> & | operator&=(uint mask) |
QFlags<T> & | operator&=(QFlags<T> mask) |
QFlags<T> & | operator&=(Enum mask) |
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 |
Static Public Members
QFlags<T> | fromInt(QFlags::Int i) |
Related Non-Members
size_t | qHash(QFlags<Enum> flags, size_t seed = 0) |
Macros
Q_DECLARE_FLAGS(Flags, Enum) | |
Q_DECLARE_OPERATORS_FOR_FLAGS(Flags) |
Detailed Description
The QFlags<Enum> class is a template class, where Enum is an enum type. QFlags is used throughout Qt for storing combinations of enum values.
The traditional C++ approach for storing OR-combinations of enum values is to use an int
or uint
variable. The inconvenience with this approach is that there's no type checking at all; any enum value can be OR'd with any other enum value and passed on to a function that takes an int
or uint
.
Qt uses QFlags to provide type safety. For example, the Qt::Alignment type is simply a typedef for QFlags<Qt::AlignmentFlag>. QLabel::setAlignment() takes a Qt::Alignment parameter, which means that any combination of Qt::AlignmentFlag values, or { }
, is legal:
label->setAlignment(Qt::AlignLeft | Qt::AlignTop); label->setAlignment({ });
If you try to pass a value from another enum or just a plain integer other than 0, the compiler will report an error. If you need to cast integer values to flags in a untyped fashion, you can use the explicit QFlags constructor as cast operator.
If you want to use QFlags for your own enum types, use the Q_DECLARE_FLAGS() and Q_DECLARE_OPERATORS_FOR_FLAGS().
Example:
class MyClass { public: enum Option { NoOptions = 0x0, ShowTabs = 0x1, ShowAll = 0x2, SqueezeBlank = 0x4 }; Q_DECLARE_FLAGS(Options, Option) ... }; Q_DECLARE_OPERATORS_FOR_FLAGS(MyClass::Options)
You can then use the MyClass::Options
type to store combinations of MyClass::Option
values.
Flags and the Meta-Object System
The Q_DECLARE_FLAGS() macro does not expose the flags to the meta-object system, so they cannot be used by Qt Script or edited in Qt Designer. To make the flags available for these purposes, the Q_FLAG() macro must be used:
Q_FLAG(Options)
Naming Convention
A sensible naming convention for enum types and associated QFlags types is to give a singular name to the enum type (e.g., Option
) and a plural name to the QFlags type (e.g., Options
). When a singular name is desired for the QFlags type (e.g., Alignment
), you can use Flag
as the suffix for the enum type (e.g., AlignmentFlag
).
See also QFlag.
Member Type Documentation
[since 5.0]
QFlags::Int
Typedef for the integer type used for storage as well as for implicit conversion. Either int
or unsigned int
, depending on whether the enum's underlying type is signed or unsigned.
This typedef was introduced in Qt 5.0.
QFlags::enum_type
Typedef for the Enum template type.
Member Function Documentation
[default]
QFlags::QFlags(const QFlags<T> &other)
Constructs a copy of other.
[since 5.4]
QFlags::QFlags(std::initializer_list<Enum> flags)
Constructs a QFlags object initialized with all flags combined using the bitwise OR operator.
This function was introduced in Qt 5.4.
See also operator|=() and operator|().
QFlags::QFlags(QFlag flag)
Constructs a QFlags object initialized with the integer flag.
The QFlag type is a helper type. By using it here instead of int
, we effectively ensure that arbitrary enum values cannot be cast to a QFlags, whereas untyped enum values (i.e., int
values) can.
QFlags::QFlags(Enum flags)
Constructs a QFlags object storing the flags.
[since 5.15]
QFlags::QFlags()
Constructs a QFlags object with no flags set.
This function was introduced in Qt 5.15.
[default]
int &QFlags::operator=(const QFlags<T> &)
Assigns other to this object and returns a reference to this object.
[static, since 6.2]
QFlags<T> QFlags::fromInt(QFlags::Int i)
Constructs a QFlags object representing the integer value i.
This function was introduced in Qt 6.2.
[since 5.7]
QFlags<T> &QFlags::setFlag(Enum flag, bool on = true)
Sets the flag flag if on is true
or unsets it if on is false
. Returns a reference to this object.
This function was introduced in Qt 5.7.
[since 6.2]
bool QFlags::testAnyFlag(Enum flag) const
Returns true
if any flag set in flag is also set in this flags object, otherwise false
. If flag has no flags set, the return will always be false
.
This function was introduced in Qt 6.2.
See also testFlag().
[since 6.2]
bool QFlags::testAnyFlags(QFlags<T> flags) const
Returns true
if any flag set in flags is also set in this flags object, otherwise false
. If flags has no flags set, the return will always be false
.
This function was introduced in Qt 6.2.
See also testFlags().
bool QFlags::testFlag(Enum flag) const
Returns true
if the flag flag is set, otherwise false
.
Note: if flag contains multiple bits set to 1 (for instance, if it's an enumerator equal to the bitwise-OR of other enumerators) then this function will return true
if and only if all the bits are set in this flags object. On the other hand, if flag contains no bits set to 1 (that is, its value as a integer is 0), then this function will return true
if and only if this flags object also has no bits set to 1.
See also testAnyFlag().
[since 6.2]
bool QFlags::testFlags(QFlags<T> flags) const
Returns true
if this flags object matches the given flags.
If flags has any flags set, this flags object matches precisely if all flags set in flags are also set in this flags object. Otherwise, when flags has no flags set, this flags object only matches if it also has no flags set.
This function was introduced in Qt 6.2.
See also testAnyFlags().
[since 6.2]
QFlags::Int QFlags::toInt() const
Returns the value stored in the QFlags object as an integer. Note that the returned integer may be signed or unsigned, depending on whether the enum's underlying type is signed or unsigned.
This function was introduced in Qt 6.2.
See also Int.
QFlags::Int QFlags::operator QFlags::Int() const
Returns the value stored in the QFlags object as an integer.
See also Int.
bool QFlags::operator!() const
Returns true
if no flag is set (i.e., if the value stored by the QFlags object is 0); otherwise returns false
.
QFlags<T> QFlags::operator&(int mask) const
Returns a QFlags object containing the result of the bitwise AND operation on this object and mask.
See also operator&=(), operator|(), operator^(), and operator~().
QFlags<T> QFlags::operator&(uint mask) const
This is an overloaded function.
[since 6.2]
QFlags<T> QFlags::operator&(QFlags<T> other) const
This is an overloaded function.
This function was introduced in Qt 6.2.
QFlags<T> QFlags::operator&(Enum other) const
This is an overloaded function.
QFlags<T> &QFlags::operator&=(int mask)
Performs a bitwise AND operation with mask and stores the result in this QFlags object. Returns a reference to this object.
See also operator&(), operator|=(), and operator^=().
QFlags<T> &QFlags::operator&=(uint mask)
This is an overloaded function.
[since 6.2]
QFlags<T> &QFlags::operator&=(QFlags<T> mask)
This is an overloaded function.
This function was introduced in Qt 6.2.
QFlags<T> &QFlags::operator&=(Enum mask)
This is an overloaded function.
QFlags<T> QFlags::operator^(QFlags<T> other) const
Returns a QFlags object containing the result of the bitwise XOR operation on this object and other.
See also operator^=(), operator&(), operator|(), and operator~().
QFlags<T> QFlags::operator^(Enum other) const
This is an overloaded function.
QFlags<T> &QFlags::operator^=(QFlags<T> other)
Performs a bitwise XOR operation with other and stores the result in this QFlags object. Returns a reference to this object.
See also operator^(), operator&=(), and operator|=().
QFlags<T> &QFlags::operator^=(Enum other)
This is an overloaded function.
QFlags<T> QFlags::operator|(QFlags<T> other) const
Returns a QFlags object containing the result of the bitwise OR operation on this object and other.
See also operator|=(), operator^(), operator&(), and operator~().
QFlags<T> QFlags::operator|(Enum other) const
This is an overloaded function.
QFlags<T> &QFlags::operator|=(QFlags<T> other)
Performs a bitwise OR operation with other and stores the result in this QFlags object. Returns a reference to this object.
See also operator|(), operator&=(), and operator^=().
QFlags<T> &QFlags::operator|=(Enum other)
This is an overloaded function.
QFlags<T> QFlags::operator~() const
Returns a QFlags object that contains the bitwise negation of this object.
Related Non-Members
[since 6.2]
template <typename Enum> size_t qHash(QFlags<Enum> flags, size_t seed = 0)
Calculates the hash for the flags flags, using seed to seed the calcualtion.
This function was introduced in Qt 6.2.
Macro Documentation
Q_DECLARE_FLAGS(Flags, Enum)
The Q_DECLARE_FLAGS() macro expands to
typedef QFlags<Enum> Flags;
Enum is the name of an existing enum type, whereas Flags is the name of the QFlags<Enum> typedef.
See the QFlags documentation for details.
See also Q_DECLARE_OPERATORS_FOR_FLAGS().
Q_DECLARE_OPERATORS_FOR_FLAGS(Flags)
The Q_DECLARE_OPERATORS_FOR_FLAGS() macro declares global operator|()
functions for Flags, which is of type QFlags<T>.
See the QFlags documentation for details.
See also Q_DECLARE_FLAGS().