<QtGlobal> - Global Qt Declarations

The <QtGlobal> header file includes the fundamental global declarations. It is included by most other Qt header files. More...

Types

Functions

Macros

The global declarations include types, functions and macros.

The type definitions are partly convenience definitions for basic types (some of which guarantee certain bit-sizes on all platforms supported by Qt), partly types related to Qt message handling. The functions are related to generating messages, Qt version handling and comparing and adjusting object values. And finally, some of the declared macros enable programmers to add compiler or platform specific code to their applications, while others are convenience macros for larger operations.

Types

The header file declares several type definitions that guarantee a specified bit-size on all platforms supported by Qt for various basic types, for example qint8 which is a signed char guaranteed to be 8-bit on all platforms supported by Qt. The header file also declares the qlonglong type definition for long long int (__int64 on Windows).

Several convenience type definitions are declared: qreal for double, uchar for unsigned char, uint forunsigned int, ulong for unsigned long and ushort for unsigned short.

Finally, the QtMsgType definition identifies the various messages that can be generated and sent to a Qt message handler; QtMsgHandler is a type definition for a pointer to a function with the signaturevoid myMsgHandler(QtMsgType, const char *).

Functions

The <QtGlobal> header file contains several functions comparing and adjusting an object's value. These functions take a template type as argument: You can retrieve the absolute value of an object using the qAbs() function, and you can bound a given object's value by given minimum and maximum values using the qBound() function. You can retrieve the minimum and maximum of two given objects using qMin() and qMax() respectively. All these functions return a corresponding template type; the template types can be replaced by any other type.

Example:

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

<QtGlobal> also contains functions that generate messages from the given string argument: qCritical(),qDebug(), qFatal() and qWarning(). These functions call the message handler with the given message.

Example:

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

The remaining functions are qRound() and qRound64(), which both accept a qreal value as their argument returning the value rounded up to the nearest integer and 64-bit integer respectively, theqInstallMsgHandler() function which installs the given QtMsgHandler, and the qVersion() function which returns the version number of Qt at run-time as a string.

Macros

The <QtGlobal> header file provides a range of macros (Q_CC_*) that are defined if the application is compiled using the specified platforms. For example, the Q_CC_SUN macro is defined if the application is compiled using Forte Developer, or Sun Studio C++. The header file also declares a range of macros (Q_OS_*) that are defined for the specified platforms. For example, Q_OS_X11 which is defined for the X Window System.

The purpose of these macros is to enable programmers to add compiler or platform specific code to their application.

The remaining macros are convenience macros for larger operations: The QT_TRANSLATE_NOOP() and QT_TR_NOOP() macros provide the possibility of marking text for dynamic translation, i.e. translation without changing the stored source text. The Q_ASSERT() and Q_ASSERT_X() enables warning messages of various level of refinement. The Q_FOREACH() and foreach() macros implement Qt's foreach loop.

The Q_INT64_C() and Q_UINT64_C() macros wrap signed and unsigned 64-bit integer literals in a platform-independent way. The Q_CHECK_PTR() macro prints a warning containing the source code's file name and line number, saying that the program ran out of memory, if the pointer is 0. TheqPrintable() macro represent an easy way of printing text.

Finally, the QT_POINTER_SIZE macro expands to the size of a pointer in bytes, and the QT_VERSIONand QT_VERSION_STR macros expand to a numeric value or a string, respectively, specifying Qt's version number, i.e the version the application is compiled against.

Type Documentation

typedef QtMsgHandler

This is a typedef for a pointer to a function with the following signature:

 void myMsgHandler(QtMsgType, const char *);

enum QtMsgType

This enum describes the messages that can be sent to a message handler (QtMsgHandler). You can use the enum to identify and associate the various message types with the appropriate actions.

typedef qint8

Typedef for signed char. This type is guaranteed to be 8-bit on all platforms supported by Qt.

typedef qint16

Typedef for signed short. This type is guaranteed to be 16-bit on all platforms supported by Qt.

typedef qint32

Typedef for signed int. This type is guaranteed to be 32-bit on all platforms supported by Qt.

typedef qint64

Typedef for long long int (__int64 on Windows). This type is guaranteed to be 64-bit on all platforms supported by Qt.

Literals of this type can be created using the Q_INT64_C() macro:

 qint64 value = Q_INT64_C(932838457459459);

typedef qlonglong

Typedef for long long int (__int64 on Windows). This is the same as qint64.

typedef qptrdiff

Integral type for representing pointer differences.

Typedef for either qint32 or qint64. This type is guaranteed to be the same size as a pointer on all platforms supported by Qt. On a system with 32-bit pointers, quintptr is a typedef for quint32; on a system with 64-bit pointers, quintptr is a typedef for quint64.

