Improve documentation on porting from Qt 4 to Qt 5.

Mention the script fixqt4headers.pl, deprecation defines
and explain how to keep the code compatible to both
versions.

Task-number: QTBUG-45662
Change-Id: I1622e2b77fe2b886ffa1e3d42af26a7fbaf9bef0
Reviewed-by: Olivier Goffart (Woboq GmbH) <ogoffart@woboq.com>
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

1 files changed, 27 insertions, 0 deletions

diff --git a/doc/src/portingcppapps_toqt5.qdoc b/doc/src/portingcppapps_toqt5.qdoc
index 6cc062f4..9217217e 100644
--- a/doc/src/portingcppapps_toqt5.qdoc
+++ b/doc/src/portingcppapps_toqt5.qdoc
@@ -37,6 +37,8 @@ port the \l{Animated Tiles Example}{Animated Tiles} application to Qt 5:
    \li Open the Animated Tiles project using Qt Creator.
    \li Edit \c {main.cpp} and replace the \c {#include <QtGui>} instance with
        \c {#include <QtWidgets>}.
+       The Perl-script \c fixqt4headers.pl can be used to scan the source files
+       of a project and perform the replacements.
    \li Edit the \c {animatedtiles.pro} and add \c {QT += widgets} towards the
        end of the file.
        \note \l{Qt GUI} is included by default in all Qt applications unless excluded using the \c {QT -= gui} directive in the \c{qmake} project file.
@@ -61,6 +63,31 @@ step-by-step instructions take you through the changes required to achieve this:
    \li Save changes and run your application.
 \endlist
 
+For larger projects, we recommend initially enabling deprecated API by adding the define
+\code
+DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0
+\endcode
+to the \c{.pro} file. In a second step, the define can be removed.
+
+It is possible to keep the project compiling with Qt 4 and Qt 5. This requires:
+
+\list 1
+   \li Omitting the module name from all includes. This is done by passing
+       the command line option \c --strip-modules to \c fixqt4headers.pl.
+   \li Adding scopes depending on the version of Qt to the \c{.pro} files:
+       \code
+       greaterThan(QT_MAJOR_VERSION, 4): QT += widgets
+       \endcode
+   \li Introducing \c #if scopes around code using modified API:
+       \code
+       #if QT_VERSION >= 0x050000
+           headerView->setSectionResizeMode(QHeaderView::ResizeToContents);
+       #else
+           headerView->setResizeMode(QHeaderView::ResizeToContents);
+       #endif
+       \endcode
+\endlist
+
 \section1 Related Topics
 \list
 \li \l {C++ API Changes}