QtWebEngine/Porting from QtWebKit: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Add "cleanup" tag)
m (Kkoehne moved page Porting from QtWebKit to QtWebEngine to QtWebEngine/Porting from QtWebKit: Let's centralize all pages about webengine as subpages under QtWebEngine)
 
(12 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{Cleanup | reason=Auto-imported from ExpressionEngine.}}
{{WarningBox|text=This guide is work in progress. It will be updated together with the code in the master branch.}}
{{LangSwitch}}
__NOTOC__
This guide gives an overview of the differences between using the Qt WebKit and Qt WebEngine APIs in applications.


[toc align_right="yes" depth="3"]
This guide intends to provide an overview of the steps to follow when porting an application using Qt WebKit's QWebView API to use Qt WebEngine's QWebEngineView.
 
= Porting from Qt WebKit to Qt WebEngine =
 
{color:red}Important: This guide is work in progress. It will be updated together with the code in the master branch.
 
This guide gives an overview of the differences between the Qt WebKit and Qt WebEngine APIs in applications.
 
This intends to provide rough steps to follow when porting an application using Qt WebKit's QWebView API to use Qt WebEngine's QWebEngineView.


== Class names ==
== Class names ==
Line 15: Line 10:
The Qt WebEngine equivalent of Qt WebKit C++ classes are prefixed by '''QWebEngine''' instead of '''QWeb'''.
The Qt WebEngine equivalent of Qt WebKit C++ classes are prefixed by '''QWebEngine''' instead of '''QWeb'''.


|''. Qt WebKit |
{|
! style="text-align:left;"| Qt WebKit
|-
| <code>
| <code>
#include <QWebHistory>
#include <QWebHistory>
Line 26: Line 23:
QWebPage
QWebPage
QWebView
QWebView
</code> |
</code>
|''. Qt WebEngine |
|-
! style="text-align:left;"| Qt WebEngine
|-
| <code>
| <code>
#include <QWebEngineHistory>
#include <QWebEngineHistory>
Line 38: Line 37:
QWebEnginePage
QWebEnginePage
QWebEngineView
QWebEngineView
</code> |
</code>
 
Most of QWebHitTestResult is now available in QWebEngineContextMenuData
|}


== Qt module name ==
== Qt module name ==
Line 44: Line 46:
=== In qmake project files ===
=== In qmake project files ===


|''. Qt WebKit |
{|
! style="text-align:left;"| Qt WebKit
|-
| <code>
| <code>
QT += webkitwidgets
QT += webkitwidgets
</code> |
</code>
|''. Qt WebEngine |
|-
! style="text-align:left;"| Qt WebEngine
|-
| <code>
| <code>
QT ''= webenginewidgets
QT += webenginewidgets
</code> |
</code>
|}


h3. Including the module in source files
=== Including the module in source files ===


|''. Qt WebKit |
{|
! style="text-align:left;"| Qt WebKit
|-
| <code>
| <code>
#include <QtWebKit/QtWebKit>
#include <QtWebKit>
#include <QtWebKitWidgets/QtWebKitWidgets> // With Qt >= 4.8
#include <QtWebKitWidgets> // With Qt >= 4.8
</code> |
</code>
|''. Qt WebEngine |
|-
! style="text-align:left;"| Qt WebEngine
|-
| <code>
| <code>
#include <QtWebEngineWidgets/QtWebEngineWidgets>
#include <QtWebEngineWidgets>
</code> |
</code>
|}


h2. QWebFrame has been merged into QWebEnginePage
== 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.
It is not possible to access sub-frames. Methods of the main QWebFrame are now available directly through the QWebEnginePage itself.


|''. Qt WebKit |
{|
! style="text-align:left;"|Qt WebKit
|-
| <code>
| <code>
QWebPage page;
QWebPage page;
connect(page->mainFrame(), SIGNAL (urlChanged(const QUrl&amp;amp;)), SLOT (mySlotName()));
connect(page->mainFrame(), SIGNAL (urlChanged(const QUrl&)), SLOT (mySlotName()));
page.mainFrame()->load(url);
page.mainFrame()->load(url);
</code> |
</code>
|''. Qt WebEngine |
|-
! style="text-align:left;"| Qt WebEngine
|-
| <code>
| <code>
QWebEnginePage page;
QWebEnginePage page;
connect(&amp;page, SIGNAL (urlChanged(const QUrl&amp;amp;)), SLOT (mySlotName()));
connect(&page, SIGNAL (urlChanged(const QUrl&)), SLOT (mySlotName()));
page.load(url);
page.load(url);
</code> |
</code>
|}


h2. Some methods now return their result asynchronously
== Some methods now return their result asynchronously ==
Because Qt WebEngine uses a multi-process architecture, calls to some methods from applications will return immediately, while the results should be received asynchronously via a callback mechanism. A function pointer, a functor, or a lambda expression must be provided to handle the results when they become available.


Since Qt WebEngine uses a multi-process architecture, the application 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.
{|
 
! style="text-align:left;"| Qt WebKit
|''. Qt WebKit |
|-
| <code>
| <code>
QWebPage *page = new QWebPage;
QWebPage *page = new QWebPage;
Line 93: Line 111:
textEdit->setPlainText(page->toHtml());
textEdit->setPlainText(page->toHtml());
textEdit->setPlainText(page->toPlainText());
textEdit->setPlainText(page->toPlainText());
</code> |
</code>
|''. Qt WebEngine (with a lambda function in C''+11) |
|-
! style="text-align:left;"| Qt WebEngine (with a lambda function in C''++11)
|-
| <code>
| <code>
QWebEnginePage *page = new QWebEnginePage;
QWebEnginePage *page = new QWebEnginePage;
QTextEdit *textEdit = new QTextEdit;
QTextEdit *textEdit = new QTextEdit;
// *textEdit must remain valid until the lambda function is called.
// *textEdit must remain valid until the lambda function is called.
page->toHtml([textEdit](const QString &amp;result){ textEdit->setPlainText(result); });
page->toHtml([textEdit](const QString &result){ textEdit->setPlainText(result); });
page->toPlainText([textEdit](const QString &amp;result){ textEdit->setPlainText(result); });
page->toPlainText([textEdit](const QString &result){ textEdit->setPlainText(result); });
</code> |
</code>  
|''. Qt WebEngine (with a functor template wrapping a member function) |
|-
! style="text-align:left;"|Qt WebEngine (with a functor template wrapping a member function)
|-
| <code>
| <code>
template<typename Arg, typename R, typename C>
template<typename Arg, typename R, typename C>
Line 123: Line 145:
QTextEdit *textEdit = new QTextEdit;
QTextEdit *textEdit = new QTextEdit;
// *textEdit must remain valid until the functor is called.
// *textEdit must remain valid until the functor is called.
page->toHtml(invoke(textEdit, &amp;QTextEdit::setPlainText));
page->toHtml(invoke(textEdit, &QTextEdit::setPlainText));
page->toPlainText(invoke(textEdit, &amp;QTextEdit::setPlainText));
page->toPlainText(invoke(textEdit, &QTextEdit::setPlainText));
</code> |
</code>
|''. Qt WebEngine (with a regular functor) |
|-
! style="text-align:left;"| Qt WebEngine (with a regular functor)
|-
| <code>
| <code>
struct SetPlainTextFunctor {
struct SetPlainTextFunctor {
  QTextEdit *textEdit;
  QTextEdit *textEdit;
  SetPlainTextFunctor(QTextEdit *textEdit) : textEdit(textEdit) { }
  SetPlainTextFunctor(QTextEdit *textEdit) : textEdit(textEdit) { }
  void operator()(const QString &amp;result) {
  void operator()(const QString &result) {
  textEdit->setPlainText(result);
  textEdit->setPlainText(result);
  }
  }
Line 141: Line 165:
page->toHtml(SetPlainTextFunctor(textEdit));
page->toHtml(SetPlainTextFunctor(textEdit));
page->toPlainText(SetPlainTextFunctor(textEdit));
page->toPlainText(SetPlainTextFunctor(textEdit));
</code> |
</code>
|}


== Qt WebEngine does not interact with QNetworkAccessManager ==
== Qt WebEngine does not interact with QNetworkAccessManager ==


Some classes of Qt Network like QAuthenticator were reused for their interface but, unlike Qt WebKit, Qt WebEngine has its own HTTP implementation and can't go through a QNetworkAccessManager.
Some classes of Qt Network like QAuthenticator were reused for their interface but, unlike Qt WebKit, Qt WebEngine has its own HTTP implementation and cannot go through a QNetworkAccessManager.


Signals and methods of QNetworkAccessManager that are still supported were moved to QWebEnginePage directly.
The signals and methods of QNetworkAccessManager that are still supported were moved to the QWebEnginePage class.


|''. Qt WebKit |
{|
! style="text-align:left;"| Qt WebKit
|-
| <code>
| <code>
QNetworkAccessManager qnam;
QNetworkAccessManager qnam;
QWebPage page;
QWebPage page;
page.setNetworkAccessManager(&amp;qnam);
page.setNetworkAccessManager(&qnam);
connect(&amp;qnam, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));
connect(&qnam, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));
</code> |
</code>
|''. Qt WebEngine |
|-
! style="text-align:left;"| Qt WebEngine
|-
| <code>
| <code>
QWebEnginePage page;
QWebEnginePage page;
connect(&amp;page, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));
connect(&page, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));
</code> |
</code>
|}


