QtWebEngine/Porting from QtWebKit: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 1: Line 1:
[toc align_right="yes" depth="3"]
[toc align_right="yes" depth="3"]


= Porting from Qt WebKit to Qt WebEngine =
= Porting from Qt WebKit to Qt WebEngine =
Line 13: Line 13:
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 |<br />| <code><br />#include &lt;QWebHistory&amp;gt;<br />#include &lt;QWebHistoryItem&amp;gt;<br />#include &lt;QWebPage&amp;gt;<br />#include &lt;QWebView&amp;gt;
|''. Qt WebKit |
<br />QWebHistory<br />QWebHistoryItem<br />QWebPage<br />QWebView<br /></code> |<br />|''. Qt WebEngine |<br />| <code><br />#include &lt;QWebEngineHistory&amp;gt;<br />#include &lt;QWebEngineHistoryItem&amp;gt;<br />#include &lt;QWebEnginePage&amp;gt;<br />#include &lt;QWebEngineView&amp;gt;
| <code>
#include <QWebHistory>
#include <QWebHistoryItem>
#include <QWebPage>
#include <QWebView>


QWebEngineHistory<br />QWebEngineHistoryItem<br />QWebEnginePage<br />QWebEngineView<br /></code> |
QWebHistory
QWebHistoryItem
QWebPage
QWebView
</code> |
|''. Qt WebEngine |
| <code>
#include <QWebEngineHistory>
#include <QWebEngineHistoryItem>
#include <QWebEnginePage>
#include <QWebEngineView>
 
QWebEngineHistory
QWebEngineHistoryItem
QWebEnginePage
QWebEngineView
</code> |


== Qt module name ==
== Qt module name ==
Line 22: Line 42:
=== In qmake project files ===
=== In qmake project files ===


|''. Qt WebKit |<br />| <code><br />QT += webkitwidgets<br /></code> |<br />|''. Qt WebEngine |<br />| <code><br />QT ''= webenginewidgets<br /></code> |
|''. Qt WebKit |
<br />h3. Including the module in source files
| <code>
<br />|''. Qt WebKit |<br />| <code><br />#include &lt;QtWebKit/QtWebKit&amp;gt;<br />#include &lt;QtWebKitWidgets/QtWebKitWidgets&amp;gt; // With Qt &gt;= 4.8<br /></code> |<br />|''. Qt WebEngine |<br />| <code><br />#include &lt;QtWebEngineWidgets/QtWebEngineWidgets&amp;gt;<br /></code> |
QT += webkitwidgets
<br />h2. QWebFrame has been merged into QWebEnginePage
</code> |
<br />It is not possible to access sub-frames. Methods of the main QWebFrame are now available directly through the QWebEnginePage itself.
|''. Qt WebEngine |
<br />|''. Qt WebKit |<br />| <code><br />QWebPage page;<br />connect(page-&gt;mainFrame(), SIGNAL (urlChanged(const QUrl&amp;amp;)), SLOT (mySlotName()));<br />page.mainFrame()<s>&gt;load(url);<br /></code> |<br />|''. Qt WebEngine |<br />| <code><br />QWebEnginePage page;<br />connect(&amp;page, SIGNAL (urlChanged(const QUrl&amp;amp;)), SLOT (mySlotName()));<br />page.load(url);<br /></code> |
| <code>
<br />h2. Some methods now return their result asynchronously
QT ''= webenginewidgets
<br />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.
</code> |
<br />|''. Qt WebKit |<br />| <code><br />QWebPage *page = new QWebPage;<br />QTextEdit *textEdit = new QTextEdit;<br />// *textEdit is modified immediately.<br />textEdit</s>&gt;setPlainText(page-&gt;toHtml());<br />textEdit-&gt;setPlainText(page-&gt;toPlainText());<br /></code> |<br />|''. Qt WebEngine (with a lambda function in C''+11) |<br />| <code><br />QWebEnginePage *page = new QWebEnginePage;<br />QTextEdit *textEdit = new QTextEdit;<br />// *textEdit must remain valid until the lambda function is called.<br />page-&gt;toHtml([textEdit](const QString &amp;result){ textEdit-&gt;setPlainText(result); });<br />page-&gt;toPlainText([textEdit](const QString &amp;result){ textEdit-&gt;setPlainText(result); });<br /></code> |<br />|''. Qt WebEngine (with a functor template wrapping a member function) |<br />| <code><br />template&amp;lt;typename Arg, typename R, typename C&amp;gt;<br />struct InvokeWrapper {<br /> R *receiver;<br /> void (C::*memberFun)(Arg);<br /> void operator()(Arg result) {<br /> (receiver-&gt;*memberFun)(result);<br /> }<br />};
 
