diff options
Diffstat (limited to 'src/core/doc/src/qtwebengine-features.qdoc')
| -rw-r--r-- | src/core/doc/src/qtwebengine-features.qdoc | 378 |
1 files changed, 259 insertions, 119 deletions
diff --git a/src/core/doc/src/qtwebengine-features.qdoc b/src/core/doc/src/qtwebengine-features.qdoc index 29ec002ee..9465d75a2 100644 --- a/src/core/doc/src/qtwebengine-features.qdoc +++ b/src/core/doc/src/qtwebengine-features.qdoc @@ -1,33 +1,10 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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. @@ -35,16 +12,20 @@ \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{Pepper Plugin API} \li \l{PDF File Viewing} \li \l{Page Lifecycle API} \li \l{Print to PDF} @@ -52,9 +33,9 @@ \li \l{Spellchecker} \li \l{Touch} \li \l{View Source} - \li \l{webrtc_feature}{WebRTC} \li \l{Web Notifications} - \li \l{Favicon Handling} + \li \l{WebGL} + \li \l{webrtc_feature}{WebRTC} \endlist \section1 Audio and Video Codecs @@ -64,25 +45,26 @@ (MP3), have been enabled. Proprietary codecs can be enabled by passing the following option to the \c configure tool when configuring Qt: - \code + \badcode -webengine-proprietary-codecs \endcode For example, the following option could be passed when configuring Qt for building it at the top level: - \code + \badcode configure -webengine-proprietary-codecs \endcode For more information, see \l{Qt Configure Options}. - When using qmake to build just the \QWE module, the following - command can be used (in this example, the \QWE source code is + 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}): - \code - qmake C:\qt\qtwebengine -- -webengine-proprietary-codecs + \badcode + qt-configure-module C:\qt\qtwebengine -webengine-proprietary-codecs + cmake --build . --parallel \endcode \warning When distributing proprietary codec libraries, you must acquire @@ -94,6 +76,68 @@ 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 @@ -101,11 +145,25 @@ 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 + 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, @@ -136,6 +194,16 @@ 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 @@ -143,7 +211,7 @@ 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 + displaying user interface components or debugging information, sandboxed schemes with extra restrictions, and so on. For more information, see \l QWebEngineUrlScheme and \l @@ -164,6 +232,61 @@ 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 @@ -180,6 +303,20 @@ 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. @@ -192,17 +329,17 @@ location can be also passed with \c {QTWEBENGINE_CHROMIUM_FLAGS} using \c {widevine-path}. On Windows: - \code + \badcode set QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="C:/some path/widevinecdm.dll" \endcode On Linux: - \code + \badcode export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.so" \endcode On macOS: - \code + \badcode export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.dylib" \endcode @@ -219,19 +356,42 @@ \section1 HTML5 Geolocation - \QWE supports JavaScript Geolocation API with \l {Qt Location} as a - backend. The application has to explicitly allow the feature by using - QWebEnginePage::Geolocation or \l{WebEngineView::Feature} - {WebEngineView.Feature}. + \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 Qt Location has been built before \QWE then this feature can be + 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 that on Windows an external GPS - receiver must be connected to the application. For more information, see - \l{Qt Positioning}. + 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} @@ -241,6 +401,31 @@ \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: @@ -273,33 +458,6 @@ WebEngineView::colorDialogRequested(), WebEngineView::fileDialogRequested(), and WebEngineView::formValidationMessageRequested() signals. For an example, - see \l{WebEngine Qt Quick Custom Dialogs Example}. - - \section1 Pepper Plugin API - - \QWE supports loading Pepper Plugin API (PPAPI) plugins if - WebEngineSettings::pluginsEnabled or QWebEngineSettings::PluginsEnabled - is set. - - The plugins must be loaded manually using the Chromium command line syntax with the - \c --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: - - \code - <file-path-plugin1>;<mime-type-plugin1>,<file-path-plugin2>;<mime-type1-plugin2>;<mime-type2-plugin2> - \endcode - - For example: - - \code - --register-pepper-plugins="libppapi_example.so;application/x-ppapi-example" - \endcode - - 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. \section1 PDF File Viewing @@ -531,6 +689,15 @@ 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 @@ -564,30 +731,19 @@ 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: - \code + \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: - \code + \badcode view-source:qt.io \endcode Support for this feature was added in Qt 5.8.0. - \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}. - \section1 Web Notifications Qt WebEngine supports JavaScript \l{Web Notifications API}. @@ -597,41 +753,25 @@ Support for this feature was added in Qt 5.13.0. - \section1 Favicon Handling + \section1 WebGL - 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". - For example, - \qml - Image { - source: "image://favicon/url" - } - \endqml + \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 \c url can be the URL of the favicon. For example, - \qml - Image { - source: "image://favicon/https://www.qt.io/hubfs/2016_Qt_Logo/qt_logo_green_rgb_16x16.png" - } - \endqml + The WebGL support is enabled by default. You can disable it with the + \l QWebEngineSettings::WebGLEnabled setting. - The \c url also can be a page URL to access its icon. For example, - \qml - Image { - source: "image://favicon/https://www.qt.io/" - } - \endqml + \target webrtc_feature + \section1 WebRTC - 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. + WebRTC provides browsers with Real-Time Communications (RTC) capabilities + via simple APIs. For more information, see \l{WebEngineView::Feature} + {WebEngineView.Feature}, and QWebEnginePage::Feature. - 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. + 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}. - \note The icon database is not available for off-the-record profiles. */ |