Using the WebView module with C++ and Qt Widgets

For a long time, developers of Qt-based C++ applications have only had one option for embedding web content: Qt WebEngine. And while it offers a large API with many useful features, the module has its downsides, since it can consume a lot of system resources and increase binary size. For QML users, we’ve had an alternative in the Qt WebView module, but that API had never been exposed to C++ until now.

With Qt 6.11, we released a C++ API for Qt WebView under Technology Preview status. This article is intended to give a brief overview of the usage of the new C++ API and describe the differences with its QML counterpart. While we’ve tried to keep it as close to the existing QML API as possible, some changes have been made, and we’re looking for feedback on its implementation from developers interested in using it.

But first, a brief overview: both WebEngine and WebView are APIs used to embed web content inside your application. But while Qt WebEngine directly embeds a Chromium runtime inside your application, Qt WebView instead acts as a light wrapper around the system-provided web libraries (where those exist; otherwise it wraps WebEngine). This can be quite useful, as it makes your application lighter on resources and ensures you don't need to worry about regularly updating for security fixes; the operating system will always provide you with the latest runtime. The full list of our supported platforms is as follows:

The native APIs we use as backends for Qt WebView work by providing an embeddable window to their users. Therefore, we’ve decided to implement the QWebView class as a subclass of QWindow. The advantage here is that users can decide how they embed the window in their own application. For users of Qt Widgets, the easiest way is to call QWidget::createWindowContainer() like so:

WebView webview;
QWidget *webViewContainer = QWidget::createWindowContainer(webView); 
QBoxLayout layout;
layout.addWidget(webViewContainer);

However, you are also free to use QWindow::setParent() and manually handle positioning if you want to. A detailed description of both approaches can be found in the documentation.

With the window set up and placed in the appropriate location in your app, all you need next is to call setUrl(), and the backend will handle the rest. From then, connecting some buttons to the goBack(), goForward(), reload(), and stop() slots is enough for a barebones web browsing experience. We provide several other signals you can use to ensure the application can detect new navigations, title changes, and new cookies being added. Crucially, we also have the runJavaScript() function to allow for injecting code into web pages, and its resultCallback parameter can be used to extract information from the web content back into C++. For example:

WebView webview;

…

webView.runJavaScript(QString(QLatin1String("document.title")), [](const QVariant &result) { 
    qDebug() << result.toString(); // Print the webpage’s title to the console
});

If you handle the QWebView::loadingChanged() signal you can get access to a QWebViewLoadingInfo object that contains information about the latest load status, its URL, and an error message. This is equivalent to the QML WebViewLoadRequest object, but we decided it needed a more appropriate name for the C++ implementation.

Lastly, you will probably also want to call QWebView::settings() to receive a QWebViewSettings object that allows you to modify the behavior of the current WebView. A single settings object belongs to a single QWebView instance, meaning that you don’t need to worry about its lifetime, and that you can set different settings to concurrently running WebViews.

Unlike in QML, we opted not to add individual properties for every setting. Instead, we have the WebAttribute enumeration describing all possible setting types, and the setAttribute() and testAttribute() functions to modify their values. We currently have four setting types only, which are described here.

We plan to increase development on the Qt WebView module and provide some more feature parity with Qt WebEngine, so we’re interested to hear your feedback on what is important for your use cases. We’d also like to hear your opinions on the current implementation before we take it out of Technical Preview and freeze the API. We invite you to take a look at our bug tracker, and open a ticket if you don’t see one there already.