Note that qptrdiff is signed. Use quintptr for unsigned values.

typedef qreal

Typedef for double on all platforms except for those using CPUs with ARM architectures. On ARM-based platforms, qreal is a typedef for float for performance reasons.

typedef quint8

Typedef for unsigned char. This type is guaranteed to be 8-bit on all platforms supported by Qt.

typedef quint16

Typedef for unsigned short. This type is guaranteed to be 16-bit on all platforms supported by Qt.

typedef quint32

Typedef for unsigned int. This type is guaranteed to be 32-bit on all platforms supported by Qt.

typedef quint64

Typedef for unsigned long long int (unsigned __int64 on Windows). This type is guaranteed to be 64-bit on all platforms supported by Qt.

Literals of this type can be created using the Q_UINT64_C() macro:

 quint64 value = Q_UINT64_C(932838457459459);

typedef quintptr

Integral type for representing a pointers (useful for hashing, etc.).

Typedef for either quint32 or quint64. This type is guaranteed to be the same size as a pointer on all platforms supported by Qt. On a system with 32-bit pointers, quintptr is a typedef for quint32; on a system with 64-bit pointers, quintptr is a typedef for quint64.

Note that quintptr is unsigned. Use qptrdiff for signed values.

typedef qulonglong

Typedef for unsigned long long int (unsigned __int64 on Windows). This is the same as quint64.

typedef uchar

Convenience typedef for unsigned char.

typedef uint

Convenience typedef for unsigned int.

typedef ulong

Convenience typedef for unsigned long.

typedef ushort

Convenience typedef for unsigned short.

Function Documentation

T qAbs ( const T & value )

Compares value to the 0 of type T and returns the absolute value. Thus if T is double, then value is compared to (double) 0.

Example:

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

const T & qBound ( const T & min, const T & value, const T & max )

Returns value bounded by min and max. This is equivalent to qMax(min, qMin(value, max)).

Example:

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

See also qMin() and qMax().

void qCritical ( const char * msg, ... )

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

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!", qPrintable(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 qInstallMsgHandler().

void qDebug ( const char * msg, ... )

Calls the message handler with the debug message msg. 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. 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 QtDebugMsgmessage 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 qInstallMsgHandler().

void qFatal ( const char * msg, ... )

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

If you are using the default message handler this function will abort on Unix systems 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 qInstallMsgHandler().

bool qFuzzyCompare ( double p1, double p2 ) [static]

Compares the floating point value p1 and p2 and returns true if they are considered equal, otherwisefalse.

Note that comparing values where either p1 or p2 is 0.0 will not work. The solution to this is to compare against values greater than or equal to 1.0.

         // 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

The two numbers are compared in a relative way, where the exactness is stronger the smaller the numbers are.

Note: This function is thread-safe.

This function was introduced in Qt 4.4.

bool qFuzzyCompare ( float p1, float p2 ) [static]

Compares the floating point value p1 and p2 and returns true if they are considered equal, otherwisefalse.

The two numbers are compared in a relative way, where the exactness is stronger the smaller the numbers are.

Note: This function is thread-safe.

This function was introduced in Qt 4.4.

Installs a Qt message handler which has been defined previously. Returns a pointer to the previous message handler (which may be 0).

The message handler is a function that prints out debug messages, warnings, critical and fatal error messages. The Qt library (debug mode) contains hundreds of warning messages that are printed when internal errors (usually invalid function arguments) occur. Qt built in release mode also contains such warnings unless QT_NO_WARNING_OUTPUT and/or QT_NO_DEBUG_OUTPUT have been set during compilation. If you implement your own message handler, you get total control of these messages.

The default message handler prints the message to the standard output under X11 or to the debugger under Windows. If it is a fatal message, the application aborts immediately.

Only one message handler can be defined, since this is usually done on an application-wide basis to control debug output.

To restore the message handler, call qInstallMsgHandler(0).

Example:

 #include <qapplication.h>   #include <stdio.h>   #include <stdlib.h>     void myMessageOutput(QtMsgType type, const char *msg)   {       switch (type) {       case QtDebugMsg:           fprintf(stderr, "Debug: %s\n", msg);           break;       case QtWarningMsg:           fprintf(stderr, "Warning: %s\n", msg);           break;       case QtCriticalMsg:           fprintf(stderr, "Critical: %s\n", msg);           break;       case QtFatalMsg:           fprintf(stderr, "Fatal: %s\n", msg);           abort();       }   }     int main(int argc, char **argv)   {       qInstallMsgHandler(myMessageOutput);       QApplication app(argc, argv);       ...       return app.exec();   }

int qMacVersion ()

const T & qMax ( const T & value1, const T & value2 )

Returns the maximum of value1 and value2.

Example:

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

See also qMin() and qBound().

