Qt Documentation

Contents

Qt WebEngine Features

Qt WebEngine supports the following features:

Audio and Video Codecs

Qt WebEngine supports the MPEG-4 Part 14 (MP4) file format only if the required proprietary audio and video codecs, such as H.264 and MPEG layer-3 (MP3), have been enabled. Proprietary codecs can be enabled by passing the following option to the configure tool when configuring Qt:

-webengine-proprietary-codecs

For example, the following option could be passed when configuring Qt for building it at the top level:

configure -webengine-proprietary-codecs

For more information, see Qt Configure Options.

When using qmake to build just the Qt WebEngine module, the following command can be used (in this example, the Qt WebEngine source code is located in C:\qt\qtwebengine):

qmake C:\qt\qtwebengine -- -webengine-proprietary-codecs

Warning: When distributing proprietary codec libraries, you must acquire licenses for them.

FFmpeg is a cross-platform solution to record, convert, and stream audio and video. It can be configured for use with several codecs, which rises licensing issues during distribution with the codec libraries. For some codecs, open source implementations, such as OpenH264, are available.

Chromium DevTools

The Chromium DevTools provide the ability to inspect and debug layout and performance issues of any web content.

This feature can be tested by launching a Qt WebEngine application with the command line option --remote-debugging-port=[your-port] or by setting the environment variable QTWEBENGINE_REMOTE_DEBUGGING, and then using a Chromium based browser (such as Simple Browser or Nano Browser) to connect to http://localhost:[your-port].

The Chromium DevTools page can also be shown within the application. To set this up, you can call either QWebEnginePage::setInspectedPage() to the page to be inspected, which implicitly loads the DevTools into the this page, or QWebEnginePage::setDevToolsPage() to let the this page be inspected.

The respective QML properties are WebEngineView.devToolsView and WebEngineView.inspectedView.

For more information, see Qt WebEngine Debugging and Profiling.

Client Certificates

Some web servers, in particular many intranet sites, require the client to authenticate itself with a certificate, called a client certificate. Qt WebEngine will read the client certificates installed in the system settings in macOS and Windows, and on Linux those installed into the NSS database. Certificates can be installed into the NSS database using the pk12util tool.

By default, Qt WebEngine will not offer any client certificates to servers, as doing so uniquely identifies the user and might violate privacy expectations.

To activate support for client certificates, an application needs to listen to the QWebEnginePage::selectClientCertificate or WebEngineView.selectClientCertificate signals and select one of the offered certificates. For applications that can navigate to untrusted web sites, it is recommended to always give the user a choice before uniquely identifying them to a remote server.

Custom Schemes

Qt WebEngine makes it possible for the application to define its own custom URL schemes with specialized security policies and transport mechanisms.

Custom schemes can be used to implement alternative network protocols with all the usual web security policies, privileged internal schemes for displaying user interface compoments or debugging information, sandboxed schemes with extra restrictions, and so on.

For more information, see QWebEngineUrlScheme and QWebEngineUrlSchemeHandler.

Drag and Drop

Qt WebEngine supports HTML5 drag and drop.

This feature can be tested by opening an HTML5 drag and drop demo, such as HTML5 Demos - Drag and Drop, HTML5 Demos - Simple Drag and Drop, or HTML5 Demos - Drag and Drop, Automatic Upload, in Simple Browser or Nano Browser.

Dragging files into the browser is not actually part of HTML5, but it is supported. It can be tested by opening HTML5 Demos - File API.

Support for this feature was added in Qt 5.7.0.

Fullscreen

Qt WebEngine supports viewing web content in fullscreen mode. For more information, see WebEngineSettings.fullscreenSupportEnabled, WebEngineView.fullScreenRequested, QWebEngineSettings::FullScreenSupportEnabled, and QWebEnginePage::fullScreenRequested.

This feature can be tested by playing a video from YouTube in Video Player or Nano Browser, and clicking the full screen icon to go into fullscreen mode.

Support for this feature was added in Qt 5.6.0.

HTML5 DRM

Qt WebEngine supports viewing DRM protected videos if the Widevine DRM plugin has been installed.

The video format most commonly used by DRM services, H.264, requires proprietary audio and video codecs. For more information about enabling the codecs, see Audio and Video Codecs.

This feature can be tested by playing a video in Simple Browser or Nano Browser from castLabs, Swank Motion Pictures, Inc., or Shaka Player.

Support for this feature was added in Qt 5.7.0.

HTML5 Geolocation

