Import the Qt WebKit porting guide from the wiki

Also added a link to it in a new section briefly explaining the
difference between Qt WebKit and Qt WebEngine.

Change-Id: I89529c701e7f9faae1e4b7d15d5e5d6aec0c8f9f
Reviewed-by: Andras Becsi <andras.becsi@digia.com>

3 files changed, 295 insertions, 1 deletions

diff --git a/src/webenginewidgets/doc/qtwebenginewidgets.qdocconf b/src/webenginewidgets/doc/qtwebenginewidgets.qdocconf
index ad8ed0367..ea7239b2f 100644
--- a/src/webenginewidgets/doc/qtwebenginewidgets.qdocconf
+++ b/src/webenginewidgets/doc/qtwebenginewidgets.qdocconf
@@ -29,7 +29,7 @@ qhp.QtWebEngineWidgets.subprojects.examples.selectors = fake:example
 
 tagfile                 = ../../../doc/qtwebenginewidgets/qtwebenginewidgets.tags
 
-depends += qtcore qtnetwork qtgui qtwidgets qtdoc
+depends += qtwebengine qtcore qtnetwork qtgui qtwidgets qtwebkit qtdoc
 
 headerdirs  += ../api
 sourcedirs  += ../api
diff --git a/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc b/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc
index 2c5791fdd..c2a3ac329 100644
--- a/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc
+++ b/src/webenginewidgets/doc/src/qtwebenginewidgets.qdoc
@@ -66,6 +66,25 @@
     Chromium itself can be found on the \l{http://www.chromium.org}
     {Chromium Project} Web site.
 
+    \section1 Should I use Qt WebEngine or Qt WebKit?
+
+    Qt WebEngine supercedes the \l{Qt WebKit Widgets}{Qt WebKit} module, which
+    was based on the WebKit project, but isn't actively synchronized with the
+    upstream WebKit code since Qt 5.2.
+
+    Chromium provides its own network and painting engines and is developed
+    tightly together with its dependent modules, thus Qt WebEngine provides
+    better and more reliable support for the latest HTML5 specification.
+    For this reason Qt WebEngine is however heavier than Qt WebKit and doesn't
+    give direct access to the network stack and the HTML document through C++ APIs.
+
+    For new code we suggest using Qt WebEngine, but it makes sense to continue
+    using Qt WebKit for applications that are in need of a deeper C++ API than
+    having better and up-to-date support for HTML, CSS and JavaScript features.
+
+    For tips on how to change a Qt WebKit application to use Qt WebEngine, see
+    \l{Porting from Qt WebKit to Qt WebEngine}
+
     \section1 Including In Your Project
 
     To include the definitions of the module's classes, use the
diff --git a/src/webenginewidgets/doc/src/qtwebkitportingguide.qdoc b/src/webenginewidgets/doc/src/qtwebkitportingguide.qdoc
new file mode 100644
index 000000000..af99cb0c0
--- /dev/null
+++ b/src/webenginewidgets/doc/src/qtwebkitportingguide.qdoc
@@ -0,0 +1,275 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtwebenginewidgets-qtwebkitportingguide.html
+    \title Porting from Qt WebKit to Qt WebEngine
+    \brief This guide gives an overview of the differences between the Qt WebKit
+           and Qt WebEngine APIs in applications.
+
+    This provides rough steps to follow when porting an application using
+    Qt WebKit's QWebView API to use Qt WebEngine's QWebEngineView.
+
+
+    \section1 Class Names
+
+    The Qt WebEngine equivalent of Qt WebKit C++ classes are prefixed by
+    "\e QWebEngine" instead of "\e QWeb".
+
+    \b {Qt WebKit}
+    \code
+        #include <QWebHistory>
+        #include <QWebHistoryItem>
+        #include <QWebPage>
+        #include <QWebView>
+
+        QWebHistory
+        QWebHistoryItem
+        QWebPage
+        QWebView
+    \endcode
+    \b {Qt WebEngine}
+    \code
+        #include <QWebEngineHistory>
+        #include <QWebEngineHistoryItem>
+        #include <QWebEnginePage>
+        #include <QWebEngineView>
+
+        QWebEngineHistory
+        QWebEngineHistoryItem
+        QWebEnginePage
+        QWebEngineView
+    \endcode
+
+
+    \section1 Qt Module Name
+
+    \section2 In qmake Project Files
+
+    \b {Qt WebKit}
+    \code
+        QT += webkitwidgets
+    \endcode
+    \b {Qt WebEngine}
+    \code
+        QT += webenginewidgets
+    \endcode
+
+    \section2 Including the Module in Source Files
+
+    \b {Qt WebKit}
+    \code
+        #include <QtWebKit/QtWebKit>
+        #include <QtWebKitWidgets/QtWebKitWidgets> // With Qt >= 4.8
+    \endcode
+    \b {Qt WebEngine}
+    \code
+        #include <QtWebEngineWidgets/QtWebEngineWidgets>
+    \endcode
+
+
+    \section1 QWebFrame has been Merged into QWebEnginePage
+
+    It is not possible to access sub-frames. Methods of the main QWebFrame are
+    now available directly through the QWebEnginePage itself.
+
+    \b {Qt WebKit}
+    \code
+        QWebPage page;
+        connect(page.mainFrame(), SIGNAL(urlChanged(const QUrl&)), SLOT(mySlotName()));
+        page.mainFrame()->load(url);
+    \endcode
+    \b {Qt WebEngine}
+    \code
+        QWebEnginePage page;
+        connect(&page, SIGNAL(urlChanged(const QUrl&)), SLOT(mySlotName()));
+        page.load(url);
+    \endcode
+
+
+    \section1 Some methods now return their result asynchronously
+
+    Since Qt WebEngine uses a multi-process architecture, applications needs
+    to return to the event loop where the result will be received asynchronously
+    from Qt WebEngine's render process. A function pointer, a functor or a lambda
+    expression must be provided to handle the result when it is available.
+
+    \b {Qt WebKit}
+    \code
+        QWebPage *page = new QWebPage;
+        QTextEdit *textEdit = new QTextEdit;
+        // *textEdit is modified immediately.
+        textEdit->setPlainText(page->toHtml());
+        textEdit->setPlainText(page->toPlainText());
+    \endcode
+    \b {Qt WebEngine (with a lambda function in C++11)}
+    \code
+        QWebEnginePage *page = new QWebEnginePage;
+        QTextEdit *textEdit = new QTextEdit;
+        // *textEdit must remain valid until the lambda function is called.
+        page->toHtml([textEdit](const QString &result){ textEdit->setPlainText(result); });
+        page->toPlainText([textEdit](const QString &result){ textEdit->setPlainText(result); });
+    \endcode
+    \b {Qt WebEngine (with a functor template wrapping a member function)}
+    \code
+        template<typename Arg, typename R, typename C>
+        struct InvokeWrapper {
+            R *receiver;
+            void (C::*memberFun)(Arg);
+            void operator()(Arg result) {
+                (receiver->*memberFun)(result);
+            }
+        };
+
+        template<typename Arg, typename R, typename C>
+        InvokeWrapper<Arg, R, C> invoke(R *receiver, void (C::*memberFun)(Arg))
+        {
+            InvokeWrapper<Arg, R, C> wrapper = {receiver, memberFun};
+            return wrapper;
+        }
+
+        QWebEnginePage *page = new QWebEnginePage;
+        QTextEdit *textEdit = new QTextEdit;
+        // *textEdit must remain valid until the functor is called.
+        page->toHtml(invoke(textEdit, &QTextEdit::setPlainText));
+        page->toPlainText(invoke(textEdit, &QTextEdit::setPlainText));
+    \endcode
+    \b {Qt WebEngine (with a regular functor)}
+    \code
+        struct SetPlainTextFunctor {
+            QTextEdit *textEdit;
+            SetPlainTextFunctor(QTextEdit *textEdit) : textEdit(textEdit) { }
+            void operator()(const QString &result) {
+                textEdit->setPlainText(result);
+            }
+        };
+
+        QWebEnginePage *page = new QWebEnginePage;
+        QTextEdit *textEdit = new QTextEdit;
+        // *textEdit must remain valid until the functor is called.
+        page->toHtml(SetPlainTextFunctor(textEdit));
+        page->toPlainText(SetPlainTextFunctor(textEdit));
+    \endcode
+
+
+    \section1 Qt WebEngine does not Interact with QNetworkAccessManager
+
+    Some classes of Qt Network such as QAuthenticator were reused for their interface
+    but, unlike Qt WebKit, Qt WebEngine has its own HTTP implementation and can't
+    go through a QNetworkAccessManager.
+
+    Signals and methods of QNetworkAccessManager that are still supported were
+    moved to QWebEnginePage directly.
+
+    \b {Qt WebKit}
+    \code
+        QNetworkAccessManager qnam;
+        QWebPage page;
+        page.setNetworkAccessManager(&qnam);
+        connect(&qnam, SIGNAL(authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT(authenticate(QNetworkReply*,QAuthenticator*)));
+    \endcode
+    \b {Qt WebEngine}
+    \code
+        QWebEnginePage page;
+        connect(&page, SIGNAL(authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT(authenticate(QNetworkReply*,QAuthenticator*)));
+    \endcode
+
+
+    \section1 Notes about Individual Methods
+
+    \section2 evaluateJavaScript
+
+    QWebFrame::evaluateJavaScript was renamed and moved as QWebEnginePage::runJavaScript.
+    It is currently only possible to run JavaScript on the main frame of a page and the
+    result is returned asynchronously to the provided functor.
+
+    \b {Qt WebKit}
+    \code
+        QWebPage *page = new QWebPage;
+        qDebug() << page->mainFrame()->evaluateJavaScript("'Java' + 'Script'");
+    \endcode
+    \b {Qt WebEngine (with lambda expressions in C++11)}
+    \code
+        QWebEnginePage *page = new QWebEnginePage;
+        page->runJavaScript("'Java' + 'Script'", [](const QVariant &result){ qDebug() << result; });
+    \endcode
+
+    \section2 setHtml and setContent
+
+    QWebEnginePage::setHtml and QWebEnginePage::setContent perform asynchronously
+    the same way as a normal HTTP load would, unlike their QWebPage counterparts.
+
+    \section2 setContentEditable
+
+    QWebPage::setContentEditable has no equivalent since any document element can be made editable through
+    the contentEditable attribute in the latest HTML standard. Therefore, QWebEnginePage::runJavaScript
+    is all that is needed.
+
+    \b {Qt WebKit}
+    \code
+        QWebPage page;
+        page.setContentEditable(true);
+    \endcode
+    \b {Qt WebEngine}
+    \code
+        QWebEnginePage page;
+        page.runJavascript("document.documentElement.contentEditable = true");
+    \endcode
+
+
+    \section1 Unavailable Qt WebKit APIs
+
+    Qt WebKit classes and methods in this list will not be available in Qt WebEngine.
+
+    \table
+    \row
+        \li QGraphicsWebView
+        \li Qt WebEngine requires hardware acceleration. Since we couldn't support
+            a web view class in a QGraphicsView unless it is attached to a QGLWidget
+            viewport, this feature is out of scope.
+    \row
+        \li QWebElement
+        \li Qt WebEngine uses a multi-process architecture and this means that
+            any access to the internal structure of the page has to be done
+            asynchronously, any query result must be returned through callbacks.
+            The QWebElement API was designed for synchronous access and this
+            would require a complete redesign.
+    \row
+        \li QWebDatabase
+        \li The Web SQL Database feature that this API was wrapping in Qt WebKit
+            was dropped from the HTML5 standard.
+    \row
+        \li QWebPluginFactory, QWebPage::setPalette, QWebView::setRenderHints
+        \li Qt WebEngine renders web pages using Skia and isn't using QPainter
+            or Qt for this purpose. The HTML5 standard also now offers much
+            better alternatives that were not available when native controls
+            plugins were introduced in Qt WebKit.
+    \row
+        \li QWebHistoryInterface
+        \li Visited links are persisted automatically by Qt WebEngine.
+    \endtable
+*/