== Notes about individual methods ==
== Notes about individual methods ==
Line 166: Line 196:
=== runJavaScript (QWebEnginePage) ===
=== runJavaScript (QWebEnginePage) ===


QWebFrame::evaluateJavaScript was renamed and moved to the QWebEnginePage. 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.
QWebFrame::evaluateJavaScript was moved and renamed 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.


|_. Qt WebKit |
{|
! style="text-align:left;"| Qt WebKit
|-
| <code>
| <code>
QWebPage *page = new QWebPage;
QWebPage *page = new QWebPage;
qDebug() << page->mainFrame()->evaluateJavaScript("'Java' + 'Script'");
qDebug() << page->mainFrame()->evaluateJavaScript("'Java' + 'Script'");
</code> |
</code>
|_. Qt WebEngine (with lambda expressions in C+''11) |
|-
! style="text-align:left;"| Qt WebEngine (with lambda expressions in C++11)
|-
| <code>
| <code>
QWebEnginePage *page = new QWebEnginePage;
QWebEnginePage *page = new QWebEnginePage;
page->runJavaScript("'Java''' 'Script'", [](const QVariant &amp;result){ qDebug() << result; });
page->runJavaScript("'Java''' 'Script'", [](const QVariant &result){ qDebug() << result; });
</code> |
</code>
|}