Qt WebEngine supports JavaScript Geolocation API with Qt Location as a backend. The application has to explicitly allow the feature by using QWebEnginePage::Geolocation or WebEngineView.Feature.

If Qt Location has been built before Qt WebEngine then this feature can be tested by using Maps and allowing it to find the current position of the user. Note that on Windows an external GPS receiver must be connected to the application. For more information, see Qt Positioning.

Support for this feature was added in Qt 5.5.0.

HTTP/2 Protocol

Qt WebEngine supports the Chromium implementation of the HTTP/2 protocol.

This feature can be tested by opening an HTTP/2 demo, such as the Akamai HTTP/2 Demo, in Simple Browser or Nano Browser.

Native Dialogs

A web page might request dialogs for the following functions:

  • Entering user credentials for HTTP and proxy authentication
  • Displaying JavaScript alerts, confirmation dialogs, and prompts
  • Picking colors
  • Selecting files
  • Displaying form validation messages

Qt WebEngine provides standard dialogs for these functions. In widget-based applications, the standard dialogs are based on QDialog, whereas in Qt Quick applications, they can be based either on Qt Quick Controls 1 or Qt Quick Controls 2 (since Qt 5.8). The latter are used only on eglfs platforms.

To explicitly force either dialogs based on Qt Quick Controls 1 or Qt Quick Controls 2, set the QTWEBENGINE_DIALOG_SET environment variable to either QtQuickControls1 or QtQuickControls2.

Qt WebEngine Widgets dialogs can be customized by reimplementing the QWebEnginePage::chooseFiles(), QWebEnginePage::javaScriptAlert(), QWebEnginePage::javaScriptConfirm(), and QWebEnginePage::javaScriptPrompt() functions.

Since Qt 5.8, Qt Quick dialogs can be customized by connecting to the WebEngineView::authenticationDialogRequested(), WebEngineView::javaScriptDialogRequested(), WebEngineView::colorDialogRequested(), WebEngineView::fileDialogRequested(), and WebEngineView::formValidationMessageRequested() signals. For an example, see WebEngine Qt Quick Custom Dialogs Example.

Pepper Plugin API

Qt WebEngine supports loading Pepper Plugin API (PPAPI) plugins if WebEngineSettings::pluginsEnabled or QWebEngineSettings::PluginsEnabled is set.

Except for the Adobe Flash Player plugin, the plugins must be loaded manually using the Chromium command line syntax with the --register-pepper-plugins argument. The argument value is a list of entries, separated by commas, that contain the file path and one or several MIME types, separated by semicolons:

<file-path-plugin1>;<mime-type-plugin1>,<file-path-plugin2>;<mime-type1-plugin2>;<mime-type2-plugin2>

For example:

--register-pepper-plugins="libppapi_example.so;application/x-ppapi-example"

The MIME type is important because it determines which embeds the plugin is used for.

Support for this feature was added in Qt 5.6.0.

Pepper Flash Player Plugin Support

The Pepper Flash player plugin can be loaded automatically if it is installed in one of the following locations, depending on the platform:

  • Windows
    C:\Windows\SysWOW64\Macromed\Flash\pepflashplayer*.dll
C:\Windows\System32\Macromed\Flash\pepflashplayer*.dll
  • OS X
    /Library/Internet Plug-Ins/PepperFlashPlayer/PepperFlashPlayer.plugin
  • Linux
    /usr/lib/pepperflashplugin-nonfree/libpepflashplayer.so
/usr/lib/adobe-flashplugin/libpepflashplayer.so
/usr/lib/PepperFlash/libpepflashplayer.so
/usr/lib64/chromium/PepperFlash/libpepflashplayer.so

You can also load the Pepper Flash player from a specific location by using command line arguments:

--ppapi-flash-path=./libpepflashplayer.so

By default, the Flash version is set to 11.2.999.999. You can use the ppapi-flash-version= argument to set another Flash version in the format major.minor.build.revision:

--ppapi-flash-version=16.0.0.235

This feature can be tested in Simple Browser or Nano Browser if the Adobe Flash PPAPI plugin is installed and plugins are enabled in the browser. To test the feature, the https://helpx.adobe.com/flash-player.html page can be opened in the browser.

PDF File Viewing

Qt WebEngine supports viewing PDF documents by navigating to them. This feature uses the Chromium extensions API and PDF viewer plugin to display the PDF documents. It can be tested in Simple Browser or Nano Browser.