<br />template&amp;lt;typename Arg, typename R, typename C&amp;gt;<br />InvokeWrapper&amp;lt;Arg, R, C&amp;gt; invoke(R *receiver, void (C::*memberFun)(Arg))<br />{<br /> InvokeWrapper&amp;lt;Arg, R, C&amp;gt; wrapper = {receiver, memberFun};<br /> return wrapper;<br />}
h3. Including the module in source files
<br />QWebEnginePage *page = new QWebEnginePage;<br />QTextEdit *textEdit = new QTextEdit;<br />// *textEdit must remain valid until the functor is called.<br />page-&gt;toHtml(invoke(textEdit, &amp;QTextEdit::setPlainText));<br />page-&gt;toPlainText(invoke(textEdit, &amp;QTextEdit::setPlainText));<br /></code> |<br />|''. Qt WebEngine (with a regular functor) |<br />| <code><br />struct SetPlainTextFunctor {<br /> QTextEdit *textEdit;<br /> SetPlainTextFunctor(QTextEdit *textEdit) : textEdit(textEdit) { }<br /> void operator()(const QString &amp;result) {<br /> textEdit-&gt;setPlainText(result);<br /> }<br />};
 
|''. Qt WebKit |
| <code>
#include <QtWebKit/QtWebKit>
#include <QtWebKitWidgets/QtWebKitWidgets> // With Qt >= 4.8
</code> |
|''. Qt WebEngine |
| <code>
#include <QtWebEngineWidgets/QtWebEngineWidgets>
</code> |
 
h2. 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 |
| <code>
QWebPage page;
connect(page->mainFrame(), SIGNAL (urlChanged(const QUrl&amp;amp;)), SLOT (mySlotName()));
page.mainFrame()->load(url);
</code> |
|''. Qt WebEngine |
| <code>
QWebEnginePage page;
connect(&amp;page, SIGNAL (urlChanged(const QUrl&amp;amp;)), SLOT (mySlotName()));
page.load(url);
</code> |
 
h2. Some methods now return their result asynchronously
 
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.
 
|''. Qt WebKit |
| <code>
QWebPage *page = new QWebPage;
QTextEdit *textEdit = new QTextEdit;
// *textEdit is modified immediately.
textEdit->setPlainText(page->toHtml());
textEdit->setPlainText(page->toPlainText());
</code> |
|''. 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 &amp;result){ textEdit->setPlainText(result); });
page->toPlainText([textEdit](const QString &amp;result){ textEdit->setPlainText(result); });
</code> |
|''. 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;<br />QTextEdit *textEdit = new QTextEdit;<br />// *textEdit must remain valid until the functor is called.<br />page-&gt;toHtml(SetPlainTextFunctor(textEdit));<br />page-&gt;toPlainText(SetPlainTextFunctor(textEdit));<br /></code> |
QWebEnginePage *page = new QWebEnginePage;
QTextEdit *textEdit = new QTextEdit;
// *textEdit must remain valid until the functor is called.
page->toHtml(invoke(textEdit, &amp;QTextEdit::setPlainText));
page->toPlainText(invoke(textEdit, &amp;QTextEdit::setPlainText));
</code> |
|''. Qt WebEngine (with a regular functor) |
| <code>
struct SetPlainTextFunctor {
QTextEdit *textEdit;
SetPlainTextFunctor(QTextEdit *textEdit) : textEdit(textEdit) { }
void operator()(const QString &amp;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));
</code> |


== Qt WebEngine does not interact with QNetworkAccessManager ==
== Qt WebEngine does not interact with QNetworkAccessManager ==
Line 42: Line 147:
Signals and methods of QNetworkAccessManager that are still supported were moved to QWebEnginePage directly.
Signals and methods of QNetworkAccessManager that are still supported were moved to QWebEnginePage directly.


|''. Qt WebKit |<br />| <code><br />QNetworkAccessManager qnam;<br />QWebPage page;<br />page.setNetworkAccessManager(&amp;qnam);<br />connect(&amp;qnam, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));<br /></code> |<br />|''. Qt WebEngine |<br />| <code><br />QWebEnginePage page;<br />connect(&amp;page, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));<br /></code> |
|''. Qt WebKit |
| <code>
QNetworkAccessManager qnam;
QWebPage page;
page.setNetworkAccessManager(&amp;qnam);
connect(&amp;qnam, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));
</code> |
|''. Qt WebEngine |
| <code>
QWebEnginePage page;
connect(&amp;page, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));
</code> |


== Notes about individual methods ==
== Notes about individual methods ==
Line 50: Line 166:
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 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.


