<QtGlobal> - Global Qt Declarations

 int myValue = 10;
 int minValue = 2;
 int maxValue = 6;

 int boundedValue = qBound(minValue, myValue, maxValue);
 // boundedValue == 6

 if (!driver()->isOpen() || driver()->isOpenError()) {
     qWarning("QSqlQuery::exec: database not open");
     return false;
 }

 void myMessageHandler(QtMsgType, const QMessageLogContext &, const QString &);

 qint64 value = Q_INT64_C(932838457459459);

 quint64 value = Q_UINT64_C(932838457459459);

 int absoluteValue;
 int myValue = -4;

 absoluteValue = qAbs(myValue);
 // absoluteValue == 4

     QString s = ...;
     for (QChar ch : s) // detaches 's' (performs a deep-copy if 's' was shared)
         process(ch);
     for (QChar ch : qAsConst(s)) // ok, no detach attempt
         process(ch);

     const QString s = ...;
     for (QChar ch : s) // ok, no detach attempt on const objects
         process(ch);

     for (QChar ch : funcReturningQString())
         process(ch); // OK, the returned object is kept alive for the loop's duration

     for (QChar ch : qAsConst(funcReturningQString()))
         process(ch); // ERROR: ch is copied from deleted memory

     for (QChar ch : qAsConst(funcReturningQString()))
         process(ch); // ERROR: ch is copied from deleted memory

 int myValue = 10;
 int minValue = 2;
 int maxValue = 6;

 int boundedValue = qBound(minValue, myValue, maxValue);
 // boundedValue == 6

     struct Foo {
         void overloadedFunction(int, const QString &);
         void overloadedFunction(int, const QString &) const;
     };
     ... qConstOverload<int, const QString &>(&Foo::overloadedFunction)
     ... qNonConstOverload<int, const QString &>(&Foo::overloadedFunction)

     qgetenv(varName).toInt(ok, 0)

     qgetenv(varName).isEmpty()

     !qgetenv(varName).isNull()

 MyClass(MyClass &&other)
   : m_pointer{qExchange(other.m_pointer, nullptr)},
     m_int{qExchange(other.m_int, 0)},
     m_vector{std::move(other.m_vector)},
     ...

 for (auto &e : qExchange(collection, {})
     doSomethingWith(e);

 {
     auto tmp = std::move(collection);
     collection = {};                    // or collection.clear()
     for (auto &e : tmp)
         doSomethingWith(e);
 }                                       // destroys 'tmp'

     if (qFloatDistance(a, b) < (1 << 7)) {   // The last 7 bits are not
                                             // significant
         // precise enough
     }

 // Instead of comparing with 0.0
 qFuzzyCompare(0.0, 1.0e-200); // This will return false
 // Compare adding 1 to both values will fix the problem
 qFuzzyCompare(1 + 0.0, 1 + 1.0e-200); // This will return true

 #include <qapplication.h>
 #include <stdio.h>
 #include <stdlib.h>

 void myMessageOutput(QtMsgType type, const QMessageLogContext &context, const QString &msg)
 {
     QByteArray localMsg = msg.toLocal8Bit();
     const char *file = context.file ? context.file : "";
     const char *function = context.function ? context.function : "";
     switch (type) {
     case QtDebugMsg:
         fprintf(stderr, "Debug: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function);
         break;
     case QtInfoMsg:
         fprintf(stderr, "Info: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function);
         break;
     case QtWarningMsg:
         fprintf(stderr, "Warning: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function);
         break;
     case QtCriticalMsg:
         fprintf(stderr, "Critical: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function);
         break;
     case QtFatalMsg:
         fprintf(stderr, "Fatal: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function);
         break;
     }
 }

 int main(int argc, char **argv)
 {
     qInstallMessageHandler(myMessageOutput);
     QApplication app(argc, argv);
     ...
     return app.exec();
 }

 int myValue = 6;
 int yourValue = 4;

 int maxValue = qMax(myValue, yourValue);
 // maxValue == myValue

 int myValue = 6;
 int yourValue = 4;

 int minValue = qMin(myValue, yourValue);
 // minValue == yourValue

     struct Foo {
         void overloadedFunction(int, const QString &);
         void overloadedFunction(int, const QString &) const;
     };
     ... qConstOverload<int, const QString &>(&Foo::overloadedFunction)
     ... qNonConstOverload<int, const QString &>(&Foo::overloadedFunction)

     struct Foo {
         void overloadedFunction();
         void overloadedFunction(int, const QString &);
     };
     ... qOverload<>(&Foo::overloadedFunction)
     ... qOverload<int, const QString &>(&Foo::overloadedFunction)

     ... QOverload<>::of(&Foo::overloadedFunction)
     ... QOverload<int, const QString &>::of(&Foo::overloadedFunction)

 double valueA = 42949672960.3;
 double valueB = 42949672960.7;

 qint64 roundedValueA = qRound64(valueA);
 // roundedValueA = 42949672960
 qint64 roundedValueB = qRound64(valueB);
 // roundedValueB = 42949672961

 float valueA = 42949672960.3;
 float valueB = 42949672960.7;

 qint64 roundedValueA = qRound64(valueA);
 // roundedValueA = 42949672960
 qint64 roundedValueB = qRound64(valueB);
 // roundedValueB = 42949672961

 double valueA = 2.3;
 double valueB = 2.7;

 int roundedValueA = qRound(valueA);
 // roundedValueA = 2
 int roundedValueB = qRound(valueB);
 // roundedValueB = 3

 float valueA = 2.3;
 float valueB = 2.7;

 int roundedValueA = qRound(valueA);
 // roundedValueA = 2
 int roundedValueB = qRound(valueB);
 // roundedValueB = 3

     QT_MESSAGE_PATTERN="[%{time yyyyMMdd h:mm:ss.zzz t} %{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}] %{file}:%{line} - %{message}"

     //% "%n fooish bar(s) found.\n"
     //% "Do you want to continue?"
     QString text = qtTrId("qtn_foo_bar", n);

Macro Documentation

QT_DEPRECATED_WARNINGS

Since Qt 5.13, this macro has no effect. In Qt 5.12 and before, if this macro is defined, the compiler will generate warnings if any API declared as deprecated by Qt is used.

See also QT_DISABLE_DEPRECATED_BEFORE and QT_NO_DEPRECATED_WARNINGS.

QT_DISABLE_DEPRECATED_BEFORE

This macro can be defined in the project file to disable functions deprecated in a specified version of Qt or any earlier version. The default version number is 5.0, meaning that functions deprecated in or before Qt 5.0 will not be included.

For instance, when using a future release of Qt 5, set QT_DISABLE_DEPRECATED_BEFORE=0x050100 to disable functions deprecated in Qt 5.1 and earlier. In any release, set QT_DISABLE_DEPRECATED_BEFORE=0x000000 to enable all functions, including the ones deprecated in Qt 5.0.

See also QT_DEPRECATED_WARNINGS.

QT_NO_DEPRECATED_WARNINGS

This macro can be used to suppress deprecation warnings that would otherwise be generated when using deprecated APIs.

This function was introduced in Qt 5.13.

See also QT_DISABLE_DEPRECATED_BEFORE.

QT_POINTER_SIZE

Expands to the size of a pointer in bytes (4 or 8). This is equivalent to sizeof(void *) but can be used in a preprocessor directive.

QT_REQUIRE_VERSION(int argc, char **argv, const char *version)

This macro can be used to ensure that the application is run against a recent enough version of Qt. This is especially useful if your application depends on a specific bug fix introduced in a bug-fix release (e.g., 4.0.2).

The argc and argv parameters are the main() function's argc and argv parameters. The version parameter is a string literal that specifies which version of Qt the application requires (e.g., "4.0.2").

Example:

 #include <QApplication>
 #include <QMessageBox>

 int main(int argc, char *argv[])
 {
     QT_REQUIRE_VERSION(argc, argv, "4.0.2")

     QApplication app(argc, argv);
     ...
     return app.exec();
 }

QT_TRANSLATE_NOOP3(context, sourceText, disambiguation)

Marks the UTF-8 encoded string literal sourceText for delayed translation in the given context with the given disambiguation. The context is typically a class and also needs to be specified as a string literal. The string literal disambiguation should be a short semantic tag to tell apart otherwise identical strings.

The macro tells lupdate to collect the string, and expands to an anonymous struct of the two string literals passed as sourceText and disambiguation.

Example:

 static { const char *source; const char *comment; } greeting_strings[] =
 {
     QT_TRANSLATE_NOOP3("FriendlyConversation", "Hello",
                        "A really friendly hello"),
     QT_TRANSLATE_NOOP3("FriendlyConversation", "Goodbye",
                        "A really friendly goodbye")
 };

 QString FriendlyConversation::greeting(int type)
 {
     return tr(greeting_strings[type].source,
               greeting_strings[type].comment);
 }

 QString global_greeting(int type)
 {
     return qApp->translate("FriendlyConversation",
                            greeting_strings[type].source,
                            greeting_strings[type].comment);
 }

This function was introduced in Qt 4.4.

See also QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and Internationalization with Qt.

QT_TRANSLATE_NOOP(context, sourceText)

Marks the UTF-8 encoded string literal sourceText for delayed translation in the given context. The context is typically a class name and also needs to be specified as a string literal.

The macro tells lupdate to collect the string, and expands to sourceText itself.

Example:

 static const char *greeting_strings[] = {
     QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"),
     QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye")
 };

 QString FriendlyConversation::greeting(int type)
 {
     return tr(greeting_strings[type]);
 }

 QString global_greeting(int type)
 {
     return qApp->translate("FriendlyConversation",
                            greeting_strings[type]);
 }

See also QT_TR_NOOP(), QT_TRANSLATE_NOOP3(), and Internationalization with Qt.

QT_TRANSLATE_N_NOOP3(context, sourceText, comment)

Marks the UTF-8 encoded string literal sourceText for numerator dependent delayed translation in the given context with the given comment. The context is typically a class and also needs to be specified as a string literal. The string literal comment should be a short semantic tag to tell apart otherwise identical strings.

The macro tells lupdate to collect the string, and expands to an anonymous struct of the two string literals passed as sourceText and comment.

Example:

 static { const char * const source; const char * const comment; } status_strings[] = {
     QT_TRANSLATE_N_NOOP3("Message Status", "Hello, you have %n message(s)",
                          "A login message status"),
     QT_TRANSLATE_N_NOOP3("Message status", "You have %n new message(s)",
                          "A new message query status")
 };

 QString FriendlyConversation::greeting(int type, int count)
 {
     return tr(status_strings[type].source,
               status_strings[type].comment, count);
 }

 QString global_greeting(int type, int count)
 {
     return qApp->translate("Message Status",
                            status_strings[type].source,
                            status_strings[type].comment,
                            count);
 }

This function was introduced in Qt 5.12.

See also QT_TR_NOOP(), QT_TRANSLATE_NOOP(), QT_TRANSLATE_NOOP3(), and Internationalization with Qt.

QT_TRANSLATE_N_NOOP(context, sourceText)

Marks the UTF-8 encoded string literal sourceText for numerator dependent delayed translation in the given context. The context is typically a class name and also needs to be specified as a string literal.

The macro tells lupdate to collect the string, and expands to sourceText itself.

Example:

 static const char * const greeting_strings[] = {
     QT_TRANSLATE_N_NOOP("Welcome Msg", "Hello, you have %n message(s)"),
     QT_TRANSLATE_N_NOOP("Welcome Msg", "Hi, you have %n message(s)")
 };

 QString global_greeting(int type, int msgcnt)
 {
     return translate("Welcome Msg", greeting_strings[type], nullptr, msgcnt);
 }

This function was introduced in Qt 5.12.

See also QT_TRANSLATE_NOOP(), QT_TRANSLATE_N_NOOP3(), and Internationalization with Qt.

QT_TRID_NOOP(id)

The QT_TRID_NOOP macro marks an id for dynamic translation.

The only purpose of this macro is to provide an anchor for attaching meta data like to qtTrId().

The macro expands to id.

Example:

 static const char * const ids[] = {
     //% "This is the first text."
     QT_TRID_NOOP("qtn_1st_text"),
     //% "This is the second text."
     QT_TRID_NOOP("qtn_2nd_text"),
     0
 };

 void TheClass::addLabels()
 {
     for (int i = 0; ids[i]; ++i)
         new QLabel(qtTrId(ids[i]), this);
 }

This function was introduced in Qt 4.6.

See also qtTrId() and Internationalization with Qt.

QT_TR_NOOP(sourceText)

Marks the UTF-8 encoded string literal sourceText for delayed translation in the current context (class).

The macro tells lupdate to collect the string, and expands to sourceText itself.

Example:

 QString FriendlyConversation::greeting(int type)
 {
     static const char *greeting_strings[] = {
         QT_TR_NOOP("Hello"),
         QT_TR_NOOP("Goodbye")
     };
     return tr(greeting_strings[type]);
 }

The macro QT_TR_NOOP_UTF8() is identical and obsolete; this applies to all other _UTF8 macros as well.

See also QT_TRANSLATE_NOOP() and Internationalization with Qt.

QT_TR_N_NOOP(sourceText)

Marks the UTF-8 encoded string literal sourceText for numerator dependent delayed translation in the current context (class).

The macro tells lupdate to collect the string, and expands to sourceText itself.

The macro expands to sourceText.

Example:

 static const char * const StatusClass::status_strings[] = {
     QT_TR_N_NOOP("There are %n new message(s)"),
     QT_TR_N_NOOP("There are %n total message(s)")
 };

 QString StatusClass::status(int type, int count)
 {
     return tr(status_strings[type], nullptr, count);
 }

This function was introduced in Qt 5.12.

See also QT_TR_NOOP and Internationalization with Qt.

QT_VERSION

This macro expands a numeric value of the form 0xMMNNPP (MM = major, NN = minor, PP = patch) that specifies Qt's version number. For example, if you compile your application against Qt 4.1.2, the QT_VERSION macro will expand to 0x040102.

You can use QT_VERSION to use the latest Qt features where available.

Example:

 #if QT_VERSION >= 0x040100
     QIcon icon = style()->standardIcon(QStyle::SP_TrashIcon);
 #else
     QPixmap pixmap = style()->standardPixmap(QStyle::SP_TrashIcon);
     QIcon icon(pixmap);
 #endif

See also QT_VERSION_STR and qVersion().

QT_VERSION_CHECK

Turns the major, minor and patch numbers of a version into an integer, 0xMMNNPP (MM = major, NN = minor, PP = patch). This can be compared with another similarly processed version id.

Example:

 #include <QtGlobal>

 #if (QT_VERSION >= QT_VERSION_CHECK(5, 0, 0))
 #include <QtWidgets>
 #else
 #include <QtGui>
 #endif

See also QT_VERSION.

QT_VERSION_STR

This macro expands to a string that specifies Qt's version number (for example, "4.1.2"). This is the version against which the application is compiled.

See also qVersion() and QT_VERSION.

void Q_ASSERT(bool test)

Prints a warning message containing the source code file name and line number if test is false.

Q_ASSERT() is useful for testing pre- and post-conditions during development. It does nothing if QT_NO_DEBUG was defined during compilation.

Example:

 // File: div.cpp

 #include <QtGlobal>

 int divide(int a, int b)
 {
     Q_ASSERT(b != 0);
     return a / b;
 }

If b is zero, the Q_ASSERT statement will output the following message using the qFatal() function:

 ASSERT: "b != 0" in file div.cpp, line 7

See also Q_ASSERT_X(), qFatal(), and Debugging Techniques.

void Q_ASSERT_X(bool test, const char *where, const char *what)

Prints the message what together with the location where, the source file name and line number if test is false.

Q_ASSERT_X is useful for testing pre- and post-conditions during development. It does nothing if QT_NO_DEBUG was defined during compilation.

Example:

 // File: div.cpp

 #include <QtGlobal>

 int divide(int a, int b)
 {
     Q_ASSERT_X(b != 0, "divide", "division by zero");
     return a / b;
 }

If b is zero, the Q_ASSERT_X statement will output the following message using the qFatal() function:

 ASSERT failure in divide: "division by zero", file div.cpp, line 7

See also Q_ASSERT(), qFatal(), and Debugging Techniques.

void Q_ASSUME(bool expr)

Causes the compiler to assume that expr is true. This macro is useful for improving code generation, by providing the compiler with hints about conditions that it would not otherwise know about. However, there is no guarantee that the compiler will actually use those hints.

This macro could be considered a "lighter" version of Q_ASSERT(). While Q_ASSERT will abort the program's execution if the condition is false, Q_ASSUME will tell the compiler not to generate code for those conditions. Therefore, it is important that the assumptions always hold, otherwise undefined behaviour may occur.

If expr is a constantly false condition, Q_ASSUME will tell the compiler that the current code execution cannot be reached. That is, Q_ASSUME(false) is equivalent to Q_UNREACHABLE().

In debug builds the condition is enforced by an assert to facilitate debugging.

Note: Q_LIKELY() tells the compiler that the expression is likely, but not the only possibility. Q_ASSUME tells the compiler that it is the only possibility.

This function was introduced in Qt 5.0.

See also Q_ASSERT(), Q_UNREACHABLE(), and Q_LIKELY().

Q_BIG_ENDIAN

This macro represents a value you can compare to the macro Q_BYTE_ORDER to determine the endian-ness of your system. In a big-endian system, the most significant byte is stored at the lowest address. The other bytes follow in decreasing order of significance.

 #if Q_BYTE_ORDER == Q_BIG_ENDIAN
 ...
 #endif

See also Q_BYTE_ORDER and Q_LITTLE_ENDIAN.

Q_BYTE_ORDER

This macro can be used to determine the byte order your system uses for storing data in memory. i.e., whether your system is little-endian or big-endian. It is set by Qt to one of the macros Q_LITTLE_ENDIAN or Q_BIG_ENDIAN. You normally won't need to worry about endian-ness, but you might, for example if you need to know which byte of an integer or UTF-16 character is stored in the lowest address. Endian-ness is important in networking, where computers with different values for Q_BYTE_ORDER must pass data back and forth.

Use this macro as in the following examples.

 #if Q_BYTE_ORDER == Q_BIG_ENDIAN
 ...
 #endif

 or

 #if Q_BYTE_ORDER == Q_LITTLE_ENDIAN
 ...
 #endif

See also Q_BIG_ENDIAN and Q_LITTLE_ENDIAN.

Q_CC_BOR

Defined if the application is compiled using Borland/Turbo C++.

Q_CC_CDS

Defined if the application is compiled using Reliant C++.

Q_CC_CLANG

Defined if the application is compiled using Clang.

Q_CC_COMEAU

Defined if the application is compiled using Comeau C++.

Q_CC_DEC

Defined if the application is compiled using DEC C++.

Q_CC_EDG

Defined if the application is compiled using Edison Design Group C++.

Q_CC_GHS

Defined if the application is compiled using Green Hills Optimizing C++ Compilers.

Q_CC_GNU

Defined if the application is compiled using GNU C++.

Q_CC_HIGHC

Defined if the application is compiled using MetaWare High C/C++.

Q_CC_HPACC

Defined if the application is compiled using HP aC++.

Q_CC_INTEL

Defined if the application is compiled using Intel C++ for Linux, Intel C++ for Windows.

Q_CC_KAI

Defined if the application is compiled using KAI C++.

Q_CC_MIPS

Defined if the application is compiled using MIPSpro C++.

Q_CC_MSVC

Defined if the application is compiled using Microsoft Visual C/C++, Intel C++ for Windows.

Q_CC_OC

Defined if the application is compiled using CenterLine C++.

Q_CC_PGI

Defined if the application is compiled using Portland Group C++.

Q_CC_SUN

Defined if the application is compiled using Forte Developer, or Sun Studio C++.

Q_CC_SYM

Defined if the application is compiled using Digital Mars C/C++ (used to be Symantec C++).

Q_CC_USLC

Defined if the application is compiled using SCO OUDK and UDK.

Q_CC_WAT

Defined if the application is compiled using Watcom C++.

void Q_CHECK_PTR(void *pointer)

If pointer is nullptr, prints a message containing the source code's file name and line number, saying that the program ran out of memory and aborts program execution. It throws std::bad_alloc instead if exceptions are enabled.

Q_CHECK_PTR does nothing if QT_NO_DEBUG and QT_NO_EXCEPTIONS were defined during compilation. Therefore you must not use Q_CHECK_PTR to check for successful memory allocations because the check will be disabled in some cases.

Example:

 int *a;

 Q_CHECK_PTR(a = new int[80]);   // WRONG!

 a = new (nothrow) int[80];      // Right
 Q_CHECK_PTR(a);

See also qWarning() and Debugging Techniques.

Q_DECLARE_TYPEINFO(Type, Flags)

You can use this macro to specify information about a custom type Type. With accurate type information, Qt's generic containers can choose appropriate storage methods and algorithms.

Flags can be one of the following:

• Q_PRIMITIVE_TYPE specifies that Type is a POD (plain old data) type with no constructor or destructor, or else a type where every bit pattern is a valid object and memcpy() creates a valid independent copy of the object.
• Q_MOVABLE_TYPE specifies that Type has a constructor and/or a destructor but can be moved in memory using memcpy(). Note: despite the name, this has nothing to do with move constructors or C++ move semantics.
• Q_COMPLEX_TYPE (the default) specifies that Type has constructors and/or a destructor and that it may not be moved in memory.

Example of a "primitive" type:

 struct Point2D
 {
     int x;
     int y;
 };

 Q_DECLARE_TYPEINFO(Point2D, Q_PRIMITIVE_TYPE);

An example of a non-POD "primitive" type is QUuid: Even though QUuid has constructors (and therefore isn't POD), every bit pattern still represents a valid object, and memcpy() can be used to create a valid independent copy of a QUuid object.

Example of a movable type:

 class Point2D
 {
 public:
     Point2D() { data = new int[2]; }
     Point2D(const Point2D &other) { ... }
     ~Point2D() { delete[] data; }

     Point2D &operator=(const Point2D &other) { ... }

     int x() const { return data[0]; }
     int y() const { return data[1]; }

 private:
     int *data;
 };

 Q_DECLARE_TYPEINFO(Point2D, Q_MOVABLE_TYPE);

Qt will try to detect the class of a type using std::is_trivial or std::is_trivially_copyable. Use this macro to tune the behavior. For instance many types would be candidates for Q_MOVABLE_TYPE despite not being trivially-copyable. For binary compatibility reasons, QList optimizations are only enabled if there is an explicit Q_DECLARE_TYPEINFO even for trivially-copyable types.

Q_DECL_CONSTEXPR

This macro can be used to declare variable that should be constructed at compile-time, or an inline function that can be computed at compile-time.

It expands to "constexpr" if your compiler supports that C++11 keyword, or to nothing otherwise.

See also Q_DECL_RELAXED_CONSTEXPR.

Q_DECL_EXPORT

This macro marks a symbol for shared library export (see Creating Shared Libraries).

See also Q_DECL_IMPORT.

Q_DECL_IMPORT

This macro declares a symbol to be an import from a shared library (see Creating Shared Libraries).

See also Q_DECL_EXPORT.

Q_DECL_NOEXCEPT

This macro marks a function as never throwing. If the function does nevertheless throw, the behaviour is defined: std::terminate() is called.

The macro expands to C++11 noexcept, if available, or to nothing otherwise.

If you need the operator version of C++11 noexcept, use Q_DECL_NOEXCEPT_EXPR(x).

If you don't need C++11 noexcept semantics, e.g. because your function can't possibly throw, don't use this macro, use Q_DECL_NOTHROW instead.

This function was introduced in Qt 5.0.

See also Q_DECL_NOTHROW and Q_DECL_NOEXCEPT_EXPR().

Q_DECL_NOEXCEPT_EXPR(x)

This macro marks a function as non-throwing if x is true. If the function does nevertheless throw, the behaviour is defined: std::terminate() is called.

The macro expands to C++11 noexcept(x), if available, or to nothing otherwise.

If you need the always-true version of C++11 noexcept, use Q_DECL_NOEXCEPT.

If you don't need C++11 noexcept semantics, e.g. because your function can't possibly throw, don't use this macro, use Q_DECL_NOTHROW instead.

This function was introduced in Qt 5.0.

See also Q_DECL_NOTHROW and Q_DECL_NOEXCEPT.

Q_DECL_NOTHROW

This macro marks a function as never throwing, under no circumstances. If the function does nevertheless throw, the behaviour is undefined.

The macro expands to either "throw()", if that has some benefit on the compiler, or to C++11 noexcept, if available, or to nothing otherwise.

If you need C++11 noexcept semantics, don't use this macro, use Q_DECL_NOEXCEPT/Q_DECL_NOEXCEPT_EXPR instead.

This function was introduced in Qt 5.0.

See also Q_DECL_NOEXCEPT and Q_DECL_NOEXCEPT_EXPR().

Q_DECL_RELAXED_CONSTEXPR

This macro can be used to declare an inline function that can be computed at compile-time according to the relaxed rules from C++14.

It expands to "constexpr" if your compiler supports C++14 relaxed constant expressions, or to nothing otherwise.

See also Q_DECL_CONSTEXPR.

void Q_FALLTHROUGH

Can be used in switch statements at the end of case block to tell the compiler and other developers that that the lack of a break statement is intentional.

This is useful since a missing break statement is often a bug, and some compilers can be configured to emit warnings when one is not found.

This function was introduced in Qt 5.8.

See also Q_UNREACHABLE().

Q_FOREACH(variable, container)

Same as foreach(variable, container).

This macro is available even when no_keywords is specified using the .pro file's CONFIG variable.

Note: Since Qt 5.7, the use of this macro is discouraged. It will be removed in a future version of Qt. Please use C++11 range-for, possibly with qAsConst(), as needed.

See also qAsConst().

Q_FOREVER

Same as forever.

This macro is available even when no_keywords is specified using the .pro file's CONFIG variable.

See also foreach().

Q_FORWARD_DECLARE_CF_TYPE(type)

Forward-declares a Core Foundation type. This includes the actual type and the ref type. For example, Q_FORWARD_DECLARE_CF_TYPE(CFString) declares __CFString and CFStringRef.

This function was introduced in Qt 5.2.

Q_FORWARD_DECLARE_MUTABLE_CF_TYPE(type)

Forward-declares a mutable Core Foundation type. This includes the actual type and the ref type. For example, Q_FORWARD_DECLARE_MUTABLE_CF_TYPE(CFMutableString) declares __CFMutableString and CFMutableStringRef.

This function was introduced in Qt 5.2.

Q_FORWARD_DECLARE_OBJC_CLASS(classname)

Forward-declares an Objective-C classname in a manner such that it can be compiled as either Objective-C or C++.

This is primarily intended for use in header files that may be included by both Objective-C and C++ source files.

This function was introduced in Qt 5.2.

const char*Q_FUNC_INFO

Expands to a string that describe the function the macro resides in. How this string looks more specifically is compiler dependent. With GNU GCC it is typically the function signature, while with other compilers it might be the line and column number.

Q_FUNC_INFO can be conveniently used with qDebug(). For example, this function:

 template<typename TInputType>
 const TInputType &myMin(const TInputType &value1, const TInputType &value2)
 {
     qDebug() << Q_FUNC_INFO << "was called with value1:" << value1 << "value2:" << value2;

     if(value1 < value2)
         return value1;
     else
         return value2;
 }

when instantiated with the integer type, will with the GCC compiler produce:

const TInputType& myMin(const TInputType&, const TInputType&) [with TInputType = int] was called with value1: 3 value2: 4

If this macro is used outside a function, the behavior is undefined.

qint64 Q_INT64_C(literal)

Wraps the signed 64-bit integer literal in a platform-independent way.

Example:

 qint64 value = Q_INT64_C(932838457459459);

See also qint64 and Q_UINT64_C().

Q_LIKELY(expr)

Hints to the compiler that the enclosed condition, expr, is likely to evaluate to true.

Use of this macro can help the compiler to optimize the code.

Example:

     // the condition inside the "if" will be successful most of the times
     for (int i = 1; i <= 365; i++) {
         if (Q_LIKELY(isWorkingDay(i))) {
             ...
         }
         ...
     }

This function was introduced in Qt 4.8.

See also Q_UNLIKELY().

Q_LITTLE_ENDIAN

This macro represents a value you can compare to the macro Q_BYTE_ORDER to determine the endian-ness of your system. In a little-endian system, the least significant byte is stored at the lowest address. The other bytes follow in increasing order of significance.

 #if Q_BYTE_ORDER == Q_LITTLE_ENDIAN
 ...
 #endif

See also Q_BYTE_ORDER and Q_BIG_ENDIAN.

Q_OS_AIX

Defined on AIX.

Q_OS_ANDROID

Defined on Android.

Q_OS_BSD4

Defined on Any BSD 4.4 system.

Q_OS_CYGWIN

Defined on Cygwin.

Q_OS_DARWIN

Defined on Darwin-based operating systems such as macOS, iOS, watchOS, and tvOS.

Q_OS_FREEBSD

Defined on FreeBSD.

Q_OS_HPUX

Defined on HP-UX.

Q_OS_HURD

Defined on GNU Hurd.

Q_OS_IOS

Defined on iOS.

Q_OS_LINUX

Defined on Linux.

Q_OS_LYNX

Defined on LynxOS.

Q_OS_MAC

Deprecated synonym for Q_OS_DARWIN. Do not use.

Q_OS_MACOS

Defined on macOS.

Q_OS_NETBSD

Defined on NetBSD.

Q_OS_OPENBSD

Defined on OpenBSD.

Q_OS_OSX

Deprecated synonym for Q_OS_MACOS. Do not use.

Q_OS_QNX

Defined on QNX Neutrino.

Q_OS_SOLARIS

Defined on Sun Solaris.

Q_OS_TVOS

Defined on tvOS.

Q_OS_UNIX

Defined on Any UNIX BSD/SYSV system.

Q_OS_WASM

Defined on Web Assembly.

Q_OS_WATCHOS

Defined on watchOS.

Q_OS_WIN32

Defined on 32-bit and 64-bit versions of Windows.

Q_OS_WIN64

Defined on 64-bit versions of Windows.

Q_OS_WIN

Defined on all supported versions of Windows. That is, if Q_OS_WIN32, Q_OS_WIN64, or Q_OS_WINRT is defined.

Q_OS_WINDOWS

This is a synonym for Q_OS_WIN.

Q_OS_WINRT

Defined for Windows Runtime (Windows Store apps) on Windows 8, Windows RT, and Windows Phone 8.

Q_PROCESSOR_X86

Defined if the application is compiled for x86 processors. Qt currently supports two x86 variants: Q_PROCESSOR_X86_32 and Q_PROCESSOR_X86_64.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_S390

Defined if the application is compiled for S/390 processors. Qt supports one optional variant of S/390: Q_PROCESSOR_S390_X.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ALPHA

Defined if the application is compiled for Alpha processors.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ARM

Defined if the application is compiled for ARM processors. Qt currently supports three optional ARM revisions: Q_PROCESSOR_ARM_V5, Q_PROCESSOR_ARM_V6, and Q_PROCESSOR_ARM_V7.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ARM_V5

Defined if the application is compiled for ARMv5 processors. The Q_PROCESSOR_ARM macro is also defined when Q_PROCESSOR_ARM_V5 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ARM_V6

Defined if the application is compiled for ARMv6 processors. The Q_PROCESSOR_ARM and Q_PROCESSOR_ARM_V5 macros are also defined when Q_PROCESSOR_ARM_V6 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_ARM_V7

Defined if the application is compiled for ARMv7 processors. The Q_PROCESSOR_ARM, Q_PROCESSOR_ARM_V5, and Q_PROCESSOR_ARM_V6 macros are also defined when Q_PROCESSOR_ARM_V7 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_AVR32

Defined if the application is compiled for AVR32 processors.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_BLACKFIN

Defined if the application is compiled for Blackfin processors.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_IA64

Defined if the application is compiled for IA-64 processors. This includes all Itanium and Itanium 2 processors.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS

Defined if the application is compiled for MIPS processors. Qt currently supports seven MIPS revisions: Q_PROCESSOR_MIPS_I, Q_PROCESSOR_MIPS_II, Q_PROCESSOR_MIPS_III, Q_PROCESSOR_MIPS_IV, Q_PROCESSOR_MIPS_V, Q_PROCESSOR_MIPS_32, and Q_PROCESSOR_MIPS_64.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_32

Defined if the application is compiled for MIPS32 processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, and Q_PROCESSOR_MIPS_II macros are also defined when Q_PROCESSOR_MIPS_32 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_64

Defined if the application is compiled for MIPS64 processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, Q_PROCESSOR_MIPS_II, Q_PROCESSOR_MIPS_III, Q_PROCESSOR_MIPS_IV, and Q_PROCESSOR_MIPS_V macros are also defined when Q_PROCESSOR_MIPS_64 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_I

Defined if the application is compiled for MIPS-I processors. The Q_PROCESSOR_MIPS macro is also defined when Q_PROCESSOR_MIPS_I is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_II

Defined if the application is compiled for MIPS-II processors. The Q_PROCESSOR_MIPS and Q_PROCESSOR_MIPS_I macros are also defined when Q_PROCESSOR_MIPS_II is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_III

Defined if the application is compiled for MIPS-III processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, and Q_PROCESSOR_MIPS_II macros are also defined when Q_PROCESSOR_MIPS_III is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_IV

Defined if the application is compiled for MIPS-IV processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, Q_PROCESSOR_MIPS_II, and Q_PROCESSOR_MIPS_III macros are also defined when Q_PROCESSOR_MIPS_IV is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_MIPS_V

Defined if the application is compiled for MIPS-V processors. The Q_PROCESSOR_MIPS, Q_PROCESSOR_MIPS_I, Q_PROCESSOR_MIPS_II, Q_PROCESSOR_MIPS_III, and Q_PROCESSOR_MIPS_IV macros are also defined when Q_PROCESSOR_MIPS_V is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_POWER

Defined if the application is compiled for POWER processors. Qt currently supports two Power variants: Q_PROCESSOR_POWER_32 and Q_PROCESSOR_POWER_64.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_POWER_32

Defined if the application is compiled for 32-bit Power processors. The Q_PROCESSOR_POWER macro is also defined when Q_PROCESSOR_POWER_32 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_POWER_64

Defined if the application is compiled for 64-bit Power processors. The Q_PROCESSOR_POWER macro is also defined when Q_PROCESSOR_POWER_64 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_RISCV

Defined if the application is compiled for RISC-V processors. Qt currently supports two RISC-V variants: Q_PROCESSOR_RISCV_32 and Q_PROCESSOR_RISCV_64.

This function was introduced in Qt 5.13.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_RISCV_32

Defined if the application is compiled for 32-bit RISC-V processors. The Q_PROCESSOR_RISCV macro is also defined when Q_PROCESSOR_RISCV_32 is defined.

This function was introduced in Qt 5.13.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_RISCV_64

Defined if the application is compiled for 64-bit RISC-V processors. The Q_PROCESSOR_RISCV macro is also defined when Q_PROCESSOR_RISCV_64 is defined.

This function was introduced in Qt 5.13.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_S390_X

Defined if the application is compiled for S/390x processors. The Q_PROCESSOR_S390 macro is also defined when Q_PROCESSOR_S390_X is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_SH

Defined if the application is compiled for SuperH processors. Qt currently supports one SuperH revision: Q_PROCESSOR_SH_4A.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_SH_4A

Defined if the application is compiled for SuperH 4A processors. The Q_PROCESSOR_SH macro is also defined when Q_PROCESSOR_SH_4A is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_SPARC

Defined if the application is compiled for SPARC processors. Qt currently supports one optional SPARC revision: Q_PROCESSOR_SPARC_V9.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_SPARC_V9

Defined if the application is compiled for SPARC V9 processors. The Q_PROCESSOR_SPARC macro is also defined when Q_PROCESSOR_SPARC_V9 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_X86_32

Defined if the application is compiled for 32-bit x86 processors. This includes all i386, i486, i586, and i686 processors. The Q_PROCESSOR_X86 macro is also defined when Q_PROCESSOR_X86_32 is defined.

See also QSysInfo::buildCpuArchitecture().

Q_PROCESSOR_X86_64

Defined if the application is compiled for 64-bit x86 processors. This includes all AMD64, Intel 64, and other x86_64/x64 processors. The Q_PROCESSOR_X86 macro is also defined when Q_PROCESSOR_X86_64 is defined.

See also QSysInfo::buildCpuArchitecture().

quint64 Q_UINT64_C(literal)

Wraps the unsigned 64-bit integer literal in a platform-independent way.

Example:

 quint64 value = Q_UINT64_C(932838457459459);

See also quint64 and Q_INT64_C().

Q_UNLIKELY(expr)

Hints to the compiler that the enclosed condition, expr, is likely to evaluate to false.

Use of this macro can help the compiler to optimize the code.

Example:

 bool readConfiguration(const QFile &file)
 {
     // We expect to be asked to read an existing file
     if (Q_UNLIKELY(!file.exists())) {
         qWarning() << "File not found";
         return false;
     }

     ...
     return true;
 }

This function was introduced in Qt 4.8.

See also Q_LIKELY().

void Q_UNREACHABLE

Tells the compiler that the current point cannot be reached by any execution, so it may optimize any code paths leading here as dead code, as well as code continuing from here.

This macro is useful to mark impossible conditions. For example, given the following enum:

    enum Shapes {
        Rectangle,
        Triangle,
        Circle,
        NumShapes
    };

One can write a switch table like so:

    switch (shape) {
        case Rectangle:
            return rectangle();
        case Triangle:
            return triangle();
        case Circle:
            return circle();
        case NumShapes:
            Q_UNREACHABLE();
            break;
    }

The advantage of inserting Q_UNREACHABLE() at that point is that the compiler is told not to generate code for a shape variable containing that value. If the macro is missing, the compiler will still generate the necessary comparisons for that value. If the case label were removed, some compilers could produce a warning that some enum values were not checked.

By using this macro in impossible conditions, code coverage may be improved as dead code paths may be eliminated.

In debug builds the condition is enforced by an assert to facilitate debugging.

This function was introduced in Qt 5.0.

See also Q_ASSERT(), Q_ASSUME(), and qFatal().

Q_UNUSED(name)

Indicates to the compiler that the parameter with the specified name is not used in the body of a function. This can be used to suppress compiler warnings while allowing functions to be defined with meaningful parameter names in their signatures.

foreach(variable, container)

This macro is used to implement Qt's foreach loop. The variable parameter is a variable name or variable definition; the container parameter is a Qt container whose value type corresponds to the type of the variable. See The foreach Keyword for details.

If you're worried about namespace pollution, you can disable this macro by adding the following line to your .pro file:

 CONFIG += no_keywords

Note: Since Qt 5.7, the use of this macro is discouraged. It will be removed in a future version of Qt. Please use C++11 range-for, possibly with qAsConst(), as needed.

See also qAsConst().

forever

This macro is provided for convenience for writing infinite loops.

Example:

 forever {
     ...
 }

It is equivalent to for (;;).

If you're worried about namespace pollution, you can disable this macro by adding the following line to your .pro file:

 CONFIG += no_keywords

See also Q_FOREVER.

qCritical(const char *message, ...)

Calls the message handler with the critical message message. If no message handler has been installed, the message is printed to stderr. Under Windows, the message is sent to the debugger. On QNX the message is sent to slogger2.

It exits if the environment variable QT_FATAL_CRITICALS is not empty.

This function takes a format string and a list of arguments, similar to the C printf() function. The format should be a Latin-1 string.

Example:

 void load(const QString &fileName)
 {
     QFile file(fileName);
     if (!file.exists())
         qCritical("File '%s' does not exist!", qUtf8Printable(fileName));
 }

If you include <QtDebug>, a more convenient syntax is also available:

 qCritical() << "Brush:" << myQBrush << "Other
 value:" << i;

A space is inserted between the items, and a newline is appended at the end.

To suppress the output at runtime, install your own message handler with qInstallMessageHandler().

Note: This function is thread-safe.

See also qDebug(), qInfo(), qWarning(), qFatal(), qInstallMessageHandler(), and Debugging Techniques.

qDebug(const char *message, ...)

Calls the message handler with the debug message message. If no message handler has been installed, the message is printed to stderr. Under Windows the message is sent to the console, if it is a console application; otherwise, it is sent to the debugger. On QNX, the message is sent to slogger2. This function does nothing if QT_NO_DEBUG_OUTPUT was defined during compilation.

If you pass the function a format string and a list of arguments, it works in similar way to the C printf() function. The format should be a Latin-1 string.

Example:

 qDebug("Items in list: %d", myList.size());

If you include <QtDebug>, a more convenient syntax is also available:

 qDebug() << "Brush:" << myQBrush << "Other value:" << i;

With this syntax, the function returns a QDebug object that is configured to use the QtDebugMsg message type. It automatically puts a single space between each item, and outputs a newline at the end. It supports many C++ and Qt types.

To suppress the output at run-time, install your own message handler with qInstallMessageHandler().

Note: This function is thread-safe.

See also qInfo(), qWarning(), qCritical(), qFatal(), qInstallMessageHandler(), and Debugging Techniques.

qFatal(const char *message, ...)

Calls the message handler with the fatal message message. If no message handler has been installed, the message is printed to stderr. Under Windows, the message is sent to the debugger. On QNX the message is sent to slogger2.

If you are using the default message handler this function will abort to create a core dump. On Windows, for debug builds, this function will report a _CRT_ERROR enabling you to connect a debugger to the application.

This function takes a format string and a list of arguments, similar to the C printf() function.

Example:

 int divide(int a, int b)
 {
     if (b == 0)                                // program error
         qFatal("divide: cannot divide by zero");
     return a / b;
 }

To suppress the output at runtime, install your own message handler with qInstallMessageHandler().

See also qDebug(), qInfo(), qWarning(), qCritical(), qInstallMessageHandler(), and Debugging Techniques.

qInfo(const char *message, ...)

Calls the message handler with the informational message message. If no message handler has been installed, the message is printed to stderr. Under Windows, the message is sent to the console, if it is a console application; otherwise, it is sent to the debugger. On QNX the message is sent to slogger2. This function does nothing if QT_NO_INFO_OUTPUT was defined during compilation.

If you pass the function a format string and a list of arguments, it works in similar way to the C printf() function. The format should be a Latin-1 string.

Example:

 qInfo("Items in list: %d", myList.size());

If you include <QtDebug>, a more convenient syntax is also available:

 qInfo() << "Brush:" << myQBrush << "Other value:" << i;

With this syntax, the function returns a QDebug object that is configured to use the QtInfoMsg message type. It automatically puts a single space between each item, and outputs a newline at the end. It supports many C++ and Qt types.

To suppress the output at run-time, install your own message handler with qInstallMessageHandler().

Note: This function is thread-safe.

This function was introduced in Qt 5.5.

See also qDebug(), qWarning(), qCritical(), qFatal(), qInstallMessageHandler(), and Debugging Techniques.

const char *qPrintable(const QString &str)

Returns str as a const char *. This is equivalent to str.toLocal8Bit().constData().

The char pointer will be invalid after the statement in which qPrintable() is used. This is because the array returned by QString::toLocal8Bit() will fall out of scope.

Note: qDebug(), qInfo(), qWarning(), qCritical(), qFatal() expect %s arguments to be UTF-8 encoded, while qPrintable() converts to local 8-bit encoding. Therefore qUtf8Printable() should be used for logging strings instead of qPrintable().

See also qUtf8Printable().

const wchar_t *qUtf16Printable(const QString &str)

Returns str as a const ushort *, but cast to a const wchar_t * to avoid warnings. This is equivalent to str.utf16() plus some casting.

The only useful thing you can do with the return value of this macro is to pass it to QString::asprintf() for use in a %ls conversion. In particular, the return value is not a valid const wchar_t*!

In general, the pointer will be invalid after the statement in which qUtf16Printable() is used. This is because the pointer may have been obtained from a temporary expression, which will fall out of scope.

Example:

 qWarning("%ls: %ls", qUtf16Printable(key), qUtf16Printable(value));

This function was introduced in Qt 5.7.

See also qPrintable(), qDebug(), qInfo(), qWarning(), qCritical(), and qFatal().

const char *qUtf8Printable(const QString &str)

Returns str as a const char *. This is equivalent to str.toUtf8().constData().

The char pointer will be invalid after the statement in which qUtf8Printable() is used. This is because the array returned by QString::toUtf8() will fall out of scope.

Example:

 qWarning("%s: %s", qUtf8Printable(key), qUtf8Printable(value));

This function was introduced in Qt 5.4.

See also qPrintable(), qDebug(), qInfo(), qWarning(), qCritical(), and qFatal().

qWarning(const char *message, ...)

Calls the message handler with the warning message message. If no message handler has been installed, the message is printed to stderr. Under Windows, the message is sent to the debugger. On QNX the message is sent to slogger2. This function does nothing if QT_NO_WARNING_OUTPUT was defined during compilation; it exits if at the nth warning corresponding to the counter in environment variable QT_FATAL_WARNINGS. That is, if the environment variable contains the value 1, it will exit on the 1st message; if it contains the value 10, it will exit on the 10th message. Any non-numeric value is equivalent to 1.

This function takes a format string and a list of arguments, similar to the C printf() function. The format should be a Latin-1 string.

Example:

 void f(int c)
 {
     if (c > 200)
         qWarning("f: bad argument, c == %d", c);
 }

If you include <QtDebug>, a more convenient syntax is also available:

 qWarning() << "Brush:" << myQBrush << "Other value:"
 << i;

This syntax inserts a space between each item, and appends a newline at the end.

To suppress the output at runtime, install your own message handler with qInstallMessageHandler().

Note: This function is thread-safe.

See also qDebug(), qInfo(), qCritical(), qFatal(), qInstallMessageHandler(), and Debugging Techniques.