h3. setHtml and setContent (QWebEnginePage)
=== setHtml and setContent (QWebEnginePage) ===
 
The QWebEnginePage::setHtml and QWebEnginePage::setContent methods perform asynchronously the same way as a normal HTTP load would, unlike their QWebPage counterparts.
Those methods now perform asynchronously the same way as a normal HTTP load would.
 
h2. Unavailable Qt WebKit APIs


== Unavailable Qt WebKit APIs ==
Qt WebKit classes or methods in this list will not be available in Qt WebEngine.
Qt WebKit classes or methods in this list will not be available in Qt WebEngine.


h3. QGraphicsWebView
=== QGraphicsWebView ===
 
Qt WebEngine is designed for being used with hardware acceleration. Because we could not support a web view class in a QGraphicsView unless it would be attached to a QGLWidget viewport, this feature is out of scope.
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.
 
h3. QWebElement


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.
=== QWebElement ===
Qt WebEngine uses a 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.


h3. QWebDatabase
=== QWebPage::setLinkDelegationPolicy ===
There is no way to connect a signal to run C++ code when a link is clicked. However, link clicks can be delegated to the Qt application instead of having the HTML handler engine process them by overloading the QWebEnginePage::acceptNavigationRequest() function. This is necessary when an HTML document is used as part of the user interface, and not to display external data, for example, when displaying a list of results.


=== QWebDatabase ===
The Web SQL Database feature that this API was wrapping in QtWebKit was dropped from the HTML5 standard.
The Web SQL Database feature that this API was wrapping in QtWebKit was dropped from the HTML5 standard.


h3. QWebPluginDatabase, QWebPluginFactory, QWebPluginInfo, QWebPage::setPalette, QWebView::setRenderHints
=== QWebPluginDatabase, QWebPluginFactory, QWebPluginInfo, QWebPage::setPalette, QWebView::setRenderHints ===
 
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 QtWebKit.
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 QtWebKit.


h3. QWebHistoryInterface
=== QWebHistoryInterface ===
 
Visited links are persisted automatically by Qt WebEngine.
Visited links are persisted automatically by Qt WebEngine.


h3. QWebPage::setContentEditable
=== QWebPage::setContentEditable ===
 
In the latest HTML standard, any document element can be made editable through the contentEditable attribute. So runJavaScript is all that is needed.
In the latest HTML standard, any document element can be made editable through the contentEditable attribute. So runJavaScript is all that is needed.
|<code>
<code>
page->runJavascript("document.documentElement.contentEditable = true")
page->runJavaScript("document.documentElement.contentEditable = true") </code>

Latest revision as of 09:18, 12 September 2017

This guide is work in progress. It will be updated together with the code in the master branch.

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

This guide gives an overview of the differences between using the Qt WebKit and Qt WebEngine APIs in applications.

This guide intends to provide an overview of the steps to follow when porting an application using Qt WebKit's QWebView API to use Qt WebEngine's QWebEngineView.

Class names

