1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Encourage use of QT_VERSION_CHECK()

Browse Source 
Document that QT_VERSION should normally be compared against it,
rather than raw hex, and mildly update the example versions used in
docs. (Left the snippets testing old version, since the code in which
the #if-ery is used might actually make sense for those versions.)

Improve related documentation in the process.

Change-Id: Id3e97f41bfb0f81a117cf7b3a3ccd5f244e2a99a
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
This commit is contained in:
Edward Welbourne 2021-09-17 15:04:03 +02:00
parent 7943480f0f
commit 44028a227e
3 changed files with 25 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp
View File

@ -203,7 +203,7 @@ int boundedValue = qBound(minValue, myValue, maxValue);
//! [16]
#if QT_VERSION >= 0x040100
#if QT_VERSION >= QT_VERSION_CHECK(4, 1, 0)
QIcon icon = style()->standardIcon(QStyle::SP_TrashIcon);
#else
QPixmap pixmap = style()->standardPixmap(QStyle::SP_TrashIcon);
@ -718,7 +718,7 @@ bool readConfiguration(const QFile &file)
//! [qt-version-check]
#include <QtGlobal>
#if (QT_VERSION >= QT_VERSION_CHECK(5, 0, 0))
#if QT_VERSION >= QT_VERSION_CHECK(5, 0, 0)
#include <QtWidgets>
#else
#include <QtGui>

32
src/corelib/global/qglobal.cpp
View File

@ -1302,17 +1302,24 @@ static_assert(sizeof(qint64) == 8, "Internal error, qint64 is misdefined");
*/
/*!
\macro QT_VERSION_CHECK
\macro QT_VERSION_CHECK(major, minor, patch)
\relates <QtGlobal>
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.
Turns the \a major, \a minor and \a patch numbers of a version into an
integer that encodes all three. When expressed in hexadecimal, this integer
is of form \c 0xMMNNPP wherein \c{0xMM ==} \a major, \c{0xNN ==} \a minor,
and \c{0xPP ==} \a patch. This can be compared with another similarly
processed version ID.
Example:
\snippet code/src_corelib_global_qglobal.cpp qt-version-check
\note the parameters are read as integers in the normal way, so should
normally be written in decimal (so a \c 0x prefix must be used if writing
them in hexadecimal). Thuse \c{QT_VERSION_CHECK(5, 15, 0)} is equal to \c
0x050e00, which could equally be written \c{QT_VERSION_CHECK(5, 0xe, 0)}.
\sa QT_VERSION
*/
@ -1320,19 +1327,22 @@ static_assert(sizeof(qint64) == 8, "Internal error, qint64 is misdefined");
\macro QT_VERSION
\relates <QtGlobal>
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.
This macro expands to a numeric value of the same form as \l
QT_VERSION_CHECK() constructs, that specifies the version of Qt with which
code using it is compiled. For example, if you compile your application with
Qt 6.1.2, the QT_VERSION macro will expand to \c 0x060102, the same as
\c{QT_VERSION_CHECK(6, 1, 2)}. Note that this need not agree with the
version the application will find itself using at \e runtime.
You can use QT_VERSION to use the latest Qt features where
available.
You can use QT_VERSION to select the latest Qt features where available
while falling back to older implementations otherwise. Using
QT_VERSION_CHECK() for the value to compare with is recommended.
Example:
\snippet code/src_corelib_global_qglobal.cpp 16
\sa QT_VERSION_STR, qVersion()
\sa QT_VERSION_STR, QT_VERSION_CHECK(), qVersion()
*/
/*!

4
src/corelib/global/qglobal.h
View File

@ -53,11 +53,11 @@
#endif
/*
QT_VERSION is (major << 16) + (minor << 8) + patch.
QT_VERSION is (major << 16) | (minor << 8) | patch.
*/
#define QT_VERSION QT_VERSION_CHECK(QT_VERSION_MAJOR, QT_VERSION_MINOR, QT_VERSION_PATCH)
/*
can be used like #if (QT_VERSION >= QT_VERSION_CHECK(4, 4, 0))
can be used like #if (QT_VERSION >= QT_VERSION_CHECK(6, 4, 0))
*/
#define QT_VERSION_CHECK(major, minor, patch) ((major<<16)|(minor<<8)|(patch))