|_. Qt WebKit |<br />| <code><br />QWebPage *page = new QWebPage;<br />qDebug() &lt;&lt; page-&gt;mainFrame()<s>&gt;evaluateJavaScript(&quot;'Java' + 'Script'&quot;);<br /></code> |<br />|_. Qt WebEngine (with lambda expressions in C+''11) |<br />| <code><br />QWebEnginePage *page = new QWebEnginePage;<br />page-&gt;runJavaScript(&quot;'Java''' 'Script'&quot;, [](const QVariant &amp;result){ qDebug() &lt;&lt; result; });<br /></code> |
|_. Qt WebKit |
<br />h3. setHtml and setContent (QWebEnginePage)
| <code>
<br />Those methods now perform asynchronously the same way as a normal HTTP load would.
QWebPage *page = new QWebPage;
<br />h2. Unavailable Qt WebKit APIs
qDebug() << page->mainFrame()->evaluateJavaScript("'Java' + 'Script'");
<br />Qt WebKit classes or methods in this list will not be available in Qt WebEngine.
</code> |
<br />h3. QGraphicsWebView
|_. Qt WebEngine (with lambda expressions in C+''11) |
<br />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.
| <code>
<br />h3. QWebElement
QWebEnginePage *page = new QWebEnginePage;
<br />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.
page->runJavaScript("'Java''' 'Script'", [](const QVariant &amp;result){ qDebug() << result; });
<br />h3. QWebDatabase
</code> |
<br />The Web SQL Database feature that this API was wrapping in QtWebKit was dropped from the HTML5 standard.
 
<br />h3. QWebPluginDatabase, QWebPluginFactory, QWebPluginInfo, QWebPage::setPalette, QWebView::setRenderHints
h3. setHtml and setContent (QWebEnginePage)
<br />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.
 
<br />h3. QWebHistoryInterface
Those methods now perform asynchronously the same way as a normal HTTP load would.
<br />Visited links are persisted automatically by Qt WebEngine.
 
<br />h3. QWebPage::setContentEditable
h2. Unavailable Qt WebKit APIs
<br />In the latest HTML standard, any document element can be made editable through the contentEditable attribute. So runJavaScript is all that is needed.<br />|<code><br />page</s>&gt;runJavascript(&quot;document.documentElement.contentEditable = true&amp;quot;)
 
Qt WebKit classes or methods in this list will not be available in Qt WebEngine.
 
h3. QGraphicsWebView
 
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.
 
h3. QWebDatabase
 
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
 
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
 
Visited links are persisted automatically by Qt WebEngine.
 
h3. 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.
|<code>
page->runJavascript("document.documentElement.contentEditable = true")

Revision as of 08:50, 25 February 2015

[toc align_right="yes" depth="3"]

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

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

|

Qt module name

In qmake project files

|. Qt WebKit |

|

QT += webkitwidgets

|

|. Qt WebEngine |

|

QT ''= webenginewidgets

|

h3. Including the module in source files

|. Qt WebKit |

|

#include <QtWebKit/QtWebKit>
#include <QtWebKitWidgets/QtWebKitWidgets> // With Qt >= 4.8

|

|. Qt WebEngine |

|

#include <QtWebEngineWidgets/QtWebEngineWidgets>

|

h2. 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&amp;amp;)), SLOT (mySlotName()));
page.mainFrame()->load(url);

|

|. Qt WebEngine |

|

QWebEnginePage page;
connect(&amp;page, SIGNAL (urlChanged(const QUrl&amp;amp;)), SLOT (mySlotName()));
page.load(url);

|

h2. Some methods now return their result asynchronously

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.

|. 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 &amp;result){ textEdit->setPlainText(result); });
page->toPlainText([textEdit](const QString &amp;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, &amp;QTextEdit::setPlainText));
page->toPlainText(invoke(textEdit, &amp;QTextEdit::setPlainText));

|

|. Qt WebEngine (with a regular functor) |

|

struct SetPlainTextFunctor {
 QTextEdit *textEdit;
 SetPlainTextFunctor(QTextEdit *textEdit) : textEdit(textEdit) { }
 void operator()(const QString &amp;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 can't go through a QNetworkAccessManager.

Signals and methods of QNetworkAccessManager that are still supported were moved to QWebEnginePage directly.

|. Qt WebKit |

|

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

|

|. Qt WebEngine |

|

QWebEnginePage page;
connect(&amp;page, SIGNAL (authenticationRequired(QNetworkReply*,QAuthenticator*)), this, SLOT (authenticate(QNetworkReply*,QAuthenticator*)));

|

Notes about individual methods

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.

|_. 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 &amp;result){ qDebug() << result; });

|

h3. setHtml and setContent (QWebEnginePage)

Those methods now perform asynchronously the same way as a normal HTTP load would.

h2. Unavailable Qt WebKit APIs

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

h3. QGraphicsWebView

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.

h3. QWebDatabase

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

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

Visited links are persisted automatically by Qt WebEngine.

h3. 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")