diff options
Diffstat (limited to 'src/core/doc/src/qtwebengine-features.qdoc')
| -rw-r--r-- | src/core/doc/src/qtwebengine-features.qdoc | 777 |
1 files changed, 777 insertions, 0 deletions
diff --git a/src/core/doc/src/qtwebengine-features.qdoc b/src/core/doc/src/qtwebengine-features.qdoc new file mode 100644 index 000000000..9465d75a2 --- /dev/null +++ b/src/core/doc/src/qtwebengine-features.qdoc @@ -0,0 +1,777 @@ +// Copyright (C) 2019 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-features.html + \title Qt WebEngine Features + \ingroup explanations-webtechnologies + + \brief Summarizes \QWE features. + + \QWE supports the following features: + + \list + \li \l{Audio and Video Codecs} + \li \l{WebEngineDriver} + \li \l{Chromium DevTools} + \li \l{Client Certificates} + \li \l{Custom Schemes} + \li \l{Drag and Drop} + \li \l{Favicon} + \li \l{Fullscreen} + \li \l{Hardware Acceleration} + \li \l{HTML5 DRM} + \li \l{HTML5 Geolocation} + \li \l{HTML5 WebSockets} + \li \l{HTTP/2 Protocol} + \li \l{Local Storage} + \li \l{Native Dialogs} + \li \l{PDF File Viewing} + \li \l{Page Lifecycle API} + \li \l{Print to PDF} + \li \l{Process Models} + \li \l{Spellchecker} + \li \l{Touch} + \li \l{View Source} + \li \l{Web Notifications} + \li \l{WebGL} + \li \l{webrtc_feature}{WebRTC} + \endlist + + \section1 Audio and Video Codecs + + \QWE 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 \c configure tool when configuring Qt: + + \badcode + -webengine-proprietary-codecs + \endcode + + For example, the following option could be passed when configuring Qt for + building it at the top level: + + \badcode + configure -webengine-proprietary-codecs + \endcode + + For more information, see \l{Qt Configure Options}. + + When using cmake to build just the \QWE module, the following + command can be used to configure and build (in this example, the \QWE source code is + located in \c {C:\qt\qtwebengine}): + + \badcode + qt-configure-module C:\qt\qtwebengine -webengine-proprietary-codecs + cmake --build . --parallel + \endcode + + \warning When distributing proprietary codec libraries, you must acquire + licenses for them. + + \l 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 \l{OpenH264 Project Homepage} + {OpenH264}, are available. + + \section1 WebEngineDriver + + With WebEngineDriver, you can automate the testing of web sites across browsers. + WebEngineDriver is based on ChromeDriver and can be used the same way. + For more information about ChromeDriver and its use, visit + \l {https://chromedriver.chromium.org/}{ChromeDriver user site}. + + WebEngineDriver has slight modifications compared to ChromeDriver to be able to connect to + \QWE based browsers. It is compatible with \QWE example browsers, such as + \l {WebEngine Widgets Simple Browser Example}{Simple Browser} or + \l{WebEngine Quick Nano Browser}{Nano Browser}. + + The browser automation is scripted through a WebDriver client like the + \l {https://www.selenium.dev/}{Selenium WebDriver}. + For example, WebEngineDriver can be used with the Python lanugage bindings of + Selenium WebDriver: + + \code + from selenium import webdriver + from selenium.webdriver.chrome.service import Service + + service = Service(executable_path='QTDIR/libexec/webenginedriver') + options = webdriver.ChromeOptions() + options.binary_location = 'path/to/browser_binary' + + driver = webdriver.Chrome(service=service, options=options) + driver.get("http://www.google.com/") + driver.quit() + \endcode + + In this example, + \list + \li \c executable_path has to be set to the WebEngineDriver's binary path + \li \c QTDIR is the directory where Qt is installed + \li \c options.binary_location has to be set to the browser's binary path + \endlist + + \note On Windows: \c executable_path='QTDIR/bin/webenginedriver.exe' + + Before executing the script, the \c QTWEBENGINE_REMOTE_DEBUGGING environment variable has to + be set. Its value is a port number what is used by both the browser and WebEngineDriver to + communicate with each other. + \badcode + export QTWEBENGINE_REMOTE_DEBUGGING=12345 + \endcode + + By executing, the script opens the specified web browser and loads the Google web site. + + WebEngineDriver can be also attached to an already running browser if it was started with the + remote debugging port set. \c options.debugger_address has to be set to the remote debugging + address in the script: + + \code + options.debugger_address = 'localhost:12345' + \endcode + + In this case, \c options.binary_location should not be set because the browser is already + running. The environment variable \c QTWEBENGINE_REMOTE_DEBUGGING is not used by the + WebEngineDriver if \c options.debugger_address is set. + + \note WebEngineDriver must be built with the same version of Chromium as \QWE is using. + + \section1 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 \QWE application with the + command line option \c {--remote-debugging-port=[your-port]} or by setting + the environment variable \c QTWEBENGINE_REMOTE_DEBUGGING and then using a + Chromium based browser (such as \l{WebEngine Widgets Simple Browser Example} + {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}) to connect + to \c {http://localhost:[your-port]}. + + \note Any WebEngine command line options should be specified after the + \c {--webEngineArgs} option, which is used to separate the user's application + specific options from the WebEngine's ones. + + \badcode + --webEngineArgs --remote-debugging-port=5000 + \endcode + + To avoid WebSocket errors during remote debugging, add an additional command-line argument + \c {--remote-allow-origins=<origin>[,<origin>, ...]}, where \c <origin> refers to the request origin. + Use \c {--remote-allow-origins=*} to allow connections from all origins. If nothing is specified, + \QWE will add \c {--remote-allow-origins=*} to command-line arguments when remote-debugging is enabled, + thereby allowing requests from all origins. + + 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 \c this page, + or QWebEnginePage::setDevToolsPage() to let the \c this page be inspected. + + The respective QML properties are \l{WebEngineView::devToolsView} + {WebEngineView.devToolsView} and \l{WebEngineView::inspectedView} + {WebEngineView.inspectedView}. + + For more information, see \l {Qt WebEngine Debugging and Profiling}. + + \section1 Client Certificates + + Some web servers, in particular many intranet sites, require the client to + authenticate itself with a certificate, called a \e {client certificate}. \QWE + 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 \c pk12util tool. + + By default, \QWE 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 + \l{WebEngineView::selectClientCertificate}{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. + + In addition to the client certificate stored in system settings, \QWE offers also + the in-memory store. The QWebEngineClientCertificateStore instance can be obtained with + the QWebEngineProfile::clientCertificateStore() method. An application can use this + class to add a new certificate with a QWebEngineClientCertificateStore::add() call. + Note that during the \c selectClientCertificate calls, \QWE lists both system + and in-memory stored clients certificates. + + See also \l{WebEngine Widgets Client Certificate Example}{Client Certificate Example} + for more implementation details. + + \section1 Custom Schemes + + \QWE 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 components or debugging information, sandboxed + schemes with extra restrictions, and so on. + + For more information, see \l QWebEngineUrlScheme and \l + QWebEngineUrlSchemeHandler. + + \section1 Drag and Drop + + \QWE supports HTML5 drag and drop. + + This feature can be tested by opening an HTML5 drag and drop demo, such as + \l{HTML5 Demos - Drag and Drop}, \l{HTML5 Demos - Simple Drag and Drop}, or + \l{HTML5 Demos - Drag and Drop, Automatic Upload}, in \l{WebEngine Widgets + Simple Browser Example}{Simple Browser} or \l{WebEngine Quick Nano Browser} + {Nano Browser}. + + Dragging files into the browser is not actually part of HTML5, but it is + supported. It can be tested by opening \l{HTML5 Demos - File API}. + + Support for this feature was added in Qt 5.7.0. + + \section1 Favicon + + \QWE supports the web site URL icon, \e favicon. Each icon is stored in the internal + database for each \l QWebEngineProfile and can be accessed using a \l QWebEnginePage::icon() + call or a \l {WebEngineView::icon}{WebEngineView.icon} property for the currently loaded content. + + Moreover \QWE provides API for accessing already stored icons in the internal profile's database. + + \note The icon database is not available for off-the-record profiles. + + \section2 QML Favicon Handling + + For accessing icons a \c QQuickImageProvider is registered. This provider can be + accessed by a special URL where the scheme is "image:" and the host is "favicon". + + \qml + Image { + source: "image://favicon/url" + } + \endqml + + The \c url can be the URL of the favicon: + + \qml + Image { + source: "image://favicon/https://www.qt.io/hubfs/2016_Qt_Logo/qt_logo_green_rgb_16x16.png" + } + \endqml + + The \c url also can be a page URL to access its icon: + + \qml + Image { + source: "image://favicon/https://www.qt.io/" + } + \endqml + + If more than one icon is available, the \l {Image::sourceSize} property can be + specified to choose the icon with the desired size. If \l {Image::sourceSize} + is not specified or 0, the largest available icon will be chosen. + + The image provider looks up the requested icon in the existing \l {WebEngineView} + instances. First, it tries to match the currently displayed icons. If no match + has been found it requests the icon from the database. Each profile has its + own icon database and it is stored in the persistent storage thus the stored icons + can be accessed without network connection too. The icon must be previously loaded + to be stored in the database. + + \section2 C++ Favicon Handling + + A user can request an icon from the previously loaded content for each + \l QWebEngineProfile using the \l QWebEngineProfile::requestIconForPageURL() or + \l QWebEngineProfile::requestIconForIconURL() calls. Note that the profile's database is + stored in the persistent storage and can be accessed without a network connection. + + \section1 Fullscreen + + \QWE supports viewing web content in fullscreen mode. For more + information, see \l{WebEngineSettings::fullscreenSupportEnabled} + {WebEngineSettings.fullscreenSupportEnabled}, + \l{WebEngineView::fullScreenRequested}{WebEngineView.fullScreenRequested}, + QWebEngineSettings::FullScreenSupportEnabled, and + QWebEnginePage::fullScreenRequested. + + This feature can be tested by playing a video from YouTube in \l{WebEngine + Widgets Video Player Example}{Video Player} or \l{WebEngine Quick Nano Browser} + {Nano Browser}, and clicking the full screen icon to go into fullscreen + mode. + + Support for this feature was added in Qt 5.6.0. + + \section1 Hardware Acceleration + + QtWebEngine tries to use hardware acceleration for rendering the content. It uses + \c OpenGL or \c OpenGLES APIs to execute rendering calls on the GPU. As a fallback, + software rendering is used whenever the hardware does not meet the required set of + OpenGL functionality. A user can check the current hardware acceleration state by + loading the \c {chrome://gpu} internal page. Moreover, the acceleration can be explicitly + disabled with \c {QTWEBENGINE_CHROMIUM_FLAGS} using the \c {disable-gpu} switch. + For example on Linux: + + \badcode + export QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu + \endcode + + \section1 HTML5 DRM + + \QWE supports viewing DRM protected videos if the \l{Widevine CDM} plugin has been installed. + CDM plugin is a replacement of Flash based plugins for displaying DRM-protected content. + It comes only in a binary format, so it can hide DRM decryption implementation details. + It can be obtained from a third party or from a Google Chrome installation. + + \QWE on startup looks for the \l{Widevine CDM} plugin in well know locations, like + default Google Chrome installation directory or Linux distro specific paths. However, plugin + location can be also passed with \c {QTWEBENGINE_CHROMIUM_FLAGS} using \c {widevine-path}. + + On Windows: + \badcode + set QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="C:/some path/widevinecdm.dll" + \endcode + + On Linux: + \badcode + export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.so" + \endcode + + On macOS: + \badcode + export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.dylib" + \endcode + + + 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 \l{Audio and Video Codecs}. + + This feature can be tested by playing a video in \l{WebEngine Widgets Simple Browser + Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser} + from \l{castLabs}, \l{Swank Motion Pictures, Inc.}, or \l{Bitmovin Player}. + + Support for this feature was added in Qt 5.7.0. + + \section1 HTML5 Geolocation + + \QWE supports JavaScript Geolocation API with \l {Qt Positioning} as a + backend. HTML5 geolocation is disabled by default. To explicitly allow it, the application + needs to listen to QWebEnginePage::featurePermissionRequested. Use QWebEnginePage::Geolocation + with a QWebEnginePage::setFeaturePermission() call or \l{WebEngineView::Feature} + with a \l{WebEngineView::grantFeaturePermission} {WebEngineView.grantFeaturePermission}() call + to grant the required permission. + + If \QWE was built with Qt Positioning support then this feature can be + tested by using \l{WebEngine Widgets Maps Example}{Maps} and allowing it to + find the current position of the user. + + \note On Windows 11, enable settings to grant the maps example access to + Windows location services. In the Settings App under + \uicontrol {Privacy & Security} > \uicontrol {Location}, enable \uicontrol + {Location services}, \uicontrol {Let apps access your location} and \uicontrol + {Let desktop apps access your location}. + + See \l{Qt Positioning} for a possible backend setup like the GPS or IP based positioning. + + Support for this feature was added in Qt 5.5.0. + + \section1 HTML5 WebSockets + + \QWE supports the WebSocket JavaScript API to communicate with WebSocket servers + using the \c {ws://} or \c {wss://} protocols. Moreover, integration with Qt WebChannel + and Qt WebSockets enables communication between JavaScript and the native side of + the application. + + The Qt WebChannel module has a great example for a + \l[QtWebChannel]{Qt WebChannel ChatServer Example}{chat server} + and its web based + \l[QtWebChannel]{Qt WebChannel ChatClient HTML Example}{chat client}. + The client works out of the box in the example browsers of \QWE + (such as \l{WebEngine Widgets Simple Browser Example} + {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}). + + \section1 HTTP/2 Protocol + + \QWE supports the Chromium implementation of the \l{HTTP/2} + protocol. + + This feature can be tested by opening an HTTP/2 demo, such as the + \l{Akamai HTTP/2 Demo}, in \l{WebEngine Widgets Simple Browser Example} + {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}. + + \section1 Local Storage + + \QWE supports saving key-value pairs in a \c {Local Storage} with no expiration date. + This is a part of the \l + {https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API} + {Web Storage API}, where a user can access a \c Storage object for the given domains + using the \c Window.localStorage JavaScript property. The stored data will persist even + after the page or the browser application is closed. + + Note that the \c Local Storage can be also disabled with a + \l QWebEngineSettings::LocalStorageEnabled + setting. Moreover, the storage path can be adjusted with a + \l QWebEngineProfile::setPersistentStoragePath + call. + + \code + QWebEngineProfile profile("MyProfile"); + profile.settings()->setAttribute(QWebEngineSettings::LocalStorageEnabled, isEnabled); + profile.setPersistentStoragePath("/path/to/storage"); + \endcode + + \QWE offers also an easy way of investigating the content of the \c {Local Storage} + with \l {Qt WebEngine Developer Tools} by visiting the \uicontrol Application panel + and expanding the \uicontrol {Local Storage} menu. + + \section1 Native Dialogs + + A web page might request dialogs for the following functions: + + \list + \li Entering user credentials for HTTP and proxy authentication + \li Displaying JavaScript alerts, confirmation dialogs, and prompts + \li Picking colors + \li Selecting files + \li Displaying form validation messages + \endlist + + \QWE 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 \c eglfs platforms. + + To explicitly force either dialogs based on Qt Quick Controls 1 or Qt Quick + Controls 2, set the \c QTWEBENGINE_DIALOG_SET environment variable to either + \c{QtQuickControls1} or \c{QtQuickControls2}. + + \QWE 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, + + \section1 PDF File Viewing + + \QWE 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 \l{WebEngine Widgets Simple Browser Example}{Simple Browser} or + \l{WebEngine Quick Nano Browser}{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. + + \section1 Page Lifecycle API + + \QWE supports the \l {https://wicg.github.io/page-lifecycle/spec.html}{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 \l {WebEngine Lifecycle + Example}. + + Support for this feature was added in Qt 5.14.0. + + \section2 Overview of Lifecycle States + + Each \l {WebEngineView} item (or \l {QWebEnginePage} object) can be in one + of three \e {lifecycle states}: active, frozen, or discarded. These states, + like the sleep states of a CPU, control the resource usage of web views. + + The \e {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 \e {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 \e {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 \l {WebEngineView::LifecycleState}. The equivalent in the Widgets + API is \l {QWebEnginePage::LifecycleState}. + + \section2 The \c {lifecycleState} and \c {recommendedState} Properties + + The \l {WebEngineView::}{lifecycleState} property of the \l {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 \l + {WebEngineView::} {recommendedState} property must be used. + + The \l {WebEngineView::}{recommendedState} property of the \l + {WebEngineView} type is a read-only property that calculates a safe limit on + the \l {WebEngineView::}{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 \c {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 \l {WebEngineView::}{recommendedState}. + + See also \l {WebEngineView::lifecycleState} and \l + {WebEngineView::recommendedState}. The equivalents in the Widgets API are \l + {QWebEnginePage::lifecycleState} and \l {QWebEnginePage::recommendedState}. + + \section2 The DOM Extensions + + The \l {WebEngineView::}{lifecycleState} property is connected to the \l + {https://wicg.github.io/page-lifecycle/spec.html}{Page Lifecycle API + specification}, which specifies two new DOM events, \c {freeze} and \c + {resume}, and adds a new \c {Document.wasDiscarded} boolean property. The \c + {freeze} and \c {resume} events are fired when transitioning from the \c + {Active} to the \c {Frozen state}, and vice-versa. The \c + {Document.wasDiscarded} property is set to \c {true} when transitioning from + the \c {Discarded} state to the \c {Active} state. + + \section1 Print to PDF + + \QWE supports printing a web page to a PDF file. For more + information, see QWebEnginePage::printToPdf() and + \l{WebEngineView::printToPdf}{WebEngineView.printToPdf}. + + This feature can be tested using \l{WebEngine Widgets Html2Pdf Example} + {Html2Pdf}. + + Support for this feature was added in Qt 5.7.0. + + \section1 Process Models + + \QWE 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: + + \list + \li \l{Process per Site Instance} + \li \l{Process per Site} + \li \l{Single Process} + \endlist + + \section2 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, \c wikipedia.org) and + scheme (for example, \c https). This is similar to the same-origin policy + but subdomains are ignored. For example, both \c{https://en.wikipedia.org/} + and \c{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 \QWE (via \l + 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 \l{WebEngine Widgets Simple Browser Example}{Simple + Browser} example, when a user opens two tabs and explicitly enters + \c{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). + + \section2 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 \c{--process-per-site}. + See \l{Using Command-Line Arguments}. + + \section2 Single Process + + For debugging purposes only, a single process mode can be enabled using the + command-line argument \c{--single-process}. See \l{Using Command-Line + Arguments} and \l{Qt WebEngine Debugging and Profiling}. + + \section1 Spellchecker + + \QWE 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 \l{Hunspell project}, but they have to be + compiled into a special binary format. A Hunspell dictionary consists of two + files: + + \list + + \li A \c .dic file that is a dictionary containing words for the + language + \li An \c .aff file that defines the meaning of special flags in the + dictionary + \endlist + + These two files can be converted into the \c bdic format by using the + \c qwebengine_convert_dict tool that is shipped together with Qt. + When the \QWE spellchecker initializes, it will try to load the + \c bdict dictionaries and to check them for consistency. + + If \c QTWEBENGINE_DICTIONARIES_PATH is set, the spellchecker uses the + dictionaries in the specified directory without looking anywere else. + Otherwise, it uses the \e qtwebengine_dictionaries directory relative to the + executable if it exists. If it does not exist, it will look in \c + QT_INSTALL_PREFIX/qtwebengine_dictionaries. + + On macOS, depending on how \QWE is configured at build time, there + are two possibilities how spellchecking data is found: + + \list + \li Hunspell dictionaries (default) - .bdic dictionaries are used, just + like on other platforms + \li Native dictionaries - the macOS spellchecking APIs are used (which + means the results will depend on the installed OS dictionaries) + \endlist + + Thus, in the macOS Hunspell case, \QWE will look in the \e + qtwebengine_dictionaries subdirectory located inside the application bundle + \c Resources directory, and also in the \c Resources directory located + inside the Qt framework bundle. + + To summarize, in case of Hunspell usage, the following paths are considered: + + \list + \li \c QTWEBENGINE_DICTIONARIES_PATH, if set + \li QCoreApplication::applicationDirPath()/qtwebengine_dictionaries + or QCoreApplication::applicationDirPath()/../Contents/Resources/qtwebengine_dictionaries + (on macOS) + \li [QLibraryInfo::DataPath]/qtwebengine_dictionaries + or path/to/QtWebEngineCore.framework/Resources/qtwebengine_dictionaries (Qt framework + bundle on macOS) + \endlist + + Spellchecking is disabled by default and can be enabled per profile by + using the QWebEngineProfile::setSpellCheckEnabled() method in widget-based + applications and the \l {QQuickWebEngineProfile::spellCheckEnabled} + {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 + \l {QQuickWebEngineProfile::spellCheckLanguages} + {WebEngineProfile.spellCheckLanguages} property. + + This feature can be tested by building and running the + \l{WebEngine Widgets Spellchecker Example}{Spellchecker Example}. + + \QWE can be compiled also without spellchecker support with the use of + a \c {webengine-spellchecker} configure switch. + + \badcode + qt-configure-module path\to\qtwebengine\sources -no-webengine-spellchecker + \endcode + + For more information, see \l{Qt Configure Options}. + + Support for this feature was added in Qt 5.8.0. + + \section1 Touch + + \QWE supports touch devices for navigating and interacting with web pages. + + Applications can prohibit the use of touch events in the following ways: + + \list + \li Passing the flag \c --touch-events=disabled on the command line will disable touch event + support in JavaScript API (meaning \c ontouchstart and related handlers will not be present + in the \c document.window object). Touch events will still be delivered to web pages. + + \li Installing an event filter object using \l {QObject::installEventFilter} on the WebEngine + view focus proxy object, and filtering out all touch events. + + \endlist + + \section1 View Source + + \QWE 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 \l{WebEngine Widgets + Simple Browser Example}{Simple Browser} or \l{WebEngine Quick Nano Browser} + {Nano Browser}, and then selecting \c{Page Source} in the context menu. The + \c{Page Source} context menu entry opens the source view in a new tab. + + For opening the source view in the current tab, URLs with \l{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: + \badcode + view-source:https://www.qt.io/ + \endcode + + Auto-completion of incomplete URLs with \l{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: + \badcode + view-source:qt.io + \endcode + + Support for this feature was added in Qt 5.8.0. + + \section1 Web Notifications + + Qt WebEngine supports JavaScript \l{Web Notifications API}. + The application has to explicitly allow the feature by using + QWebEnginePage::Notifications or \l{WebEngineView::Feature} + {WebEngineView.Notifications}. + + Support for this feature was added in Qt 5.13.0. + + \section1 WebGL + + \QWE supports WebGL for some graphics stacks setups. A user can visit the + chrome://gpu page using the QtWebEngine powered application. The \e {Graphics Feature Status} + overview states if WebGL is supported for the current platform setup. A user can also + check the \l {https://webglreport.com}{WebGL Report}. + + The WebGL support is enabled by default. You can disable it with the + \l QWebEngineSettings::WebGLEnabled setting. + + \target webrtc_feature + \section1 WebRTC + + WebRTC provides browsers with Real-Time Communications (RTC) capabilities + via simple APIs. For more information, see \l{WebEngineView::Feature} + {WebEngineView.Feature}, and QWebEnginePage::Feature. + + This feature can be tested by setting up a webcam or microphone and then + opening \c https://test.webrtc.org/ in \l{WebEngine Widgets Simple Browser + Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}. + +*/ |