From 390391c8138b0138954da0d50537dbb138758bd9 Mon Sep 17 00:00:00 2001
From: Jocelyn Turcotte <jocelyn.turcotte@digia.com>
Date: Fri, 26 Sep 2014 17:24:39 +0200
Subject: [PATCH] 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>
---
.../doc/qtwebenginewidgets.qdocconf | 2 +-
.../doc/src/qtwebenginewidgets.qdoc | 19 ++
.../doc/src/qtwebkitportingguide.qdoc | 275 ++++++++++++++++++
3 files changed, 295 insertions(+), 1 deletion(-)
create mode 100644 src/webenginewidgets/doc/src/qtwebkitportingguide.qdoc
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
+*/
--
GitLab