Loading plugins needs to be enabled using QWebEngineSettings::PluginsEnabled or WebEngineSettings::pluginsEnabled in order to use this feature.

This feature can be turned on (default) or off via the QWebEngineSettings::PdfViewerEnabled or WebEngineSettings::pdfViewerEnabled setting.

Support for this feature was added in Qt 5.13.0.

Page Lifecycle API

Qt WebEngine supports the Page Lifecycle API specification, a work-in-progress extension to the HTML standard for allowing user agents to reduce their resource consumption by freezing or discarding background pages. The feature is exposed both in the Widgets and QML APIs.

For an example of the QML API in use, see the WebEngine Lifecycle Example.

Support for this feature was added in Qt 5.14.0.

Overview of Lifecycle States

Each WebEngineView item (or QWebEnginePage object) can be in one of three lifecycle states: active, frozen, or discarded. These states, like the sleep states of a CPU, control the resource usage of web views.

The active state is the normal, unrestricted state of a web view. All visible web views are always in the active state, as are all web views that have not yet finished loading. Only invisible, idle web views can be transitioned to other lifecycle states.

The frozen state is a low CPU usage state. In this state, most HTML task sources are suspended (frozen) and, as a result, most DOM event processing and JavaScript execution will also be suspended. The web view must be invisible in order to be frozen as rendering is not possible in this state.

The discarded state is an extreme resource-saving state. In this state, the browsing context of the web view will be discarded and the corresponding renderer subprocess shut down. CPU and memory usage in this state is reduced virtually to zero. On exiting this state the web page will be automatically reloaded. The process of entering and exiting the discarded state is similar to serializing the browsing history of the web view and destroying the view, then creating a new view and restoring its history.

See also WebEngineView::LifecycleState. The equivalent in the Widgets API is QWebEnginePage::LifecycleState.

The lifecycleState and recommendedState Properties

The lifecycleState property of the WebEngineView type is a read-write property that controls the current lifecycle state of the web view. This property is designed to place as few restrictions as possible on what states can be transitioned to. For example, it is allowed to freeze a web view that is currently playing music in the background, stopping the music. In order to implement a less aggressive resource-saving strategy that avoids interrupting user-visible background activity, the recommendedState property must be used.

The recommendedState property of the WebEngineView type is a read-only property that calculates a safe limit on the lifecycleState property, taking into account the current activity of the web view. So, in the example of a web view playing music in the background, the recommended state will be Active since a more aggressive state would stop the music. If the application wants to avoid interrupting background activity, then it should avoid putting the web view into a more aggressively resource-saving lifecycle state than what's given by recommendedState.

See also WebEngineView::lifecycleState and WebEngineView::recommendedState. The equivalents in the Widgets API are QWebEnginePage::lifecycleState and QWebEnginePage::recommendedState.

The DOM Extensions

The lifecycleState property is connected to the Page Lifecycle API specification, which specifies two new DOM events, freeze and resume, and adds a new Document.wasDiscarded boolean property. The freeze and resume events are fired when transitioning from the Active to the Frozen state, and vice-versa. The Document.wasDiscarded property is set to true when transitioning from the Discarded state to the Active state.

Qt WebEngine supports printing a web page to a PDF file. For more information, see QWebEnginePage::printToPdf() and WebEngineView.printToPdf.

This feature can be tested using Html2Pdf.

Support for this feature was added in Qt 5.7.0.

Process Models

Qt WebEngine uses multiple OS processes to isolate web sites from each other and from the client application, improving security and robustness. The following process models, or ways to divide web sites between OS processes, are supported:

Process per Site Instance

This is the default model. Pages from separate sites are put into separate processes and separate visits to the same site are also isolated.

Two web pages are considered as belonging to the same site if they originate from the same registered domain name (for example, wikipedia.org) and scheme (for example, https). This is similar to the same-origin policy but subdomains are ignored. For example, both https://en.wikipedia.org/ and https://de.wikipedia.org/ would belong to the same site.

A site instance is a collection of web pages belonging to the same site. When the application explicitly loads a URL into Qt WebEngine (via QWebEnginePage::setUrl, for example), a new site instance is created for the page. However, when the user clicks same-site links on the page, the existing site instance is merely extended with more pages.

For instance, in the Simple Browser example, when a user opens two tabs and explicitly enters https://en.wikipedia.org/ into the URL bars, both tabs will have their own separate OS processes (because explicitly entering a URL creates a new site instance). However, when the user then middle-clicks some same-site links to open more tabs, these new tabs will share the same OS process (because user interaction extends the existing site instance).