const T & qMin ( const T & value1, const T & value2 )

Returns the minimum of value1 and value2.

Example:

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

See also qMax() and qBound().

qint64 qRound64 ( qreal value )

Rounds value to the nearest 64-bit integer.

Example:

 qreal valueA = 42949672960.3;   qreal valueB = 42949672960.7;     int roundedValueA = qRound(valueA);   // roundedValueA = 42949672960   int roundedValueB = qRound(valueB);   // roundedValueB = 42949672961

int qRound ( qreal value )

Rounds value to the nearest integer.

Example:

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

const char * qVersion ()

Returns the version number of Qt at run-time as a string (for example, "4.1.2"). This may be a different version than the version the application was compiled against.

void qWarning ( const char * msg, ... )

Calls the message handler with the warning message msg. If no message handler has been installed, the message is printed to stderr. Under Windows, the message is sent to the debugger. This function does nothing if QT_NO_WARNING_OUTPUT was defined during compilation; it exits if the environment variable QT_FATAL_WARNINGS is defined.

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

T * q_check_ptr ( T * pointer )

Users Q_CHECK_PTR on pointer, then returns pointer.

This can be used as an inline version of Q_CHECK_PTR.

QByteArray qgetenv ( const char * varName )

Returns the value of the environment variable with name varName. To get the variable string, useQByteArray::constData().

Note: qgetenv() was introduced because getenv() from the standard C library was deprecated in VC2005 (and later versions). qgetenv() uses the new replacement function in VC, and calls the standard C library's implementation on all other platforms.

bool qputenv ( const char * varName, const QByteArray & value )

This function sets the value of the environment variable named varName. It will create the variable if it does not exist. It returns 0 if the variable could not be set.

Note: qputenv() was introduced because putenv() from the standard C library was deprecated in VC2005 (and later versions). qputenv() uses the replacement function in VC, and calls the standard C library's implementation on all other platforms.

int qrand ()

Thread-safe version of the standard C++ rand() function.

Returns a value between 0 and RAND_MAX (defined in <cstdlib> and <stdlib.h>), the next number in the current sequence of pseudo-random integers.

Use qsrand() to initialize the pseudo-random number generator with a seed value.

This function was introduced in Qt 4.2.

See also qsrand().

void qsrand ( uint seed )

Thread-safe version of the standard C++ srand() function.

Sets the argument seed to be used to generate a new random number sequence of pseudo random integers to be returned by qrand().

The sequence of random numbers generated is deterministic per thread. For example, if two threads call qsrand(1) and subsequently calls qrand(), the threads will get the same random number sequence.

This function was introduced in Qt 4.2.

See also qrand().

QString qtTrId ( const char * id, int n = -1 )

The qtTrId function finds and returns a translated string.

Returns a translated string identified by id. If no matching string is found, the id itself is returned. This should not happen under normal conditions.

If n >= 0, all occurrences of %n in the resulting string are replaced with a decimal representation of n. In addition, depending on n's value, the translation text may vary.

Meta data and comments can be passed as documented for QObject::tr(). In addition, it is possible to supply a source string template like that:

//% <C string>

or

/*% <C string> */

Example:

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

Creating QM files suitable for use with this function requires passing the -idbased option to thelrelease tool.

Warning: This method is reentrant only if all translators are installed before calling this method. Installing or removing translators while performing translations is not supported. Doing so will probably result in crashes or other undesirable behavior.

Note: This function is reentrant.

This function was introduced in Qt 4.6.

void qt_set_sequence_auto_mnemonic ( bool on )

Enables automatic mnemonics on Mac if on is true; otherwise this feature is disabled.

Note that this function is only available on Mac where mnemonics are disabled by default.

To access to this function, use an extern declaration: extern void qt_set_sequence_auto_mnemonic(bool b);

int qt_symbian_exception2Error ( const std::exception & aThrow )

Convert a caught standard C++ exception aThrow to a Symbian error code

Warning: This function is only available on Symbian.

void qt_symbian_exception2LeaveL ( const std::exception & aThrow )

Convert a caught standard C++ exception aThrow to a Symbian leave

Warning: This function is only available on Symbian.

void qt_symbian_throwIfError ( int error )

Throws an exception if the error parameter is a symbian error code. This is the exception throwing equivalent of Symbian's User::LeaveIfError.

Warning: This function is only available on Symbian.

Macro Documentation

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 versionparameter 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, comment )

Marks the string literal sourceText for dynamic translation in the given context and with comment, i.e the stored sourceText will not be altered. The context is typically a class and also needs to be specified as string literal. The string literal comment will be available for translators using e.g. Qt Linguist.

The macro expands to anonymous struct of the two string literals passed as sourceText and comment.

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.

QT_TRANSLATE_NOOP ( context, sourceText )

Marks the str