diff options
Diffstat (limited to 'src/core/doc/src')
| -rw-r--r-- | src/core/doc/src/external-resources.qdoc | 138 | ||||
| -rw-r--r-- | src/core/doc/src/qt6-changes.qdoc | 131 | ||||
| -rw-r--r-- | src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc | 54 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-debugging.qdoc | 112 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-deploying.qdoc | 199 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-features.qdoc | 777 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-global.qdoc | 56 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-index.qdoc | 47 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-modules.qdoc | 25 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-overview.qdoc | 307 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebengine-platform-notes.qdoc | 223 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebenginecore-index.qdoc | 43 | ||||
| -rw-r--r-- | src/core/doc/src/qtwebenginecore-module.qdoc | 49 | ||||
| -rw-r--r-- | src/core/doc/src/qwebengine-licensing.qdoc | 34 | ||||
| -rw-r--r-- | src/core/doc/src/qwebenginehistory_lgpl.qdoc | 22 | ||||
| -rw-r--r-- | src/core/doc/src/qwebenginepage_lgpl.qdoc | 186 | ||||
| -rw-r--r-- | src/core/doc/src/qwebenginesettings_lgpl.qdoc | 104 |
17 files changed, 2298 insertions, 209 deletions
diff --git a/src/core/doc/src/external-resources.qdoc b/src/core/doc/src/external-resources.qdoc new file mode 100644 index 000000000..775492c7e --- /dev/null +++ b/src/core/doc/src/external-resources.qdoc @@ -0,0 +1,138 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \externalpage http://www.chromium.org + \title Chromium Project +*/ + +/*! + \externalpage https://developers.google.com/web/tools/chrome-devtools + \title Chrome DevTools +*/ + +/*! + \externalpage https://developer.chrome.com/docs/devtools/console/ + \title Chrome console API +*/ + +/*! + \externalpage http://ffmpeg.org/ + \title FFmpeg +*/ + +/*! + \externalpage http://www.openh264.org/ + \title OpenH264 Project Homepage +*/ + +/*! + \externalpage http://html5demos.com/drag + \title HTML5 Demos - Drag and Drop +*/ + +/*! + \externalpage http://html5demos.com/drag-anything + \title HTML5 Demos - Simple Drag and Drop +*/ + +/*! + \externalpage http://html5demos.com/dnd-upload + \title HTML5 Demos - Drag and Drop, Automatic Upload +*/ + +/*! + \externalpage http://html5demos.com/file-api + \title HTML5 Demos - File API +*/ + +/*! + \externalpage http://www.widevine.com + \title Widevine CDM +*/ + +/*! + \externalpage http://demo.castlabs.com/ + \title castLabs +*/ + +/*! + \externalpage http://ssdemo04.swankmp.net/ + \title Swank Motion Pictures, Inc. +*/ + +/*! + \externalpage https://bitmovin.com/demos/drm + \title Bitmovin Player +*/ + +/*! + \externalpage https://sourceforge.net/projects/hunspell/ + \title Hunspell Project +*/ + +/*! + \externalpage https://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1 + \title RFC 2616 section 19.5.1 +*/ + +/*! + \externalpage https://www.iana.org/assignments/uri-schemes/prov/view-source + \title view-source URI scheme +*/ + +/*! + \externalpage https://wiki.greasespot.net/Metadata_Block + \title Greasemonkey +*/ + +/*! + \externalpage https://http2.github.io/ + \title HTTP/2 +*/ + +/*! + \externalpage https://http2.akamai.com/demo + \title Akamai HTTP/2 Demo +*/ + +/*! + \externalpage https://www.chromium.org/developers/design-documents/user-scripts + \title User Scripts +*/ + +/*! + \externalpage https://wiki.greasespot.net/Metadata_Block#.40name + \title Metadata Block +*/ + +/*! + \externalpage https://developer.mozilla.org/en-US/docs/Web/API/Navigator/registerProtocolHandler + \title registerProtocolHandler +*/ + +/*! + \externalpage https://www.w3.org/TR/notifications + \title Web Notifications API +*/ + +/*! + \externalpage https://developers.google.com/web/updates/2017/09/autoplay-policy-changes + \title Autoplay Policy Changes +*/ + +// Workarounds for broken links introduced by README.chromium license files +/*! + \externalpage # + \title This is the canonical public repository +*/ + +/*! + \externalpage # + \title NA +*/ + +/*! + \externalpage https://source.chromium.org/chromium/chromium/src/+/master:v8/src/base/ieee754.cc + \title source.chromium.org/chromium/chromium/src/+/master:v8/src/base/ieee754.cc +*/ diff --git a/src/core/doc/src/qt6-changes.qdoc b/src/core/doc/src/qt6-changes.qdoc new file mode 100644 index 000000000..5061c77ab --- /dev/null +++ b/src/core/doc/src/qt6-changes.qdoc @@ -0,0 +1,131 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-changes-qt6.html + \title Changes to Qt WebEngine + \ingroup changes-qt-5-to-6 + \brief Migrate Qt WebEngine to Qt 6. + + Qt 6 is a result of the conscious effort to make the framework more + efficient and easy to use. + + We try to maintain binary and source compatibility for all the public + APIs in each release. But some changes were inevitable in an effort to + make Qt a better framework + + In this topic we summarize those changes in Qt WebEngine, and provide guidance + to handle them. + + \section1 Moved Classes + + \section2 The Qt WebEngine module + Has been renamed to the Qt WebEngineQuick module to not collide with the name of + the super module, and to be consistent with other Quick modules. + + If you port your Qt Quick application, please remember to use the new module + name in your qmake project file. + + \code + QT += webenginequick + \endcode + + \section2 Classes moved from Qt WebEngineWidgets to Qt WebEngineCore + Several classes have been moved from Qt WebEngineWidgets to Qt WebEngineCore if they + did not use the Widgets module. In most cases this change should be source compatible unless + you included the module name in the include header, in which case you need to update your + includes. + + \section3 Classes moved with minimal changes + \list + \li QWebEngineHistory + \li QWebEngineProfile + \li QWebEngineScript + \li QWebEngineScriptCollection + \li QWebEngineClientCertificateSelection + \li QWebEngineSettings + \li QWebEngineFullScreenRequest + \endlist + + \section3 QWebEngineCertificateError + Has been unified between QML and C++ versions, so both are now accepted or rejected via methods + on the class. + + \section3 QWebEngineContextMenuData + Has been moved to Core and renamed QWebEngineContextMenuRequest. + + \section3 QWebEngineDownloadItem + Has been moved to Core and renamed QWebEngineDownloadRequest. + + \section3 QWebEnginePage + Has been moved to Core, and API that worked on QWebEngineView or QPrinter has been moved, and can now + be accessed only from QWebEngineView. See Changed API. + + \section2 Classes moved from Qt WebEngineQuick to Qt WebEngineCore + + \section3 WebEngineNavigationRequest + Is now QWebEngineNavigationRequest, and accessible from C++ API as well, adding a more + informative variant of QWebEnginePage::acceptNavigationRequest(). + + \section3 WebEngineNewViewRequest + Is now WebEngineNewWindowRequest and QWebEngineNewWindowRequest, and accessible from C++ API as well, + adding a more informative variant of QWebEnginePage::createWindow(). + + + \section1 Changed API + + \section2 C++ + + \section3 QWebEnginePage::certificateError() + Is now a signal instead of a derived method. The errors are either accepted or rejected + via methods on the QWebEngineCertificateError class. + + \section3 QWebEnginePage::print() + Has been moved to QWebEngineView::print() and no longer takes a callback argument but + signals finished with QWebEngineView::printFinished() instead. It was never possible + to have two active print jobs at the same time. + + \section3 QWebEnginePage::view() + Has been removed as QWebEnginePage and QWebEngineView are now in different modules. The view + associated with a page can be accessed using the static helper QWebEngineView::forPage(). + + \section3 QWebEngineProfile::defaultProfile() + Has been removed. The default profile is now an off-the-record profile, and only used if a + QWebEnginePage is created without an explicit profile. To maintain Qt 5 like behavior, create + a global profile called "Default" and use it when creating every QWebEnginePage. + + \section2 QML + + \section3 WebEngineNavigationRequest + The navigation requests are now accepted or rejected like other request objects using accept() + or reject() methods. + + \section3 WebEngineNewViewRequest + Has been renamed WebEngineNewWindowRequest. + + \section1 Changed Behavior + + \section2 Default Profile + The default profile is now \e{off the record}. To have a standard browser profile with + disk-cache and cookies, we recommend creating your own profile and using that explicitly. + + \section2 QRC Scheme + Can no longer be accessed from custom schemes by default, nor can it access local content + directly. If the Qt 5 behavior is needed, it can be restored by registering the qrc scheme + like a custom URL scheme, and setting the CorsEnabled and LocalAccessAllowed access flags. + \code + QWebEngineUrlScheme qrcScheme(QByteArrayLiteral("qrc")); + qrcScheme.setFlags(QWebEngineUrlScheme::SecureScheme + | QWebEngineUrlScheme::LocalAccessAllowed + | QWebEngineUrlScheme::CorsEnabled + | QWebEngineUrlScheme::ViewSourceAllowed); + QWebEngineUrlScheme::registerScheme(qrcScheme); + \endcode + + \section2 OCSP Certificate Revocation Checking + In Qt 5 OCSP could be enabled on Linux using QWebEngineProfile::setUseForGlobalCertificateVerification(true) + on a QWebEngineProfile. This has been removed in Qt6 as this specific form of OCSP is considered bad. As + of Qt 6.2, no new method for revoked certificate checking on Linux has yet been added. + + +*/ diff --git a/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc b/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc new file mode 100644 index 000000000..6af681cc5 --- /dev/null +++ b/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc @@ -0,0 +1,54 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-webengine-dictionary.html +\ingroup cmake-commands-qtwebenginecore + +\title qt_add_webengine_dictionary +\keyword qt6_add_webengine_dictionary + +\brief Converts the hunspell dictionary format into \e bdict binary format. + +\cmakecommandsince 6.3 + +\section1 Synopsis + +\badcode +qt_add_webengine_dictionary( + [TARGET] + [SOURCE] + [OUTPUT_DIRECTORY] +) + +\endcode + +\versionlessCMakeCommandsNote qt6_webengine_add_dictionary() + +\section1 Description + + A spell checker in Qt Web Engine needs dictionaries in a specific binary format. + This CMake command converts dictionaries from the \l{Hunspell project}. into the \c bdict + binary format. It creates a \c qtwebengine_dictionaries target, which your project can + use as a dependency. This way your project can easily add dictionaries for the spell + checker. Refer to the \l{WebEngine Widgets Spellchecker Example}{spell checker example} + for more details. + +\section1 Arguments + + \c TARGET is an optinal argument and specifies the name of the application target that should + depend on \c qtwebengine_dictionaries target. In other words it is used to define a build + dependency to create the binary format of dictionaries before building \c TARGET. + + \c SOURCE is the absolute path to the \l{Hunspell project} dictionary for which + a corresponding binary format (\c.bdict) will be created. + + \c OUTPUT_DIRECTORY is an optional argument and specifies the directory where the binary format + of the dictionary will be created. If not specified, \c CMAKE_CURRENT_BINARY_DIR will be used + as \c OUTPUT_DIRECTORY. + + \note The \c qtwebengine_dictionaries directory or \c <CONFIG>/qtwebengine_dictionaries + directories in the case of the multi-config generator is appended to OUTPUT_DIRECTORY. This + helps to utilize dictionaries, as the \c webengine_dictionaries directory is the default + search location. +*/ diff --git a/src/core/doc/src/qtwebengine-debugging.qdoc b/src/core/doc/src/qtwebengine-debugging.qdoc new file mode 100644 index 000000000..3dd4d9276 --- /dev/null +++ b/src/core/doc/src/qtwebengine-debugging.qdoc @@ -0,0 +1,112 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-debugging.html + \title Qt WebEngine Debugging and Profiling + + \section1 Console Logging + + JavaScript executed inside \QWE can use the + \l{Chrome console API} to log information to a console. The logging messages + are forwarded to Qt's logging facilities inside a \c js + \l{QLoggingCategory}{logging category}. However, only warning and fatal + messages are printed by default. To change this, you either have to set custom + rules for the \c js category, or provide custom message handlers + by reimplementing \l{QWebEnginePage::javaScriptConsoleMessage()}, or + connecting to \l{WebEngineView::javaScriptConsoleMessage()}. + + All messages can also be accessed through the \QWE developer + tools. + + \section1 Qt WebEngine Developer Tools + + The \QWE module provides web developer tools that make it easy + to inspect and debug layout and performance issues of any web content. + + The developer tools are accessed as a local web page using a Chromium or + \QWE based browser, such as the Chrome browser. + + To activate the developer tools, start an application that uses \QWE + 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 + --webEngineArgs --remote-debugging-port=<portnumber> + \endcode + + Where \c <port_number> refers to a local network port. The web developer + tools can then be accessed by launching a browser at the address + \c http://localhost:<port_number>. + + Alternatively, the environment variable QTWEBENGINE_REMOTE_DEBUGGING + can be set. It can be set as either just a port working similarly to + \c --remote-debugging-port or given both a host address and a port. The + latter can be used to control which network interface to export the + 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. + + \section1 Using Command-Line Arguments + + You can use the following command-line arguments while debugging to provide + input for bug reports: + + \list + \li \c {--disable-gpu} disables GPU hardware acceleration. This is + useful when diagnosing OpenGL problems. + \li \c {--disable-logging} disables console logging, which might be + useful for debug builds. + \li \c {--enable-logging --log-level=0} enables console logging and sets + the logging level to 0, which means that messages of the severity + \c info and above are recorded in the log. This is the default for + debug builds. Other possible log levels are \c 1 for warnings, \c 2 + for errors, and \c 3 for fatal errors. + \li \c {--v=1} Increases the logging level beyond what \c {--log-level} + can, and enables logging debug messages up to verbosity level \c 1. + A higher number further increases verbosity, but may result in a + large number of logged messages. Default is \c 0 (no debug messages). + \li \c {--no-sandbox} disables the sandbox for the renderer and plugin + processes. Keep in mind that disabling the sandbox might present a + security risk. + \li \c {--single-process} runs the renderer and plugins in the same + process as the browser. This is useful for getting stack traces for + renderer crashes. + \li \c {--enable-features=NetworkServiceInProcess} runs networking in + the main process. This may help firewall management, since only the + application executable will need to be whitelisted and + not QtWebEngineProcess. It means losing the security of + sandboxing of the network service though. + \endlist + + Alternatively, the environment variable QTWEBENGINE_CHROMIUM_FLAGS can be + set. For example, the following value could be set to disable logging while + debugging an application called \e mybrowser: + + \code + QTWEBENGINE_CHROMIUM_FLAGS="--disable-logging" mybrowser + \endcode + + 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 new file mode 100644 index 000000000..3d8a976c8 --- /dev/null +++ b/src/core/doc/src/qtwebengine-deploying.qdoc @@ -0,0 +1,199 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \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 + \l{Deploying Applications on macOS}{macdeployqt} automate the steps to + generate a stand-alone application package. + + When manually deploying applications that depend on \QWE, all the + files that are required to run the application have to be included: + libraries, QML imports, plugins, and translations. + + For more information, see \l {Deploying Qt Applications}. + + \section1 Target Platforms + + \QWE does try to support all \l{Supported Platforms} of Qt. However, + due to different requirements of Chromium this is not always possible. Known + limitations are: + + \list + \li \QWE currently supports only Windows, Linux, and \macos. + + \li On Windows, \QWE only supports Windows Vista or newer as + target platform. Due to use of newer API in Chromium, Windows XP is + not supported. WinRT is not supported, either. + \endlist + + \section1 Deploying Applications Manually + + When manually deploying applications that depend on \QWE, the + following files might have to be deployed: + + \list + \li Libraries + \li QML imports + \li \QWE process + \li Resources + \li Translations + \li Audio and video codecs + \endlist + + \section2 Deploying Libraries + + The following libraries must be deployed with applications that depend on + \QWE: + + \list + \li QtWebEngineCore library + \li QtWebEngineWidgets or QtWebEngine libraries, depending on + application type + \endlist + + \section2 Deploying QML Imports + + If Qt Quick integration is used in the application, the QtWebEngine import + directory needs to be deployed. + + \section2 Deploying \QWE Processes + + \QWE takes advantage of the multi-process model that the Chromium + project offers. The multi-process model requires that the \QWE + Process executable be deployed alongside your application. + + The WebEngine process is executed for each QWebEngineView or WebEngineView + instance. For example, a browser application + with two tabs open should have two separate instances of the process + running. This is a common approach used by most modern web engines to + provide a stable browsing experience. + + At runtime, \QWE looks for the \c QtWebEngineProcess executable in + the directory that + QLibraryInfo::location(QLibraryInfo::LibraryExecutablesPath) returns. + For Qt installations, this is \c QTDIR/libexec (Linux) or \c QTDIR\bin + (Windows). The path can be changed by defining a \c qt.conf file, for + example. Alternatively, an executable path can be set as a value of the + \c QTWEBENGINEPROCESS_PATH environment variable. On \macos, \QWE + looks for the executable in \c .app/Helpers/QtWebEngineProcess. + + \section2 Deploying Resources + + \QWE requires the following resource files: + + \list + \li \c qtwebengine_resources.pak contains the resources needed by + Chromium. + \li \c qtwebengine_devtools_resources.pak contains tools for remote + debugging. + \li \c qtwebengine_resources_100p.pak contains images suitable for low + resolution displays. + \li \c qtwebengine_resources_200p.pak contains images suitable for high + DPI displays. + \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: + + \list + \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: + + \list + \li On \macos: \c .app/Content/Resources + \li On Linux and Windows: \c qtwebengine_locales directory in the + directory specified by + 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 + JavaScript files inside .qrc resources, and these files are supposed to be loaded from inside + HTML pages, make sure to specify the resource files in a \c QTQUICK_COMPILER_SKIPPED_RESOURCES + qmake variable inside your project. This prevents the Qt Quick Compiler from trying to generate + C++ code for the corresponding JavaScript code, as well as removing the original JavaScript code + from the Qt resources file, which would lead to broken HTML pages. For example: + + \code + 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 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}. + +*/ diff --git a/src/core/doc/src/qtwebengine-global.qdoc b/src/core/doc/src/qtwebengine-global.qdoc new file mode 100644 index 000000000..7f6636c16 --- /dev/null +++ b/src/core/doc/src/qtwebengine-global.qdoc @@ -0,0 +1,56 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \headerfile <qtwebenginecoreglobal.h> + \inmodule QtWebEngineCore + \title Global Qt WebEngine Core Declarations + \ingroup funclists + + \brief Helper functions for the \QWE Core module. + +*/ + + +/*! + \fn const char *qWebEngineVersion() noexcept + \relates <qtwebenginecoreglobal.h> + \since 6.2 + + Returns the version number of \QWE at run-time as a string + (for example, "6.2.0"). This may be a different version than the + version the application was compiled against, and a different version + than Qt. +*/ + +/*! + \fn const char *qWebEngineChromiumVersion() noexcept + \relates <qtwebenginecoreglobal.h> + \since 6.2 + + Returns the version number of Chromium used by \QWE at run-time + as a string (for example, "83.0.4103.122"). +*/ + +/*! + \fn const char *qWebEngineChromiumSecurityPatchVersion() noexcept + \relates <qtwebenginecoreglobal.h> + \since 6.3 + + 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-index.qdoc b/src/core/doc/src/qtwebengine-index.qdoc new file mode 100644 index 000000000..b20a96dc1 --- /dev/null +++ b/src/core/doc/src/qtwebengine-index.qdoc @@ -0,0 +1,47 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-index.html + \title Qt WebEngine + + \brief Provides functionality for rendering regions of dynamic web content. + + \QWE provides functionality for rendering regions of dynamic web content. + + The functionality in \QWE is divided into the following modules: + + \annotatedlist qtwebengine-modules + + \section1 Articles and Guides + + \list + \li \l{Qt WebEngine Overview} + \li \l{Qt WebEngine Features} + \li \l{Qt WebEngine Platform Notes} + \li \l{Qt WebEngine Licensing} + \li \l{Qt WebEngine Debugging and Profiling} + \li \l{Deploying Qt WebEngine Applications} + \li \l{Porting from Qt WebKit to Qt WebEngine} + \endlist + + + \section1 Module Evolution + + \l{Changes to Qt WebEngine} lists important changes in the module API + and functionality that were done for the Qt 6 series of Qt. + + \section1 Examples + + \list + \li \l{Qt WebEngine Quick Examples} + \li \l{Qt WebEngine Widgets Examples} + \endlist + + \section1 API References + + \list + \li \l{Qt WebEngine C++ Classes and Namespaces} + \li \l{Qt WebEngine QML Types} + \endlist +*/ diff --git a/src/core/doc/src/qtwebengine-modules.qdoc b/src/core/doc/src/qtwebengine-modules.qdoc new file mode 100644 index 000000000..ee1ad8188 --- /dev/null +++ b/src/core/doc/src/qtwebengine-modules.qdoc @@ -0,0 +1,25 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-modules.html + \title Qt WebEngine C++ Classes and Namespaces + \brief Provides functionality for rendering regions of dynamic web content. + + \QWE provides functionality for rendering regions of dynamic web content. + + \section1 Namespaces + \annotatedlist qtwebengine-namespaces + + \section1 Classes + + \section2 Qt WebEngine Core Module + \generatelist {classesbymodule QtWebEngineCore} + + \section2 Qt WebEngine Widgets Module + \generatelist {classesbymodule QtWebEngineWidgets} + + \section2 Qt WebEngine Quick Module + \generatelist {classesbymodule QtWebEngineQuick} + +*/ diff --git a/src/core/doc/src/qtwebengine-overview.qdoc b/src/core/doc/src/qtwebengine-overview.qdoc new file mode 100644 index 000000000..6eccc669e --- /dev/null +++ b/src/core/doc/src/qtwebengine-overview.qdoc @@ -0,0 +1,307 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \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. + + \QWE provides C++ classes and QML types for rendering HTML, XHTML, and SVG documents, + styled using Cascading Style Sheets (CSS) and scripted with JavaScript. HTML documents can be + made fully editable by the user through the use of the \c{contenteditable} attribute on HTML + elements. + + \section1 Qt WebEngine Architecture + + \image qtwebengine-architecture.png + + The functionality in \QWE is divided into the following modules: + + \list + \li \l{Qt WebEngine Widgets Module} for creating widget-based web applications + \li \l{Qt WebEngine Module} for creating Qt Quick based web applications + \li \l{Qt WebEngine Core Module} for interacting with Chromium + \endlist + + Page rendering and JavaScript execution are separated from the GUI process into the \QWE + Process. It is a library that must be shipped with the application if the Qt libraries are + bundled into the application. + + \section2 Qt WebEngine Widgets Module + + \image qtwebenginewidgets-model.png + + A \e {web engine view} is the main widget component of the \QWE module. It can be used + in various applications to load web content. Within a view, a \e {web engine page} holds a main + frame that is responsible for web content, the \e history of navigated links, and \e actions. + The view and page are quite similar, as they provide a set of common functions. + + All pages belong to a \e {web engine profile} that contains shared \e settings, \e scripts, and + \e cookies. Profiles can be used to isolate pages from each other. A typical use case is a + dedicated profile for a \e {private browsing} mode, where no information is permanently saved. + + \note The \QWE Widgets module uses the \l{Qt Quick Scene Graph}{Qt Quick scene graph} + to compose the elements of a web page into one view. This means that the UI process + requires OpenGL ES 2.0 or OpenGL 2.0 for its rendering. + + \section2 Qt WebEngine Module + + \image qtwebengine-model.png + + The \QWE QML implementation contains the same elements as the \QWE Widgets + implementation, except that there is no separately accessible web engine page. + The supported page functionality is integrated into the web engine view. + + \section2 Qt WebEngine Core Module + + 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. + You can find more detailed information about the differences between Chromium and Chrome in this + \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. + + 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 security patch level. You can also find the versions in the \QWE + sources in the CHROMIUM_VERSION file. + + \section2 Qt WebEngine Process + + The \QWE Process is a separate executable that is used to render web pages and + execute JavaScript. This mitigates security issues and isolates crashes caused by specific + content. + + \section1 Embedding Web Content into Widget Based Applications + + Use the QWebEngineView class to display web pages in the simplest way. Because it is a widget, + you can embed QWebEngineView into your forms and use its convenience functions to download and + display web sites. + + \code + QWebEngineView *view = new QWebEngineView(parent); + view->load(QUrl("http://www.qt.io/")); + view->show(); + \endcode + + An instance of QWebEngineView has one QWebEnginePage. QWebEnginePage can have a + QWebEngineHistory that provides access to the page's navigation history and several QAction + objects that apply actions on the web page. In addition, a QWebEnginePage has the ability to + run JavaScript code in the context of the page's main frame and to enable customization of + handlers for specific events like showing custom authentication dialogs. + + Each QWebEnginePage belongs to a QWebEngineProfile that can have a QWebEngineSettings + for specifying page settings, a QWebEngineScriptCollection for running scripts on the page, and + a QWebEngineCookieStore for accessing the HTTP cookies of Chromium. A QWebEnginePage can also + directly point to a script collection. + + For a widget based application, the web engine is automatically initialized, unless it is + placed in a plugin. In that case, it must be initialized in the application main source file + by using \l QtWebEngineQuick::initialize, as illustrated by the following code snippet: + + \code + int main(int argc, char **argv) + { + QtWebEngineQuick::initialize(); + + QApplication app(argc, argv); + + QMainWindow window; + window.show(); + + return app.exec(); + } + \endcode + + \section1 Embedding Web Content into Qt Quick Applications + + The WebEngineView QML type allows Qt Quick applications to render regions of dynamic web + content. A \e{WebEngineView} type may share the screen with other QML types or encompass the + full screen as specified within the Qt Quick application. + + To make sure that OpenGL context can be shared between the GUI and render processes, the web + engine must be initialized by using \l QtWebEngineQuick::initialize in the application main source + file, as illustrated by the following code snippet: + + \code + int main(int argc, char *argv[]) + { + QGuiApplication app(argc, argv); + + QtWebEngineQuick::initialize(); + + QQmlApplicationEngine engine; + engine.load(QUrl("qrc:/main.qml")); + + return app.exec(); + } + \endcode + + An application can load pages into the WebEngineView, using either an URL or HTML string, and + navigate within session history. By default, links to different pages load within the same + WebEngineView object, but web sites may request them to be opened as a new tab, window, or + dialog. + + The following sample QML application loads a web page using the \l{WebEngineView::}{url} + property: + + \quotefromfile minimal/main.qml + \skipto import + \printuntil /^\}/ + + \section1 Script Injection + + \QWE does not allow direct access to the document object model (DOM) of a page. + However, the DOM can be inspected and adapted by injecting scripts. + + The DOM of a page is constructed when the document is ready, typically + when the page is completely loaded. Therefore, executing scripts as soon as a document is + created is not suitable for DOM operations, where one has to wait until the DOM is ready. + + In addition, an injected script shares the same \e world as the other scripts executed on the + page, which might lead to conflicts. To avoid this, the QWebEngineScript class and the + WebEngineScript QML type provide implementations of the Chromium API for + \e{Content Script Extensions}. They specify the + script to run, the injection point, and the world where the script is run. This enables + accessing the DOM to manipulate it within a world. + + Since Qt 5.8, \QWE supports augmenting a script by using the + following \l{Metadata Block}{Greasemonkey-like attributes}: + + \list + \li \c {@exclude <regexp>} + \li \c {@include <regexp>} + \li \c {@match <regexp>} + \li \c {@name <free text>} + \li \c {@run-at [document-start|document-end|document-idle]} + \endlist + + The attributes determine if and when a \l {User Scripts}{user script} is + run. They must be placed immediately in the beginning of the script, inside + a \c ==UserScript== comment: + + \code + // ==UserScript== + // @include http://*.qt.io/* + // @exclude http://wiki.qt.io/* + // ==/UserScript== + + window.alert("Page is from qt.io, but not wiki.qt.io"); + \endcode + + If your WebEngine application is built using the Qt Quick Compiler, and the application ships + JavaScript files inside .qrc resources, consider reading the section + \l{JavaScript Files in Qt Resource Files}. + + \section1 Managing Certificates + + \QWE uses its own network stack, and therefore QSslConfiguration is not used to + open SSL connections. Instead, \QWE uses the root CA certificates from the operating + system to validate the peer's certificate. + + 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. + + \section1 Proxy Support + + \QWE uses the proxy settings from \l{Qt Network}, and forwards them to Chromium's + networking stack. If QNetworkProxy::applicationProxy is set, it will also be used for \QWE. + If QNetworkProxyFactory::usesSystemConfiguration() is enabled, the proxy settings + are automatically retrieved from the system. Settings from an installed QNetworkProxyFactory + will be ignored, though. + + In case QNetworkProxy::user() and QNetworkProxy::password() are set, these credentials + will be automatically used for proxy authentication. It is up to the user to provide valid + credentials, since there is no error handling callback. + + If no credentials are set with QNetworkProxy, but the proxy requires authentication, + QWebEnginePage::proxyAuthenticationRequired is emitted. + For Qt Quick, a dialog is shown. + + Not all properties of QNetworkProxy are supported by \QWE. That is, + QNetworkProxy::type(), QNetworkProxy::hostName() and QNetworkProxy::port() are taken into + account. All other proxy settings such as QNetworkProxy::rawHeader() are ignored. + + \section1 High DPI Support + + To support High DPI devices, it is recommended that the application attribute + Qt::AA_EnableHighDpiScaling is set to enable automatic scaling based on the + pixel density of the monitor. In \QWE applications, the scaling + affects the default zooming factor and scrollbar size. + + For example: + + \code + int main(int argc, char *argv[]) + { + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + QApplication app(argc, argv); + // ... + } + \endcode + + \QWE bundles images for normal and high-dpi resolutions into + \e qtwebengine_resources_100p.pak and \e qtwebengine_resources_200p.pak + files. Depending on the target resolutions, one or both of these files need + to be deployed. + + For more information, see \l{High DPI}. + + \section1 Using WebEngine Core + + \QWE Core provides an API shared by \QWE and \QWE Widgets for handling + URL requests issued for the networking stack of Chromium and for accessing its HTTP cookies. + + Implementing the QWebEngineUrlRequestInterceptor interface and installing the interceptor on a + profile enables intercepting, blocking, and modifying URL requests (QWebEngineUrlRequestInfo) + before they reach the networking stack of Chromium. + + A QWebEngineUrlSchemeHandler can be registered for a profile to add support for custom URL + schemes. Requests for the scheme are then issued to QWebEngineUrlSchemeHandler::requestStarted() + as QWebEngineUrlRequestJob objects. + + The QWebEngineCookieStore class provides functions for accessing HTTP cookies of Chromium. + The functions can be used to synchronize cookies with QNetworkAccessManager, as well as to set, + delete, and intercept cookies during navigation. + + \section1 Platform Notes + + \QWE currently supports only Windows, Linux, and \macos. Due to Chromium build + requirements it also often requires a newer compiler than the rest of Qt. See + \l{Qt WebEngine Platform Notes} for further details. + + \section1 Related Modules + + \QWE supersedes the \l{http://doc.qt.io/archives/qt-5.3/qtwebkit-index.html}{Qt WebKit} + module, which is based on the + WebKit project, but has not been actively synchronized with the upstream WebKit code since + Qt 5.2 and has been deprecated in Qt 5.5. For tips on how to change a Qt \WebKit widgets + application to use \QWE widgets, see \l{Porting from Qt WebKit to Qt WebEngine}. + + The \l{Qt WebView} module allows to use a native web browser on platforms where one is + available. + + The \l{Qt WebChannel} module can be used to create a bi-directional communication channel + between QObject objects on the C++ side and JavaScript on the QML side. + +*/ diff --git a/src/core/doc/src/qtwebengine-platform-notes.qdoc b/src/core/doc/src/qtwebengine-platform-notes.qdoc new file mode 100644 index 000000000..33bac101a --- /dev/null +++ b/src/core/doc/src/qtwebengine-platform-notes.qdoc @@ -0,0 +1,223 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-platform-notes.html + \title Qt WebEngine Platform Notes + + \brief Contains information about issues that are specific to the \QWE module. + + \section1 Building \QWE from Source + + Static builds are not supported. + + The requirements for building Qt modules from source are listed separately for each supported + platform: + + \list + \li \l{Qt for Windows - Building from Source} + \li \l{Qt for X11 Requirements} + \li \l{Qt for macOS - Building from Source} + \endlist + + In addition, the following tools are required for building the \l {Qt WebEngine} module: + + \list + \li \l {All Platforms} + \li \l {Windows} + \li \l {Linux} + \li \l {macOS} + \endlist + + \section2 All Platforms + + 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 14 or later + \endlist + + \section2 Windows + + On Windows, the following additional tools are required: + + \list + \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 11 SDK version 10.0.22621.0 or later + \endlist + + \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 + + On Linux, Clang or GCC version 9 or later is required. + + \QWE requires \c pkg-config to detect most of its dependencies. The + following \c pkg-config files are required: + + \list + \li \c dbus-1 + \li \c fontconfig + \endlist + + If Qt was configured for \c xcb, the following \c pkg-config files are also + required: + + \list + \li \c libdrm + \li \c xcomposite + \li \c xcursor + \li \c xi + \li \c xrandr + \li \c xscrnsaver + \li \c xtst + \endlist + + \section2 \macos + + On \macos, the following are required: + + \list + \li \macos 10.14 or later + \li Xcode 12.0 or later + \li \macos 11 SDK or later + \endlist + + \note \QWE cannot be built for the 32-bit mode of \macos (using the + \c macx-clang-32 \c mkspec). + + \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.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: + + \list 1 + \li Download the qtwebengine sources. + \li From the earlier Qt version, run + \c {qmake && make (&& make install)}. + \endlist + + \section1 Mac App Store Compatibility + + Applications using \QWE are not compatible with the Mac App Store, because: + + \list + \li The Chromium part of the code uses several private API methods, which are prohibited by + the App Store. + \li Applications submitted to the App Store must be code-signed with the App Sandbox feature + enabled. The App Sandbox feature interferes with Chromium's own sandbox + initialization, which results in Chromium not being properly initialized. This also + ties in with the private API usage. Furthermore, standalone Chromium itself is not + officially tested with the App Sandbox enabled, and even if work is done to bypass + the App Store's restrictions, that would not guarantee correct behavior of the library. + + \endlist + + \section1 macOS Airplay Support on MacBooks with Dual GPUs + + To make \QWE work correctly when streaming to an AppleTV from a MacBook that supports + GPU switching, it is important to add the \c NSSupportsAutomaticGraphicsSwitching option to the + application Info.plist file, with the value set to \c YES. Otherwise rendering issues might + occur when creating new web engine view instances after Airplay is switched on or off. + + \section1 Default QSurfaceFormat OpenGL Profile Support + + If a new default QSurfaceFormat with a modified OpenGL profile has to be set, it should be set + before the application instance is declared, to make sure that all created OpenGL contexts use + the same OpenGL profile. + + On \macos, if the default QSurfaceFormat is set after the application instance, the application + will exit with qFatal(), and print a message that the default QSurfaceFormat should be set + before the application instance. + + \section1 Sandboxing Support + + \QWE provides out-of-the-box sandboxing support for Chromium render + processes. + + On Linux, note the following restrictions: + + \list + \li The kernel has to support the anonymous namespaces feature + (kernel version 3.8 or later). However, on Debian, Ubuntu, + and other Debian-derived distributions, this feature is off + by default. It can be turned on by setting + \c /proc/sys/kernel/unprivileged_userns_clone to 1. + \li The kernel has to support the \c seccomp-bpf feature (kernel + version 3.5 or later). + \li Setuid sandboxes are not supported and are thus disabled. + \endlist + + To explicitly disable sandboxing, use one of the following options: + + \list + \li Set the \c QTWEBENGINE_DISABLE_SANDBOX environment variable to 1. + \li Pass the \c{--no-sandbox} command line argument to the user + application executable. + \li Set \c QTWEBENGINE_CHROMIUM_FLAGS to \c{--no-sandbox}. + \endlist + + For more information, see \l{Using Command-Line Arguments}. + + \section1 Memory Requirements in Docker Environment + + When running Qt Web Engine examples in a Docker container and browsing + content-heavy sites, BUS errors (SIGBUS) might be reported. Typically, + this is caused by Docker running a container with a too small memory space + (such as 64MB). To fix this problem, increase the memory space size. + + \section1 Accessibility and Performance + + \QWE enables accessibility support for web pages when the following conditions + are met: + + \list + \li Qt Core is configured and built with accessibility support enabled. + \li The QPA plugin is notified by the operating system that accessibility should be + activated. This happens for example when using a screen reader application on Windows + or VoiceOver on \macos. + \endlist + + On some old Linux configurations, accessibility can cause a significant slowdown + on large HTML pages. + + 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 692e33d1d..e6fc0b307 100644 --- a/src/core/doc/src/qtwebenginecore-index.qdoc +++ b/src/core/doc/src/qtwebenginecore-index.qdoc @@ -1,49 +1,26 @@ -/**************************************************************************** -** -** Copyright (C) 2016 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) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtwebenginecore-index.html \title Qt WebEngine Core - \brief Provides common API shared by \QWE and \QWE Widgets. + \brief Provides common API shared by \QWE Quick and \QWE Widgets. - \QWE Core provides API shared by \l {Qt WebEngine} 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 + For build with CMake use the \c find_package() command to locate the needed module components + in the Qt6 package and \c target_link_libraries() to link against the module: + + \snippet qtwebenginecore_build_snippet.qdoc 2 + \section1 Articles and Guides \list diff --git a/src/core/doc/src/qtwebenginecore-module.qdoc b/src/core/doc/src/qtwebenginecore-module.qdoc index c976d024c..188609793 100644 --- a/src/core/doc/src/qtwebenginecore-module.qdoc +++ b/src/core/doc/src/qtwebenginecore-module.qdoc @@ -1,53 +1,32 @@ -/**************************************************************************** -** -** Copyright (C) 2016 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) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \module QtWebEngineCore \title Qt WebEngine Core C++ Classes - \brief Provides public API shared by both QtWebEngine and QtWebEngineWidgets. + \brief Provides public API shared by both QtWebEngineQuick and QtWebEngineWidgets. \since 5.6 \ingroup qtwebengine-modules \ingroup modules - - To include the definitions of the module's classes, use the - following directive: - - \snippet qtwebenginecore_build_snippet.qdoc 1 + \qtvariable webenginecore + \qtcmakepackage WebEngineCore If you use qmake to build your projects, \QWE Core is usually - indirectly included through the \l{Qt WebEngine QML Types}{Qt WebEngine} or + indirectly included through the \l{Qt WebEngine QML Types}{Qt WebEngine Quick} or \l{Qt WebEngine Widgets C++ Classes}{Qt WebEngine Widgets} modules. \if !defined(qtforpython) - To link against the module, add this line to your qmake project file: + To link against the module using build with qmake, + add this line to your qmake project file: \snippet qtwebenginecore_build_snippet.qdoc 0 - However, \c webenginecore is implied by adding \c webengine or \c webenginewidgets. + However, \c webenginecore is implied by adding \c webenginequick or \c webenginewidgets. + + For build with CMake use the \c find_package() command to locate the needed module components + in the Qt6 package and \c target_link_libraries() to link against the module: + + \snippet qtwebenginecore_build_snippet.qdoc 2 \endif */ diff --git a/src/core/doc/src/qwebengine-licensing.qdoc b/src/core/doc/src/qwebengine-licensing.qdoc new file mode 100644 index 000000000..796a9664d --- /dev/null +++ b/src/core/doc/src/qwebengine-licensing.qdoc @@ -0,0 +1,34 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group qtwebengine-licensing +\title Qt WebEngine Licensing + +The Qt specific parts of the \QWE module are dual-licensed +under Commercial and GNU Lesser General Public License (LGPLv3). +In addition, the module contains code licensed under LGPLv2. + +The module includes a snapshot of Chromium. As such, users need to +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 +\ingroup qtwebengine-licensing +\title Chromium License +\brief BSD + +The Google-authored portion of Chromium is released under a BSD license: + +\quotefile ../../../3rdparty/chromium/LICENSE +*/ 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 43195deb2..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. */ /*! @@ -252,6 +237,8 @@ Return multiple file names. \value FileSelectUploadFolder Allows users to specify a single existing folder for upload. + \value FileSelectSave + Specify a new file to be created. \sa chooseFiles() */ @@ -278,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() @@ -303,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 @@ -465,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. @@ -720,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. @@ -826,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 7c6ccd3d3..cd7ff8e8c 100644 --- a/src/core/doc/src/qwebenginesettings_lgpl.qdoc +++ b/src/core/doc/src/qwebenginesettings_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) 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 @@ -56,7 +40,7 @@ \value CursiveFont \value FantasyFont \value PictographFont - (added in Qt 5.7) + (added in Qt 5.7, deprecated Qt 6.4) */ /*! @@ -89,21 +73,18 @@ 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. \value LocalStorageEnabled Enables support for the HTML 5 local storage feature. Enabled by default. \value LocalContentCanAccessRemoteUrls - Allows locally loaded documents to ignore cross-origin rules so that they can access - remote resources that would normally be blocked, because all remote resources are - considered cross-origin for a local file. Remote access that would not be blocked by - cross-origin rules is still possible when this setting is disabled (default). - Note that disabling this setting does not stop XMLHttpRequests or media elements in - local files from accessing remote content. Basically, it only stops some HTML - subresources, such as scripts, and therefore disabling this setting is not a safety - mechanism. + Allows local origin documents to access remote resources that would normally be blocked. + 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 @@ -114,7 +95,8 @@ trying to reach towards the right and which element they probably want. Disabled by default. \value LocalContentCanAccessFileUrls - Allows locally loaded documents to access other local URLs. Enabled by default. + Allows locally loaded documents to access other local URLs. Disabling this makes QtWebEngine + behave more like Chrome and Firefox does by default. Enabled by default. \value HyperlinkAuditingEnabled Enables support for the \c ping attribute for hyperlinks. Disabled by default. \value ScrollAnimatorEnabled @@ -171,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 @@ -185,6 +170,16 @@ \value PdfViewerEnabled Specifies that PDF documents will be opened in the internal PDF viewer instead of being downloaded. Enabled by default. (Added in Qt 5.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) */ /*! @@ -207,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. */ @@ -294,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 +*/ |