Process per Site

Pages from separate sites are put into separate processes. Unlike Process per Site Instance, all visits to the same site will share an OS process.

The benefit of this model is reduced memory consumption, because more web pages will share processes. The drawbacks include reduced security, robustness, and responsiveness.

To enable this model, use the command-line argument --process-per-site. See Using Command-Line Arguments.

Single Process

For debugging purposes only, a single process mode can be enabled using the command-line argument --single-process. See Using Command-Line Arguments and Qt WebEngine Debugging and Profiling.

Spellchecker

Qt WebEngine supports integrating spellchecking support into HTML forms to enable users to submit spellchecked messages. When the user clicks on an underlined misspelled word, the default context menu displays up to four suggestions. Selecting one will replace the misspelled word.

To be able to check the spelling, the spellchecker needs dictionaries. It supports dictionaries from the Hunspell project, but they have to be compiled into a special binary format. A Hunspell dictionary consists of two files:

  • A .dic file that is a dictionary containing words for the language
  • An .aff file that defines the meaning of special flags in the dictionary

These two files can be converted into the bdic format by using the qwebengine_convert_dict tool that is shipped together with Qt. When the Qt WebEngine spellchecker initializes, it will try to load the bdict dictionaries and to check them for consistency.

If QTWEBENGINE_DICTIONARIES_PATH is set, the spellchecker uses the dictionaries in the specified directory without looking anywere else. Otherwise, it uses the qtwebengine_dictionaries directory relative to the executable if it exists. If it does not exist, it will look in QT_INSTALL_PREFIX/qtwebengine_dictionaries.

On macOS, depending on how Qt WebEngine is configured at build time, there are two possibilities how spellchecking data is found:

  • Hunspell dictionaries (default) - .bdic dictionaries are used, just like on other platforms
  • Native dictionaries - the macOS spellchecking APIs are used (which means the results will depend on the installed OS dictionaries)

Thus, in the macOS Hunspell case, Qt WebEngine will look in the qtwebengine_dictionaries subdirectory located inside the application bundle Resources directory, and also in the Resources directory located inside the Qt framework bundle.

To summarize, in case of Hunspell usage, the following paths are considered:

Spellchecking is disabled by default and can be enabled per profile by using the QWebEngineProfile::setSpellCheckEnabled() method in widget-based applications and the WebEngineProfile.spellCheckEnabled property in Qt Quick applications.

The current language used for spellchecking is defined per profile, and can be set using the QWebEngineProfile::setSpellCheckLanguages() method or the WebEngineProfile.spellCheckLanguages property.

This feature can be tested by building and running the Spellchecker Example.

Support for this feature was added in Qt 5.8.0.

Touch

Qt WebEngine supports touch devices for navigating and interacting with web pages.

Applications can prohibit the use of touch events in the following ways:

  • Passing the flag --touch-events=disabled on the command line will disable touch event support in JavaScript API (meaning ontouchstart and related handlers will not be present in the document.window object). Touch events will still be delivered to web pages.
  • Installing an event filter object using QObject::installEventFilter on the WebEngine view focus proxy object, and filtering out all touch events.

View Source

Qt WebEngine supports viewing the HTML source of a web page.

This feature can be used from custom menus or assigned to custom events. For more information, see WebEngineView::WebAction, and QWebEnginePage::WebAction.

This feature can be tested by opening a web page in Simple Browser or Nano Browser, and then selecting Page Source in the context menu. The Page Source context menu entry opens the source view in a new tab.

For opening the source view in the current tab, URLs with view-source URI scheme are also supported. For example, you can type the following URL to the URL bar to view the HTML source of the qt.io web page:

view-source:https://www.qt.io/

Auto-completion of incomplete URLs with view-source URI scheme makes the usage of this feature more comfortable. For example, the following incomplete URL also loads the source view of the qt.io web page:

view-source:qt.io

Support for this feature was added in Qt 5.8.0.

WebRTC

WebRTC provides browsers with Real-Time Communications (RTC) capabilities via simple APIs. For more information, see WebEngineView.Feature and QWebEnginePage::Feature.

This feature can be tested by setting up a webcam or microphone and then opening https://test.webrtc.org/ in Simple Browser or Nano Browser.

Web Notifications

Qt WebEngine supports JavaScript Web Notifications API. The application has to explicitly allow the feature by using QWebEnginePage::Notifications or WebEngineView.Notifications.

Support for this feature was added in Qt 5.13.0.

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.