diff options
Diffstat (limited to 'src/core/doc/src')
| -rw-r--r-- | src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc | 2 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-debugging.qdoc | 25 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-deploying.qdoc | 65 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-features.qdoc | 341 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-global.qdoc | 14 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-overview.qdoc | 23 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-platform-notes.qdoc | 49 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebenginecore-index.qdoc | 8 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebenginecore-module.qdoc | 5 | ||||
| -rw-r--r-- | src/core/doc/src/qwebengine-licensing.qdoc | 7 | ||||
| -rw-r--r-- | src/core/doc/src/qwebenginehistory_lgpl.qdoc | 22 | ||||
| -rw-r--r-- | src/core/doc/src/qwebenginepage_lgpl.qdoc | 184 | ||||
| -rw-r--r-- | src/core/doc/src/qwebenginesettings_lgpl.qdoc | 88 |
13 files changed, 574 insertions, 259 deletions
diff --git a/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc b/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc index 74a3ecb48..6af681cc5 100644 --- a/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc +++ b/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_webengine_dictionary.html +\page qt-add-webengine-dictionary.html \ingroup cmake-commands-qtwebenginecore \title qt_add_webengine_dictionary diff --git a/src/core/doc/src/qtwebengine-debugging.qdoc b/src/core/doc/src/qtwebengine-debugging.qdoc index dd7e6bdad..3dd4d9276 100644 --- a/src/core/doc/src/qtwebengine-debugging.qdoc +++ b/src/core/doc/src/qtwebengine-debugging.qdoc @@ -28,10 +28,14 @@ \QWE based browser, such as the Chrome browser. To activate the developer tools, start an application that uses \QWE - with the command-line arguments: + with the command-line argument \c {--remote-debugging-port=<portnumber>}. + + \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 - --remote-debugging-port=<port_number> + --webEngineArgs --remote-debugging-port=<portnumber> \endcode Where \c <port_number> refers to a local network port. The web developer @@ -45,6 +49,12 @@ interface on, so that you can access the developer tools from a remote device. + 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. + For a detailed explanation of the capabilities of developer tools, see the \l {Chrome DevTools} page. @@ -88,6 +98,15 @@ QTWEBENGINE_CHROMIUM_FLAGS="--disable-logging" mybrowser \endcode - QTWEBENGINE_CHROMIUM_FLAGS can also be set using {qputenv} from within the + QTWEBENGINE_CHROMIUM_FLAGS can also be set using \c qputenv from within the application if called before QtWebEngineQuick::initialize(). + + \section1 Dump WebEngineContext Information + + For dumping the WebEngineContext information, you can set the \c QT_LOGGING_RULES + environment variable to \c "qt.webenginecontext.debug=true". + + The output contains information about the graphical backend, and the way how \QWE + is initialized for the application. This is particularly useful for reproducing + issues. */ diff --git a/src/core/doc/src/qtwebengine-deploying.qdoc b/src/core/doc/src/qtwebengine-deploying.qdoc index 383f6828b..3d8a976c8 100644 --- a/src/core/doc/src/qtwebengine-deploying.qdoc +++ b/src/core/doc/src/qtwebengine-deploying.qdoc @@ -4,6 +4,7 @@ /*! \page qtwebengine-deploying.html \title Deploying Qt WebEngine Applications + \ingroup explanations-webtechnologies The way to package and deploy applications varies between operating systems. For Windows and \macos, \l{The Windows Deployment Tool}{windeployqt} and @@ -97,6 +98,12 @@ \li \c icudtl.dat provides support for International Components for Unicode (ICU). It is the Chromium version of ICU, which is not needed if \QWE was configured to use the system ICU. + \li \c v8_context_snapshot.bin contains a previously prepared snapshot + of a v8 context used to speed up initialization. Debug builds use + separate snapshots with the file name extension \c .debug.bin instead + of \c .bin. On \macos, there is a snapshot for each architecture named + accordingly, for example \c v8_context_snapshot.arm64.bin or + \c v8_context_snapshot.arm64.debug.bin. \endlist Resources are searched from the following locations: @@ -105,8 +112,12 @@ \li On Linux and Windows: the \c resources directory in the directory specified by QLibraryInfo::location(QLibraryInfo::DataPath) \li On \macos: \c .app/Content/Resources + \li The application directory specified by QCoreApplication::applicationDirPath() \endlist + Alternatively, a resources directory path can be set as a value of the + \c QTWEBENGINE_RESOURCES_PATH environment variable. + \section2 Translations Locale data (such as \c en-US.pak) is searched form the following locations: @@ -118,6 +129,9 @@ QLibraryInfo::location(QLibraryInfo::TranslationsPath) \endlist + Alternatively, a locales directory path can be set as a value of the + \c QTWEBENGINE_LOCALES_PATH environment variable. + \section2 JavaScript Files in Qt Resource Files If your WebEngine application is built using the Qt Quick Compiler, and the application ships @@ -131,4 +145,55 @@ QTQUICK_COMPILER_SKIPPED_RESOURCES += resources/my_resource.qrc \endcode + \section2 \macos Specific Deployment Steps + + To deploy a \QWE application on \macos, you will need to ensure that the \QWE process is signed + with an entitlements file that at least contains the entitlements listed in + QtWebEngineCore.framework/Helpers/QtWebEngineProcess.app/Contents/Resources/QtWebEngineProcess.entitlements. + + To deploy a \QWE application that accesses the microphone or camera + on \macos, you will need to provide texts for the messages that will be shown to the user to + explain why the application asks for permission to access to the camera or microphone. + To do this, add the texts to the application's \c Info.plist file using the keys + described below. + + For the camera usage message, provide a text using the following key: + \code + <key>NSCameraUsageDescription</key> + <string>Your message text for camera usage.</string> + \endcode + + See also \l{https://developer.apple.com/documentation/bundleresources/information_property_list/nscamerausagedescription} + {Apple's property list file documentation}. + + For the microphone usage message, provide a text using the following key: + \code + <key>NSMicrophoneUsageDescription</key> + <string>Your message text for microphone usage.</string> + \endcode + + See also \l{https://developer.apple.com/documentation/bundleresources/information_property_list/nsmicrophoneusagedescription} + {Apple's property list file documentation}. + + To notarize an application that accesses the camera or the microphone, + you will need to add the corresponding keys to your application's entitlements file used for + deployment and notarization. + + To enable access to the camera, add: + \code + <key>com.apple.security.device.camera</key> + <true/> + \endcode + + See also \l{https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_device_camera} + {Apple's camera entitlement documentation}. + + To enable access to the microphone, add: + \code + <key>com.apple.security.device.microphone</key> + <true/> + \endcode + + See also \l{https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_device_microphone} + {Apple's microphone entitlement documentation}. */ diff --git a/src/core/doc/src/qtwebengine-features.qdoc b/src/core/doc/src/qtwebengine-features.qdoc index da5451221..9465d75a2 100644 --- a/src/core/doc/src/qtwebengine-features.qdoc +++ b/src/core/doc/src/qtwebengine-features.qdoc @@ -4,6 +4,7 @@ /*! \page qtwebengine-features.html \title Qt WebEngine Features + \ingroup explanations-webtechnologies \brief Summarizes \QWE features. @@ -11,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} @@ -28,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 @@ -40,14 +45,14 @@ (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 @@ -57,7 +62,7 @@ command can be used to configure and build (in this example, the \QWE source code is located in \c {C:\qt\qtwebengine}): - \code + \badcode qt-configure-module C:\qt\qtwebengine -webengine-proprietary-codecs cmake --build . --parallel \endcode @@ -71,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 @@ -78,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, @@ -113,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 @@ -120,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 @@ -141,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 @@ -157,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. @@ -169,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 @@ -197,18 +357,41 @@ \section1 HTML5 Geolocation \QWE supports JavaScript Geolocation API with \l {Qt Positioning} as a - backend. The application has to explicitly allow the feature by using - QWebEnginePage::Geolocation or \l{WebEngineView::Feature} - {WebEngineView.Feature}. + 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 Positioning 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} @@ -218,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: @@ -250,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 @@ -508,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 @@ -541,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}. @@ -574,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. */ diff --git a/src/core/doc/src/qtwebengine-global.qdoc b/src/core/doc/src/qtwebengine-global.qdoc index 57df8b3ac..7f6636c16 100644 --- a/src/core/doc/src/qtwebengine-global.qdoc +++ b/src/core/doc/src/qtwebengine-global.qdoc @@ -40,3 +40,17 @@ Returns the version number of last Chromium version security patches have been merged from. */ + +/*! + \fn QString qWebEngineGetDomainAndRegistry(const QUrl &url) + \relates <qtwebenginecoreglobal.h> + \since 6.6 + + Returns the domain of the host, that is, the effective top-level domain + (eTLD) and the first domain below it, from \a url. + + This function supports internationalized domain names (IDN). In this case, + it returns the domain encoded in Punycode. + + If the host is not a domain, returns an empty string. +*/ diff --git a/src/core/doc/src/qtwebengine-overview.qdoc b/src/core/doc/src/qtwebengine-overview.qdoc index 3937ca9bb..6eccc669e 100644 --- a/src/core/doc/src/qtwebengine-overview.qdoc +++ b/src/core/doc/src/qtwebengine-overview.qdoc @@ -4,6 +4,7 @@ /*! \page qtwebengine-overview.html \title Qt WebEngine Overview + \ingroup explanations-webtechnologies The \QWE module provides a web browser engine that makes it easy to embed content from the World Wide Web into your Qt application on platforms that do not have a native web engine. @@ -58,6 +59,9 @@ The \QWE core is based on the \l {Chromium Project}. Chromium provides its own network and painting engines and is developed tightly together with its dependent modules. + Even though the QtNetwork stack is not used, its setup can be synchronized with the \QWE. + See \l {Proxy Support}, \l {Managing Certificates}, \l {Client Certificates}, and + \l {QWebEngineCookieStore} for more details. \note \QWE is based on Chromium, but does not contain or use any services or add-ons that might be part of the Chrome browser that is built and delivered by Google. @@ -65,10 +69,19 @@ \l{https://chromium.googlesource.com/chromium/src/+/master/docs/chromium_browser_vs_google_chrome.md}{overview} that is part of the documentation in the \l {Chromium Project} upstream source tree. - This version of \QWE is based on Chromium version 94.0.4606, with additional security - fixes from newer versions. The Chromium version can also be read at runtime using the + The Chromium version used is the one used by the latest stable Chrome version at the time of Qt feature freeze + for the current version of \QWE. Additional security patches are cherry picked from newer Chrome releases on + every patch release, security patches released in time for the Qt patch release freeze will be included. + If Chrome releases critical fixes outside our release window, the next patch release is sped up to ensure a + patched \QWE is released before the patch details goes public. + + If you need a newer \QWE beyond security fixes, and can not update all of Qt, \QWE supports building with + older version of Qt back to the last Qt LTS. For instance \QWE 6.3, 6.4, and 6.5 can all be built with Qt 6.2. + In Qt LTS releases, \QWE may be fully replaced with such a newer version to make security patching easier. + + The relevant Chromium versions in question can also be read at runtime using the \l qWebEngineChromiumVersion() method, and \l qWebEngineChromiumSecurityPatchVersion() - to read the current patch level. You can also find the versions in the QtWebEngine + to read the current security patch level. You can also find the versions in the \QWE sources in the CHROMIUM_VERSION file. \section2 Qt WebEngine Process @@ -150,7 +163,7 @@ The following sample QML application loads a web page using the \l{WebEngineView::}{url} property: - \quotefromfile webenginequick/minimal/main.qml + \quotefromfile minimal/main.qml \skipto import \printuntil /^\}/ @@ -204,7 +217,7 @@ open SSL connections. Instead, \QWE uses the root CA certificates from the operating system to validate the peer's certificate. - The \l{WebEngineCertificateError::error} and \l{QWebEngineCertificateError::Type} enumerations + The \l{WebEngineCertificateError::type} and \l{QWebEngineCertificateError::Type} enumerations provide information about the types of certificate errors that might occur. The errors can be handled by using the WebEngineView::certificateError QML method or by connecting to the QWebEnginePage::certificateError signal. diff --git a/src/core/doc/src/qtwebengine-platform-notes.qdoc b/src/core/doc/src/qtwebengine-platform-notes.qdoc index f2a39f7db..33bac101a 100644 --- a/src/core/doc/src/qtwebengine-platform-notes.qdoc +++ b/src/core/doc/src/qtwebengine-platform-notes.qdoc @@ -34,11 +34,12 @@ On all platforms, the following tools are required at build time: \list + \li C++20 compiler support \li CMake 3.19 or newer \li \l Python 3 with html5lib library \li Bison, Flex \li GPerf - \li Node.js version 12 or later + \li Node.js version 14 or later \endlist \section2 Windows @@ -49,16 +50,10 @@ \li Visual Studio 2019 or later, or clang-cl version 10 or later \li Active Template Library (ATL), usually included in the Visual Studio installation - \li Windows 10 SDK version 10.0.19041 or later + \li Windows 11 SDK version 10.0.22621.0 or later \endlist - \QWE can only be built on 64-bit Windows, with a x64-bit toolchain. - For building \QWE for x86 applications, you need to configure - and compile Qt with the Visual Studio x64 to x86 cross-compile - toolchain. This toolchain can be set up on the command line by running - \c{vcvarsall.bat amd64_x86}. - - \note It is not recommended to use tools form \c msys2 or \c cygwin to build \QWE as it may result in build errors. + \note It is not recommended to use tools from \c msys2 or \c cygwin to build \QWE as it may result in build errors. \section2 Linux @@ -101,8 +96,8 @@ \section1 Using Earlier Qt Versions to Build \QWE Building \QWE with earlier Qt versions (down to the last LTS - version) is supported. It means that \QWE 6.3 can be built with - Qt 6.2.x, and Qt 6.3. + version) is supported. It means that \QWE 6.4 can be built with + Qt 6.2.x, Qt 6.3.x, and Qt 6.4. To use an earlier Qt version to build Qt Webengine: @@ -193,16 +188,36 @@ or VoiceOver on \macos. \endlist - Due to some limitations, the Linux QPA plugin almost always reports that accessibility should - be activated. On big HTML pages, this can cause a significant slowdown in rendering speed. + On some old Linux configurations, accessibility can cause a significant slowdown + on large HTML pages. - Because of that, \QWE accessibility support is disabled by default - on Linux. - It can be re-enabled by setting the \c QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY environment - variable to a non-empty value. + Because of that, \QWE accessibility support can be disabled on Linux, by setting the + \c QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY environment variable to 0. \section1 Popups in Fullscreen Applications on Windows Because of a limitation in the Windows compositor, applications that show a fullscreen web engine view will not properly display popups or other top-level windows. The reason and workaround is described in \l {Fullscreen OpenGL Based Windows}. + + \target windows_manifest + \section1 Windows Application Manifest + A manifest is an XML file that is read when the program starts and informs Windows how to run the program. + Some \QWE features may require adding a manifest file for the user application to work correctly on Windows. + + The following snippets show the manifest file's structure and how to embed it into the program. + + \note These code snippets are taken from the \l {WebEngine Quick Nano Browser} example. + + The manifest file defines which Windows versions the application supports. + \l {QWebEngineProfile::} {httpUserAgent} needs this information to report the correct Windows version. + \quotefile ../../../../examples/webenginequick/quicknanobrowser/quicknanobrowser.exe.manifest + + To embed the file into the executable, add it to the sources: + \quotefromfile ../../../../examples/webenginequick/quicknanobrowser/CMakeLists.txt + \skipto qt_add_executable + \dots + \printuntil endif + \dots + + For more information, see the \l {https://learn.microsoft.com/en-us/windows/win32/sbscs/application-manifests} {Application manifest documentation page}. */ diff --git a/src/core/doc/src/qtwebenginecore-index.qdoc b/src/core/doc/src/qtwebenginecore-index.qdoc index 73a6b4ead..e6fc0b307 100644 --- a/src/core/doc/src/qtwebenginecore-index.qdoc +++ b/src/core/doc/src/qtwebenginecore-index.qdoc @@ -7,15 +7,11 @@ \brief Provides common API shared by \QWE Quick and \QWE Widgets. - \QWE Core provides API shared by \l {Qt WebEngine Quick} and \l {Qt WebEngine Widgets}. + \QWE Core provides API shared by \l {Qt WebEngine QML Types}{Qt WebEngine Quick} and + \l {Qt WebEngine Widgets C++ Classes}{Qt WebEngine Widgets}. \section1 Getting Started - To include the definitions of the module's classes, use the - following directive: - - \snippet qtwebenginecore_build_snippet.qdoc 1 - To link against the module, add this line to your qmake project file: \snippet qtwebenginecore_build_snippet.qdoc 0 diff --git a/src/core/doc/src/qtwebenginecore-module.qdoc b/src/core/doc/src/qtwebenginecore-module.qdoc index 2cb321e07..188609793 100644 --- a/src/core/doc/src/qtwebenginecore-module.qdoc +++ b/src/core/doc/src/qtwebenginecore-module.qdoc @@ -12,11 +12,6 @@ \qtvariable webenginecore \qtcmakepackage WebEngineCore - To include the definitions of the module's classes, use the - following directive: - - \snippet qtwebenginecore_build_snippet.qdoc 1 - If you use qmake to build your projects, \QWE Core is usually indirectly included through the \l{Qt WebEngine QML Types}{Qt WebEngine Quick} or \l{Qt WebEngine Widgets C++ Classes}{Qt WebEngine Widgets} modules. diff --git a/src/core/doc/src/qwebengine-licensing.qdoc b/src/core/doc/src/qwebengine-licensing.qdoc index 2b1bd2845..796a9664d 100644 --- a/src/core/doc/src/qwebengine-licensing.qdoc +++ b/src/core/doc/src/qwebengine-licensing.qdoc @@ -14,11 +14,16 @@ respect the licenses of Chromium, and third-party code included in Chromium. The arguably most restrictive license to be respected by all users is LGPLv2.1. +\note Any GPL licenses listed below are only used to access Linux system +resources. \QWE does not link to nor distribute GPL binary code, and +it does not affect users of \QWE. + Third party licenses included in the sources are: */ /*! -\page qtwebengine-3rdparty-chromium-global.html attribution +\page qtwebengine-3rdparty-chromium-global.html +\attribution \ingroup qtwebengine-licensing \title Chromium License \brief BSD diff --git a/src/core/doc/src/qwebenginehistory_lgpl.qdoc b/src/core/doc/src/qwebenginehistory_lgpl.qdoc index 37f96e7c1..f61bb3b85 100644 --- a/src/core/doc/src/qwebenginehistory_lgpl.qdoc +++ b/src/core/doc/src/qwebenginehistory_lgpl.qdoc @@ -1,22 +1,6 @@ -/* - Copyright (C) 2015 The Qt Company Ltd. - Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Library General Public License for more details. - - You should have received a copy of the GNU Library General Public License - along with this library; see the file COPYING.LIB. If not, write to - the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - Boston, MA 02110-1301, USA. -*/ +// Copyright (C) 2015 The Qt Company Ltd. +// Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // The documentation in this file was imported from QtWebKit and is thus constrained // by its LGPL license. Documentation written from scratch for new methods should be diff --git a/src/core/doc/src/qwebenginepage_lgpl.qdoc b/src/core/doc/src/qwebenginepage_lgpl.qdoc index 4a058460b..c2515cd13 100644 --- a/src/core/doc/src/qwebenginepage_lgpl.qdoc +++ b/src/core/doc/src/qwebenginepage_lgpl.qdoc @@ -1,24 +1,8 @@ -/* - Copyright (C) 2019 The Qt Company Ltd. - Copyright (C) 2008, 2009, 2012 Nokia Corporation and/or its subsidiary(-ies) - Copyright (C) 2007 Staikos Computing Services Inc. - Copyright (C) 2007 Apple Inc. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Library General Public License for more details. - - You should have received a copy of the GNU Library General Public License - along with this library; see the file COPYING.LIB. If not, write to - the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - Boston, MA 02110-1301, USA. -*/ +// Copyright (C) 2019 The Qt Company Ltd. +// Copyright (C) 2008, 2009, 2012 Nokia Corporation and/or its subsidiary(-ies) +// Copyright (C) 2007 Staikos Computing Services Inc. +// Copyright (C) 2007 Apple Inc. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // The documentation in this file was imported from QtWebKit and is thus constrained // by its LGPL license. Documentation written from scratch for new methods should be @@ -131,85 +115,86 @@ should be enabled to get automatic focus. \value PasteAndMatchStyle Paste content from the clipboard with current style. - \value OpenLinkInThisWindow Open the current link in the current window. (Added in Qt 5.6) - \value OpenLinkInNewWindow Open the current link in a new window. Requires implementation of - \l createWindow() or \l newWindowRequested() (Added in Qt 5.6) - \value OpenLinkInNewTab Open the current link in a new tab. Requires implementation of - \l createWindow() or \l newWindowRequested(). (Added in Qt 5.6) - \value OpenLinkInNewBackgroundTab Open the current link in a new background tab. Requires - implementation of \l createWindow() or \l newWindowRequested(). (Added in Qt 5.7) - \value CopyLinkToClipboard Copy the current link to the clipboard. (Added in Qt 5.6) - - \value CopyImageToClipboard Copy the clicked image to the clipboard. (Added in Qt 5.6) - \value CopyImageUrlToClipboard Copy the clicked image's URL to the clipboard. (Added in Qt 5.6) - \value CopyMediaUrlToClipboard Copy the hovered audio or video's URL to the clipboard. (Added in Qt 5.6) - \value ToggleMediaControls Toggle between showing and hiding the controls for the hovered audio - or video element. (Added in Qt 5.6) - \value ToggleMediaLoop Toggle whether the hovered audio or video should loop on completetion or - not. (Added in Qt 5.6) - \value ToggleMediaPlayPause Toggle the play/pause state of the hovered audio or video element. - (Added in Qt 5.6) - \value ToggleMediaMute Mute or unmute the hovered audio or video element. (Added in Qt 5.6) - \value DownloadLinkToDisk Download the current link to the disk. Requires a slot for - \l{QWebEngineProfile::}{downloadRequested()}. (Added in Qt 5.6) - \value DownloadImageToDisk Download the highlighted image to the disk. Requires a slot for - \l{QWebEngineProfile::}{downloadRequested()}. (Added in Qt 5.6) - \value DownloadMediaToDisk Download the hovered audio or video to the disk. Requires a slot for - \l{QWebEngineProfile::}{downloadRequested()}. (Added in Qt 5.6) - - \value InspectElement Trigger any attached Web Inspector to inspect the highlighed element. - (Added in Qt 5.6) - \value ExitFullScreen Exit the fullscreen mode. (Added in Qt 5.6) - \value RequestClose Request to close the web page. If defined, the \c{window.onbeforeunload} + \value [since 5.6] OpenLinkInThisWindow Open the current link in the current window. + \value [since 5.6] OpenLinkInNewWindow Open the current link in a new window. Requires implementation of + \l createWindow() or \l newWindowRequested(). + \value [since 5.6] OpenLinkInNewTab Open the current link in a new tab. Requires implementation of + \l createWindow() or \l newWindowRequested(). + \value [since 5.7] OpenLinkInNewBackgroundTab Open the current link in a new background tab. Requires + implementation of \l createWindow() or \l newWindowRequested(). + \value [since 5.6] CopyLinkToClipboard Copy the current link to the clipboard. + + \value [since 5.6] CopyImageToClipboard Copy the clicked image to the clipboard. + \value [since 5.6] CopyImageUrlToClipboard Copy the clicked image's URL to the clipboard. + \value [since 5.6] CopyMediaUrlToClipboard Copy the hovered audio or video's URL to the clipboard. + \value [since 5.6] ToggleMediaControls Toggle between showing and hiding the controls for the hovered audio + or video element. + \value [since 5.6] ToggleMediaLoop Toggle whether the hovered audio or video should loop on completetion or + not. + \value [since 5.6] ToggleMediaPlayPause Toggle the play/pause state of the hovered audio or video element. + \value [since 5.6] ToggleMediaMute Mute or unmute the hovered audio or video element. + \value [since 5.6] DownloadLinkToDisk Download the current link to the disk. Requires a slot for + \l{QWebEngineProfile::}{downloadRequested()}. + \value [since 5.6] DownloadImageToDisk Download the highlighted image to the disk. Requires a slot for + \l{QWebEngineProfile::}{downloadRequested()}. + \value [since 5.6] DownloadMediaToDisk Download the hovered audio or video to the disk. Requires a slot for + \l{QWebEngineProfile::}{downloadRequested()}. + + \value [since 5.6] InspectElement Trigger any attached Web Inspector to inspect the highlighed element. + \value [since 5.6] ExitFullScreen Exit the fullscreen mode. + \value [since 5.6] RequestClose Request to close the web page. If defined, the \c{window.onbeforeunload} handler is run, and the user can confirm or reject to close the page. If the close - request is confirmed, \c windowCloseRequested is emitted. (Added in Qt 5.6) - \value Unselect Clear the current selection. (Added in Qt 5.7) - \value SavePage Save the current page to disk. MHTML is the default format that is used to store + request is confirmed, \c windowCloseRequested is emitted. + \value [since 5.7] Unselect Clear the current selection. + \value [since 5.7] SavePage Save the current page to disk. MHTML is the default format that is used to store the web page on disk. Requires a slot for \l{QWebEngineProfile::}{downloadRequested()}. - (Added in Qt 5.7) - \value ViewSource Show the source of the current page in a new tab. Requires implementation of - \l createWindow() or \l newWindowRequested(). (Added in Qt 5.8) + \value [since 5.8] ViewSource Show the source of the current page in a new tab. Requires implementation of + \l createWindow() or \l newWindowRequested(). - \value ToggleBold + \value [since 5.10] ToggleBold Toggles boldness for the selection or at the cursor position. - Requires \c contenteditable="true". (Added in Qt 5.10) - \value ToggleItalic + Requires \c contenteditable="true". + \value [since 5.10] ToggleItalic Toggles italics for the selection or at the cursor position. - Requires \c contenteditable="true". (Added in Qt 5.10) - \value ToggleUnderline + Requires \c contenteditable="true". + \value [since 5.10] ToggleUnderline Toggles underlining of the selection or at the cursor position. - Requires \c contenteditable="true". (Added in Qt 5.10) - \value ToggleStrikethrough + Requires \c contenteditable="true". + \value [since 5.10] ToggleStrikethrough Toggles striking through the selection or at the cursor position. - Requires \c contenteditable="true". (Added in Qt 5.10) + Requires \c contenteditable="true". - \value AlignLeft + \value [since 5.10] AlignLeft Aligns the lines containing the selection or the cursor to the left. - Requires \c contenteditable="true". (Added in Qt 5.10) - \value AlignCenter + Requires \c contenteditable="true". + \value [since 5.10] AlignCenter Aligns the lines containing the selection or the cursor at the center. - Requires \c contenteditable="true". (Added in Qt 5.10) - \value AlignRight + Requires \c contenteditable="true". + \value [since 5.10] AlignRight Aligns the lines containing the selection or the cursor to the right. - Requires \c contenteditable="true". (Added in Qt 5.10) - \value AlignJustified + Requires \c contenteditable="true". + \value [since 5.10] AlignJustified Stretches the lines containing the selection or the cursor so that each line has equal width. - Requires \c contenteditable="true". (Added in Qt 5.10) - \value Indent + Requires \c contenteditable="true". + \value [since 5.10] Indent Indents the lines containing the selection or the cursor. - Requires \c contenteditable="true". (Added in Qt 5.10) - \value Outdent + Requires \c contenteditable="true". + \value [since 5.10] Outdent Outdents the lines containing the selection or the cursor. - Requires \c contenteditable="true". (Added in Qt 5.10) + Requires \c contenteditable="true". - \value InsertOrderedList + \value [since 5.10] InsertOrderedList Inserts an ordered list at the current cursor position, deleting the current selection. - Requires \c contenteditable="true". (Added in Qt 5.10) - \value InsertUnorderedList + Requires \c contenteditable="true". + \value [since 5.10] InsertUnorderedList Inserts an unordered list at the current cursor position, deleting the current selection. - Requires \c contenteditable="true". (Added in Qt 5.10) + Requires \c contenteditable="true". + \value [since 6.6] ChangeTextDirectionLTR + Changes text direction to left-to-right in the focused input element. + \value [since 6.6] ChangeTextDirectionRTL + Changes text direction to right-to-left in the focused input element. \omitvalue WebActionCount */ @@ -225,8 +210,8 @@ A web browser tab. \value WebDialog A window without decoration. - \value WebBrowserBackgroundTab - A web browser tab without hiding the current visible WebEngineView. (Added in Qt 5.7) + \value [since 5.7] WebBrowserBackgroundTab + A web browser tab without hiding the current visible WebEngineView. */ /*! @@ -280,7 +265,7 @@ \value NavigationTypeFormSubmitted The navigation request resulted from a form submission. \value NavigationTypeBackForward The navigation request resulted from a back or forward action. \value NavigationTypeReload The navigation request resulted from a reload action. - \value NavigationTypeRedirect The navigation request resulted from a content or server controlled redirect. This also includes automatic reloads. (Added in Qt 5.14) + \value [since 5.14] NavigationTypeRedirect The navigation request resulted from a content or server controlled redirect. This also includes automatic reloads. \value NavigationTypeOther The navigation request was triggered by other means not covered by the above. \sa acceptNavigationRequest() @@ -305,11 +290,18 @@ \value MouseLock Mouse locking, which locks the mouse pointer to the web view and is typically used in games. - \value DesktopVideoCapture + \value [since 5.10] DesktopVideoCapture Video output capture, that is, the capture of the user's display, - for screen sharing purposes for example. (Added in Qt 5.10) - \value DesktopAudioVideoCapture - Both audio and video output capture. (Added in Qt 5.10) + for screen sharing purposes for example. + \value [since 5.10] DesktopAudioVideoCapture + Both audio and video output capture. + \value [since 6.8] ClipboardReadWrite + Read and write access for the clipboard. If both \l{QWebEngineSettings::JavascriptCanPaste} + {JavascriptCanPaste} and \l{QWebEngineSettings::JavascriptCanAccessClipboard} + {JavascriptCanAccessClipboard} settings are enabled, this permission will always be granted + automatically and no feature requests will be made. + \value [since 6.8] LocalFontsAccess + Access to the fonts installed on the user's machine. Only available on desktop platforms. \sa featurePermissionRequested(), featurePermissionRequestCanceled(), setFeaturePermission(), PermissionPolicy @@ -467,6 +459,9 @@ The action is owned by the QWebEnginePage but you can customize the look by changing its properties. + \l{QWebEnginePage::action(WebAction action)} does not have a default styled icon. + Use \l{QWebEngineView::pageAction()} to have an action with a default styled icon. + QWebEnginePage also takes care of implementing the action, so that upon triggering the corresponding action is performed on the page. @@ -722,6 +717,7 @@ is empty, it is assumed that the content is \c{text/plain,charset=US-ASCII}. External objects referenced in the content are located relative to \a baseUrl. + For external objects with relative URLs to be loaded, \c baseUrl cannot be empty. The \a data is loaded immediately; external objects are loaded asynchronously. @@ -828,3 +824,15 @@ \sa url() */ + +/*! + \fn void QWebEnginePage::webAuthUxRequested(QWebEngineWebAuthUxRequest *request); + \since 6.7 + + This signal is emitted when a WebAuth authenticator needs user interaction + during the authentication process. These requests are handled by displaying a dialog to the user. + + The \a request contains the information and API required to complete the WebAuth UX request. + + \sa QWebEngineWebAuthUxRequest +*/ diff --git a/src/core/doc/src/qwebenginesettings_lgpl.qdoc b/src/core/doc/src/qwebenginesettings_lgpl.qdoc index 9baeafaaf..cd7ff8e8c 100644 --- a/src/core/doc/src/qwebenginesettings_lgpl.qdoc +++ b/src/core/doc/src/qwebenginesettings_lgpl.qdoc @@ -1,22 +1,6 @@ -/* - Copyright (C) 2022 The Qt Company Ltd. - Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Library General Public License for more details. - - You should have received a copy of the GNU Library General Public License - along with this library; see the file COPYING.LIB. If not, write to - the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - Boston, MA 02110-1301, USA. -*/ +// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // The documentation in this file was imported from QtWebKit and is thus constrained // by its LGPL license. Documentation written from scratch for new methods should be @@ -31,8 +15,8 @@ \inmodule QtWebEngineCore QWebEngineSettings allows configuration of browser properties, such as font sizes and - families, the location of a custom style sheet, and generic attributes, such as JavaScript - support. Individual attributes are set using the setAttribute() function. The + families, and generic attributes, such as JavaScript support. + Individual attributes are set using the setAttribute() function. The \l{QWebEngineSettings::WebAttribute}{WebAttribute} enum further describes each attribute. Each QWebEnginePage object has its own QWebEngineSettings object, which configures the @@ -89,7 +73,9 @@ Allows JavaScript programs to read from and write to the clipboard. Writing to the clipboard is always allowed if it is specifically requested by the user. See JavascriptCanPaste to also allow pasting the content of the clipboard content from - JavaScript. + JavaScript. Since unrestricted clipboard access is a potential security concern, it is + recommended that applications leave this disabled and instead respond to + \l{QWebEnginePage::ClipboardReadWrite}{ClipboardReadWrite} feature permission requests. Disabled by default. \value LinksIncludedInFocusChain Includes hyperlinks in the keyboard focus chain. Enabled by default. @@ -97,7 +83,8 @@ Enables support for the HTML 5 local storage feature. Enabled by default. \value LocalContentCanAccessRemoteUrls Allows local origin documents to access remote resources that would normally be blocked. - Disabled by default. + Disabled by default. Note DnsPrefetchEnabled below operates independently of this setting, + and can if enabled, cause remote accesses from local content. \value XSSAuditingEnabled Obsolete and has no effect. \value SpatialNavigationEnabled @@ -166,8 +153,11 @@ similar to Chrome on desktops. To overwrite the default behavior, disable this setting. (Added in Qt 5.11) \value JavascriptCanPaste - Enables JavaScript \c{execCommand("paste")}. This also requires - enabling JavascriptCanAccessClipboard. + Enables JavaScript \c{execCommand("paste")}. This also requires enabling + JavascriptCanAccessClipboard. Since unrestricted clipboard access is a potential + security concern, it is recommended that applications leave this disabled + and instead respond to \l{QWebEnginePage::ClipboardReadWrite}{ClipboardReadWrite} + feature permission requests. Disabled by default. (Added in Qt 5.11) \value WebRTCPublicInterfacesOnly Limits WebRTC to public IP addresses only. When disabled WebRTC may also use @@ -183,6 +173,13 @@ \value NavigateOnDropEnabled Specifies that navigations can be triggered by dropping URLs on the view. Enabled by default. (Added in Qt 6.4) + \value ReadingFromCanvasEnabled Specifies that reading from all canvas elements is enabled. + This setting will have impact on all HTML5 canvas elements irrespective of origin, and can be disabled + to prevent canvas fingerprinting. + Enabled by default. (Added in Qt 6.6) + \value ForceDarkMode Specifies that all web contents will be rendered using a dark theme. + For more information, see \l{https://developer.chrome.com/blog/auto-dark-theme/}{Auto dark theme}. + Disabled by default. (Added in Qt 6.7) */ /*! @@ -205,6 +202,24 @@ */ /*! + \enum QWebEngineSettings::ImageAnimationPolicy + \since Qt 6.8 + + This enum describes how an image animation should be handled when the image frames + are rendered for animation. + + \value AllowImageAnimation + Allows image animation when the image frames are rendered. + \value AnimateImageOnce + Animate the image once when the image frames are rendered. + \value DisallowImageAnimation + Disallows image animation when the image frames are rendered. + \omitvalue InheritedImageAnimationPolicy + + \sa imageAnimationPolicy setImageAnimationPolicy resetImageAnimationPolicy +*/ + +/*! \fn void QWebEngineSettings::setFontSize(FontSize type, int size) Sets the font size for \a type to \a size in pixels. */ @@ -292,3 +307,26 @@ Resets the setting of \a attribute to the value specified in the profile that the page belongs to. */ + +/*! + \fn QWebEngineSettings::ImageAnimationPolicy QWebEngineSettings::imageAnimationPolicy() const + \since Qt 6.8 + Returns the currently selected policy for handling image animation when the image frames are rendered. + Default is \l{QWebEngineSettings::AllowImageAnimation}. + \sa setImageAnimationPolicy resetImageAnimationPolicy +*/ + +/*! + \fn void QWebEngineSettings::setImageAnimationPolicy(QWebEngineSettings::ImageAnimationPolicy policy) + \since Qt 6.8 + Sets the policy for handling image animation when the image frames are rendered to \a policy. + Default is \l{QWebEngineSettings::AllowImageAnimation}. + \sa imageAnimationPolicy resetImageAnimationPolicy +*/ + +/*! + \fn void QWebEngineSettings::resetImageAnimationPolicy() + \since Qt 6.7 + Removes the policy for handling image animation. + \sa imageAnimationPolicy setImageAnimationPolicy +*/ |