From 390391c8138b0138954da0d50537dbb138758bd9 Mon Sep 17 00:00:00 2001 From: Jocelyn Turcotte Date: Fri, 26 Sep 2014 17:24:39 +0200 Subject: 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 --- .../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 (limited to 'src/webenginewidgets') 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 + #include + #include + #include + + QWebHistory + QWebHistoryItem + QWebPage + QWebView + \endcode + \b {Qt WebEngine} + \code + #include + #include + #include + #include + + 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 + #include // With Qt >= 4.8 + \endcode + \b {Qt WebEngine} + \code + #include + \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 + struct InvokeWrapper { + R *receiver; + void (C::*memberFun)(Arg); + void operator()(Arg result) { + (receiver->*memberFun)(result); + } + }; + + template + InvokeWrapper invoke(R *receiver, void (C::*memberFun)(Arg)) + { + InvokeWrapper 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 +*/ -- cgit v1.2.3