The Qt WebEngine equivalent of Qt WebKit C++ classes are prefixed by QWebEngine instead of QWeb.

Qt WebKit
#include <QWebHistory>
#include <QWebHistoryItem>
#include <QWebPage>
#include <QWebView>

QWebHistory
QWebHistoryItem
QWebPage
QWebView
Qt WebEngine
#include <QWebEngineHistory>
#include <QWebEngineHistoryItem>
#include <QWebEnginePage>
#include <QWebEngineView>

QWebEngineHistory
QWebEngineHistoryItem
QWebEnginePage
QWebEngineView

Most of QWebHitTestResult is now available in QWebEngineContextMenuData

Qt module name

In qmake project files

Qt WebKit
QT += webkitwidgets
Qt WebEngine
QT += webenginewidgets

Including the module in source files

Qt WebKit
#include <QtWebKit>
#include <QtWebKitWidgets> // With Qt >= 4.8
Qt WebEngine
#include <QtWebEngineWidgets>

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.

Qt WebKit
QWebPage page;
connect(page->mainFrame(), SIGNAL (urlChanged(const QUrl&)), SLOT (mySlotName()));
page.mainFrame()->load(url);
Qt WebEngine
QWebEnginePage page;
connect(&page, SIGNAL (urlChanged(const QUrl&)), SLOT (mySlotName()));
page.load(url);

Some methods now return their result asynchronously

Because Qt WebEngine uses a multi-process architecture, calls to some methods from applications will return immediately, while the results should be received asynchronously via a callback mechanism. A function pointer, a functor, or a lambda expression must be provided to handle the results when they become available.

Qt WebKit
QWebPage *page = new QWebPage;
QTextEdit *textEdit = new QTextEdit;
// *textEdit is modified immediately.
textEdit->setPlainText(page->toHtml());
textEdit->setPlainText(page->toPlainText());
Qt WebEngine (with a lambda function in C++11)
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); });
Qt WebEngine (with a functor template wrapping a member function)
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));
Qt WebEngine (with a regular functor)
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));

Qt WebEngine does not interact with QNetworkAccessManager

Some classes of Qt Network like QAuthenticator were reused for their interface but, unlike Qt WebKit, Qt WebEngine has its own HTTP implementation and cannot go through a QNetworkAccessManager.

The signals and methods of QNetworkAccessManager that are still supported were moved to the QWebEnginePage class.

Qt WebKit
QNetworkAccessManager qnam;
QWebPage page;
page.setNetworkAccessManager(&qnam);
connect(&qnam, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));
Qt WebEngine
QWebEnginePage page;
connect(&page, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));

Notes about individual methods

runJavaScript (QWebEnginePage)

QWebFrame::evaluateJavaScript was moved and renamed 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.

Qt WebKit
QWebPage *page = new QWebPage;
qDebug() << page->mainFrame()->evaluateJavaScript("'Java' + 'Script'");
Qt WebEngine (with lambda expressions in C++11)
QWebEnginePage *page = new QWebEnginePage;
page->runJavaScript("'Java''' 'Script'", [](const QVariant &result){ qDebug() << result; });

setHtml and setContent (QWebEnginePage)

The QWebEnginePage::setHtml and QWebEnginePage::setContent methods perform asynchronously the same way as a normal HTTP load would, unlike their QWebPage counterparts.

Unavailable Qt WebKit APIs

Qt WebKit classes or methods in this list will not be available in Qt WebEngine.

QGraphicsWebView

Qt WebEngine is designed for being used with hardware acceleration. Because we could not support a web view class in a QGraphicsView unless it would be attached to a QGLWidget viewport, this feature is out of scope.

QWebElement

Qt WebEngine uses a 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.

QWebPage::setLinkDelegationPolicy

There is no way to connect a signal to run C++ code when a link is clicked. However, link clicks can be delegated to the Qt application instead of having the HTML handler engine process them by overloading the QWebEnginePage::acceptNavigationRequest() function. This is necessary when an HTML document is used as part of the user interface, and not to display external data, for example, when displaying a list of results.

QWebDatabase

The Web SQL Database feature that this API was wrapping in QtWebKit was dropped from the HTML5 standard.

QWebPluginDatabase, QWebPluginFactory, QWebPluginInfo, QWebPage::setPalette, QWebView::setRenderHints

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 QtWebKit.

QWebHistoryInterface

Visited links are persisted automatically by Qt WebEngine.

QWebPage::setContentEditable

In the latest HTML standard, any document element can be made editable through the contentEditable attribute. So runJavaScript is all that is needed.

page->runJavaScript("document.documentElement.contentEditable = true")