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 | 272 | ||||
| -rw-r--r-- | src/core/doc/src/qwebenginepage_lgpl.qdoc | 838 | ||||
| -rw-r--r-- | src/core/doc/src/qwebenginesettings_lgpl.qdoc | 332 |
17 files changed, 3569 insertions, 68 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 new file mode 100644 index 000000000..f61bb3b85 --- /dev/null +++ b/src/core/doc/src/qwebenginehistory_lgpl.qdoc @@ -0,0 +1,272 @@ +// 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 +// placed inline in the code as usual. + +/*! + \class QWebEngineHistoryItem + \brief The QWebEngineHistoryItem class represents one item in the history of a web engine page. + \since 5.4 + \inmodule QtWebEngineCore + + Each web engine history item represents an entry in the history stack of a web page, + containing information about the page, its location, and the time when it was last visited. + + \sa QWebEngineHistory, QWebEnginePage::history() +*/ + +/*! + \fn QWebEngineHistoryItem::QWebEngineHistoryItem(const QWebEngineHistoryItem &other) + Constructs a history item from \a other. The new item and \a other + will share their data, and modifying either this item or \a other will + modify both instances. +*/ + +/*! + \fn QWebEngineHistoryItem &QWebEngineHistoryItem::operator=(const QWebEngineHistoryItem &other) + Assigns the \a other history item to this. This item and \a other + will share their data, and modifying either this item or \a other will + modify both instances. +*/ + +/*! + \fn QWebEngineHistoryItem::~QWebEngineHistoryItem() + Destroys the history item. +*/ + +/*! + \fn QUrl QWebEngineHistoryItem::originalUrl() const + Returns the original URL associated with the history item. + + \sa url() +*/ + +/*! + \fn QUrl QWebEngineHistoryItem::url() const + Returns the URL associated with the history item. + + \sa originalUrl(), title(), lastVisited() +*/ + +/*! + \fn QString QWebEngineHistoryItem::title() const + Returns the title of the page associated with the history item. + + \sa url(), lastVisited() +*/ + +/*! + \fn QDateTime QWebEngineHistoryItem::lastVisited() const + Returns the date and time when the page associated with the item was last visited. + + \sa title(), url() +*/ + +/*! + \fn bool QWebEngineHistoryItem::isValid() const + Returns whether this is a valid history item. +*/ + +/*! + \class QWebEngineHistoryModel + \inmodule QtWebEngineCore + \since 6.2 + + \brief A data model that represents the history of a web engine page. + + The QWebEngineHistoryModel type exposes the \e title, \e url, \e icon, and \e offset roles. + The \e title, \e url and \e icon specify the title, URL, and favicon of the visited page. + The \e offset specifies the position of the page in respect to the current page (0). + A positive number indicates that the page was visited after the current page, whereas a + negative number indicates that the page was visited before the current page. + + This type is uncreatable, but it can be accessed by using the QWebEngineHistory::itemsModel, + QWebEngineHistory::backItemsModel, QWebEngineHistory::forwardItemsModel methods. + + \sa QWebEngineHistory +*/ + +/*! + \enum QWebEngineHistoryModel::Roles + + This enum describes specific roles, which history data model supports. + + \value UrlRole URL of the visited page + \value TitleRole Title of the visited page + \value OffsetRole The offset of the page in respect to the current page (0) + \value IconUrlRole Favicon of the visited page +*/ + +/*! + \class QWebEngineHistory + \brief The QWebEngineHistory class represents the history of a web engine page. + \since 5.4 + \inmodule QtWebEngineCore + + Each web engine page contains a history of visited pages that can be accessed + by QWebEnginePage::history(). + + The history uses the concept of a \e{current item}, dividing the pages visited + into those that can be visited by navigating \e back and \e forward using the + back() and forward() functions. The current item can be obtained by calling + currentItem(), and an arbitrary item in the history can be made the current + item by passing it to goToItem(). + + A list of items describing the pages that can be visited by going back can be + obtained by calling the backItems() function; similarly, items describing the + pages ahead of the current page can be obtained with the forwardItems() function. + The total list of items is obtained with the items() function. + + Also, the following QWebEngineHistoryModel data model objects are provided: + + \list + \li \c backItemsModel(), which contains the URLs of visited pages. + \li \c forwardItemsModel(), which contains the URLs of the pages that were visited after visiting + the current page. + \li \c itemsModel(), which contains the URLs of the back and forward items, as well as the URL of + the current page. + \endlist + + Just as with containers, functions are available to examine the history in terms + of a list. Arbitrary items in the history can be obtained with itemAt(), the total + number of items is given by count(), and the history can be cleared with the + clear() function. + + QWebEngineHistory's state can be saved to a QDataStream using the >> operator and loaded + by using the << operator. + + \sa QWebEngineHistoryItem, QWebEnginePage +*/ + +/*! + \fn void QWebEngineHistory::clear() + Clears the history. + + \sa count(), items() +*/ + +/*! + \fn QList<QWebEngineHistoryItem> QWebEngineHistory::items() const + Returns a list of all items currently in the history. + + \sa count(), clear() +*/ + +/*! + \fn QList<QWebEngineHistoryItem> QWebEngineHistory::backItems(int maxItems) const + Returns the list of items in the backwards history list. + At most \a maxItems entries are returned. + + \sa forwardItems() +*/ + +/*! + \fn QList<QWebEngineHistoryItem> QWebEngineHistory::forwardItems(int maxItems) const + Returns the list of items in the forward history list. + At most \a maxItems entries are returned. + + \sa backItems() +*/ + +/*! + \fn QWebEngineHistoryModel *QWebEngineHistory::itemsModel() const + Returns the data model, which represents URLs of back items, forward items, + and the current item in the history. +*/ + +/*! + \fn QWebEngineHistoryModel *QWebEngineHistory::backItemsModel() const + Return the data model, which represents URLs of visited pages. +*/ + +/*! + \fn QWebEngineHistoryModel *QWebEngineHistory::forwardItemsModel() const + Return the data model, which represents URLs of the pages + that were visited after visiting the current page. +*/ + +/*! + \fn bool QWebEngineHistory::canGoBack() const + Returns \c true if there is an item preceding the current item in the history; + otherwise returns \c false. + + \sa canGoForward() +*/ + +/*! + \fn bool QWebEngineHistory::canGoForward() const + Returns \c true if we have an item to go forward to; otherwise returns \c false. + + \sa canGoBack() +*/ + +/*! + \fn void QWebEngineHistory::back() + Sets the current item to be the previous item in the history and goes to the + corresponding page; that is, goes back one history item. + + \sa forward(), goToItem() +*/ + +/*! + \fn void QWebEngineHistory::forward() + Sets the current item to be the next item in the history and goes to the + corresponding page; that is, goes forward one history item. + + \sa back(), goToItem() +*/ + +/*! + \fn void QWebEngineHistory::goToItem(const QWebEngineHistoryItem &item) + Sets the current item to be the specified \a item in the history and goes to the page. + + \sa back(), forward() +*/ + +/*! + \fn QWebEngineHistoryItem QWebEngineHistory::backItem() const + Returns the item before the current item in the history. +*/ + +/*! + \fn QWebEngineHistoryItem QWebEngineHistory::currentItem() const + Returns the current item in the history. +*/ + +/*! + \fn QWebEngineHistoryItem QWebEngineHistory::forwardItem() const + Returns the item after the current item in the history. +*/ + +/*! + \fn int QWebEngineHistory::currentItemIndex() const + Returns the index of the current item in history. +*/ + +/*! + \fn QWebEngineHistoryItem QWebEngineHistory::itemAt(int i) const + Returns the item at index \a i in the history. +*/ + +/*! + \fn int QWebEngineHistory::count() const + Returns the total number of items in the history. +*/ + +/*! + \fn QDataStream& operator<<(QDataStream& stream, const QWebEngineHistory& history) + \relates QWebEngineHistory + + Saves the web engine history \a history into \a stream. +*/ + + +/*! + \fn QDataStream& operator>>(QDataStream& stream, QWebEngineHistory& history) + \relates QWebEngineHistory + + Loads the web engine history from \a stream into \a history. +*/ diff --git a/src/core/doc/src/qwebenginepage_lgpl.qdoc b/src/core/doc/src/qwebenginepage_lgpl.qdoc new file mode 100644 index 000000000..c2515cd13 --- /dev/null +++ b/src/core/doc/src/qwebenginepage_lgpl.qdoc @@ -0,0 +1,838 @@ +// 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 +// placed inline in the code as usual. + +/*! + \class QWebEnginePage + \brief The QWebEnginePage class provides an object to view and edit web documents. + \since 5.4 + \inmodule QtWebEngineCore + + A \e {web engine page} holds the contents of an HTML document, the history of navigated + links, and actions. + + QWebEnginePage's API is very similar to QWebEngineView, as you are still provided with + common functions like action() (known as + \l{QWebEngineView::pageAction()}{pageAction}() in QWebEngineView), triggerAction(), + and findText(). + + A page can be loaded using load() or setUrl(). Alternatively, if you have + the HTML content readily available, you can use setHtml(). The GET method is + always used to load URLs. + + The QWebEnginePage class also offers methods to retrieve both the URL currently + loaded by the page (see url()) as well as the URL originally requested + to be loaded (see requestedUrl()). These methods make possible the retrieval + of the URL before and after a DNS resolution or a redirection occurs during + the load process. The requestedUrl() also matches to the URL added to the + page history (\l{QWebEngineHistory}) if load is successful. + + The title of an HTML page can be accessed with the title() property. + Additionally, a page may also specify an icon, which can be accessed + using the icon() or its URL using the iconUrl() property. + If the title or the icon changes, the corresponding titleChanged(), iconChanged() + and iconUrlChanged() signals will be emitted. + The zoomFactor() property enables zooming the contents of the web page by a + scale factor. + + The loadStarted() signal is emitted when the page begins to load, whereas the loadProgress() + signal is emitted whenever an element of the web page completes loading, such as an embedded + image or a script. The loadFinished() signal is emitted when the page contents + have been loaded completely, independent of script execution or page rendering. + Its argument, either \c true or \c false, indicates whether or not the load + operation succeeded. + + An HTML document is loaded in a \e {main frame} within the web page. If it references + \e {child frames} (as defined by the \c <frame> or \c <iframe> elements), they are considered + part of the content. Child frames are individually accessible only through JavaScript. + + Web sites define \e {security origin} for safely accessing each other's resources for + client-side scripting or databases. An origin consist of a host name, a scheme, and a port + number. For example, the sites \c http://www.example.com/my/page.html and + \c http://www.example.com/my/overview.html are allowed to share the same database or access + each other's documents when used in HTML frame sets and JavaScript. At the same time, + \c http://www.malicious.com/evil.html is prevented from accessing the resources of + \c http://www.example.com/, because they are of a different security origin. + By default, local schemes like \c file:// and \c qrc:// are considered to be in the same + security origin, and can access each other's resources. Local resources are by default + restricted from accessing remote content, which means that \c file:// will not be able to + access \c http://domain.com/foo.html. + + Scripts can be executed on the web page by using runJavaScript(), either in the main + JavaScript \e world, along with the rest of the JavaScript coming from the web contents, or in + their own isolated world. While the DOM of the page can be accessed from any world, JavaScript + variables of a function defined in one world are not accessible from a different one. + QWebEngineScript::ScriptWorldId provides some predefined IDs for this purpose. Using the + \c runJavaScript() version without the world ID is the same as running the script in the + \c MainWorld. + + The \l {QWebEngineSettings::FocusOnNavigationEnabled} {FocusOnNavigationEnabled} setting can be + used to make the view associated with the page automatically receive focus when a navigation + operation occurs (like loading or reloading a page or navigating through history). +*/ + +/*! + \enum QWebEnginePage::FindFlag + + This enum describes the options available to the findText() function. The options + can be OR-ed together from the following list: + + \value FindBackward Searches backwards instead of forwards. + \value FindCaseSensitively By default findText() works case insensitive. Specifying this option + changes the behavior to a case sensitive find operation. +*/ + +/*! + \enum QWebEnginePage::WebAction + + This enum describes the types of action which can be performed on the web page. + + Actions only have an effect when they are applicable. + + The availability of actions can be be determined by checking + \l{QAction::}{isEnabled()} on the action returned by action(). + + \value NoWebAction No action is triggered. + \value Back Navigate back in the history of navigated links. + \value Forward Navigate forward in the history of navigated links. + \value Stop Stop loading the current page. + \value Reload Reload the current page. + \value ReloadAndBypassCache Reload the current page, but do not use any local cache. + \value Cut Cut the content currently selected into the clipboard. + \value Copy Copy the content currently selected into the clipboard. + \value Paste Paste content from the clipboard. + \value Undo Undo the last editing action. + \value Redo Redo the last editing action. + \value SelectAll Select all content. This action is only enabled when the page's content is focused. + The focus can be forced by the JavaScript \c{window.focus()} call, or the + \l{QWebEngineSettings::FocusOnNavigationEnabled} {FocusOnNavigationEnabled} setting + should be enabled to get automatic focus. + \value PasteAndMatchStyle Paste content from the clipboard with current style. + + \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. + \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()}. + \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 [since 5.10] ToggleBold + Toggles boldness for the selection or at the cursor position. + Requires \c contenteditable="true". + \value [since 5.10] ToggleItalic + Toggles italics for the selection or at the cursor position. + Requires \c contenteditable="true". + \value [since 5.10] ToggleUnderline + Toggles underlining of the selection or at the cursor position. + Requires \c contenteditable="true". + \value [since 5.10] ToggleStrikethrough + Toggles striking through the selection or at the cursor position. + Requires \c contenteditable="true". + + \value [since 5.10] AlignLeft + Aligns the lines containing the selection or the cursor to the left. + 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". + \value [since 5.10] AlignRight + Aligns the lines containing the selection or the cursor to the right. + 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". + \value [since 5.10] Indent + Indents the lines containing the selection or the cursor. + Requires \c contenteditable="true". + \value [since 5.10] Outdent + Outdents the lines containing the selection or the cursor. + Requires \c contenteditable="true". + + \value [since 5.10] InsertOrderedList + Inserts an ordered list at the current cursor position, deleting the current selection. + 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". + \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 + +*/ + +/*! + \enum QWebEnginePage::WebWindowType + + This enum describes the types of window that can be created by the createWindow() function: + + \value WebBrowserWindow + A complete web browser window. + \value WebBrowserTab + A web browser tab. + \value WebDialog + A window without decoration. + \value [since 5.7] WebBrowserBackgroundTab + A web browser tab without hiding the current visible WebEngineView. +*/ + +/*! + \enum QWebEnginePage::JavaScriptConsoleMessageLevel + + This enum describes the different severity levels a JavaScript console message can have: + + \value InfoMessageLevel The message is purely informative and can safely be ignored. + \value WarningMessageLevel The message informs about unexpected behavior or errors that may + need attention. + \value ErrorMessageLevel The message indicates there has been an error. +*/ + +/*! + \enum QWebEnginePage::FileSelectionMode + + This enum indicates whether the implementation of the chooseFiles() function should + return only one file or may return multiple files: + + \value FileSelectOpen + Return only one file name. + \value FileSelectOpenMultiple + 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() +*/ + +/*! + \enum QWebEnginePage::PermissionPolicy + + This enum describes the permission policies that the user may set for data or device access: + + \value PermissionUnknown It is unknown whether the user grants or denies permission. + \value PermissionGrantedByUser The user has granted permission. + \value PermissionDeniedByUser The user has denied permission. + + \sa featurePermissionRequested(), featurePermissionRequestCanceled(), setFeaturePermission(), Feature +*/ + +/*! + \enum QWebEnginePage::NavigationType + + This enum describes the type of a navigation request: + + \value NavigationTypeLinkClicked The navigation request resulted from a clicked link. + \value NavigationTypeTyped The navigation request resulted from an explicitly loaded URL. + \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 [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() +*/ + +/*! + \enum QWebEnginePage::Feature + + This enum describes the platform feature access categories that the user may be asked to grant + or deny access to: + + \value Notifications + Web notifications for the end-user. + \value Geolocation + Location hardware or service. + \value MediaAudioCapture + Audio capture devices, such as microphones. + \value MediaVideoCapture + Video devices, such as cameras. + \value MediaAudioVideoCapture + Both audio and video capture devices. + \value MouseLock + Mouse locking, which locks the mouse pointer to the web view and is typically used in + games. + \value [since 5.10] DesktopVideoCapture + Video output capture, that is, the capture of the user's display, + 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 + +*/ + +/*! + \fn QWebEnginePage::QWebEnginePage(QObject *parent) + Constructs an empty QWebEnginePage with the parent \a parent. +*/ + +/*! + \fn QWebEnginePage::~QWebEnginePage() + Destroys the web page. +*/ + +/*! + \fn QWebEngineHistory *QWebEnginePage::history() const + Returns a pointer to the view's history of navigated web pages. +*/ + +/*! + \fn void QWebEnginePage::javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level, const QString& message, int lineNumber, const QString& sourceID) + This function is called when a JavaScript program tries to print the \a message to the web + browser's console. + + For example, in case of evaluation errors the source URL may be provided in \a sourceID as well + as the \a lineNumber. + + \a level indicates the severity of the event that triggered the message. That is, whether it + was triggered by an error or a less severe event. + + Since Qt 5.6, the default implementation logs the messages in a \c js + \l{QLoggingCategory}{logging category}. + + \sa{Console Logging} +*/ + +/*! + \fn bool QWebEnginePage::acceptNavigationRequest(const QUrl &url, NavigationType type, bool isMainFrame) + \since 5.5 + This function is called upon receiving a request to navigate to the specified \a url by means of + the specified navigation type \a type. \a isMainFrame indicates whether the request corresponds + to the main frame or a child frame. If the function returns \c true, the navigation request is + accepted and \c url is loaded. The default implementation accepts all navigation requests. + + Navigation requests can be delegated to the Qt application instead of having the HTML handler + engine process them by overloading this function. This is necessary when an HTML document is + used as part of the user interface, and not to display external data, for example, when + displaying a list of results. + + \note This function is not called for fragment navigation on the same page. Such navigation, + for example, happens by clicking a link to a '#fragment' within the page. It does not trigger + a load to a different document, even though it changes page's url and adds history entry. + It only serves as a shortcut to scroll within the page. Hence, no delegation of this navigation + type is expected to happen. + + \note The loading process is started and the loadStarted() signal is emitted + \e before the request is accepted or rejected. Therefore, a loadFinished() + signal that returns \c false is to be expected even after delegating the + request. + + \note When using setHtml or setContent with relative links, make + sure to specify a base url, otherwise the links will be considered + invalid and no navigation requests will be emitted. + + The \l{QWebEngineUrlRequestInterceptor} class offers further options for intercepting and + manipulating requests. +*/ + +/*! + \fn void QWebEnginePage::javaScriptAlert(const QUrl &securityOrigin, const QString& msg) + This function is called whenever a JavaScript program running in a frame affiliated with + \a securityOrigin calls the \c alert() function with the message \a msg. + + The default implementation shows the message, \a msg, with QMessageBox::information. +*/ + +/*! + \fn bool QWebEnginePage::javaScriptConfirm(const QUrl &securityOrigin, const QString& msg) + This function is called whenever a JavaScript program running in a frame affiliated with + \a securityOrigin calls the \c confirm() function with the message \a msg. Returns \c true + if the user confirms the message; otherwise returns \c false. + + It is also called when the \c onbeforeunload handler is requesting a confirmation before + leaving a page. + + The default implementation executes the query using QMessageBox::information with QMessageBox::Ok and QMessageBox::Cancel buttons. +*/ + +/*! + \fn bool QWebEnginePage::javaScriptPrompt(const QUrl &securityOrigin, const QString& msg, const QString& defaultValue, QString* result) + This function is called whenever a JavaScript program running in a frame affiliated with \a securityOrigin tries to prompt the user for input. + The program may provide an optional message, \a msg, as well as a default value for the input in \a defaultValue. + + If the prompt was cancelled by the user, the implementation should return \c false; otherwise the + result should be written to \a result and \c true should be returned. If the prompt was not + cancelled by the user, the implementation should return \c true and the result string must not + be null. + + The default implementation uses QInputDialog::getText(). +*/ + +/*! + \fn QWebEnginePage *QWebEnginePage::createWindow(WebWindowType type) + This function is called to create a new window of the specified \a type. For example, when a + JavaScript program requests to open a document in a new window. + + If the new window can be created, the new window's QWebEnginePage is returned; otherwise a null pointer is returned. + + If the view associated with the web page is a QWebEngineView object, then the default implementation forwards + the request to QWebEngineView::createWindow(); otherwise it returns a null pointer. + + If this call is not implemented or does not return a new page, \l newWindowRequested() + is emitted to handle the request. + + \note In the cases when the window creation is being triggered by JavaScript, apart from + reimplementing this method the application must also set + QWebEngineSettings::JavascriptCanOpenWindows to \c true in order for the method to get called. + + \sa QWebEngineView::createWindow(), newWindowRequested() +*/ + +/*! + \fn void QWebEnginePage::triggerAction(WebAction action, bool checked = false) + This function can be called to trigger the specified \a action. + It is also called by \QWE if the user triggers the action, for example + through a context menu item. + + If \a action is a checkable action, then \a checked specifies whether the action + is toggled or not. + + \sa action() +*/ + +/*! + \property QWebEnginePage::hasSelection + \brief Whether this page contains selected content or not. + + \sa selectionChanged() +*/ + +/*! + \property QWebEnginePage::selectedText + \brief The text currently selected. + + By default, this property contains an empty string. + + \sa selectionChanged() +*/ + +/*! + \fn QAction *QWebEnginePage::action(WebAction action) const + Returns a QAction for the specified WebAction \a action. + + 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. + + \sa triggerAction() +*/ + +/*! + \fn void QWebEnginePage::findText(const QString &subString, QWebEnginePage::FindFlags options = {}, const std::function<void(const QWebEngineFindTextResult &)> &resultCallback = std::function<void(const QWebEngineFindTextResult &)>) + Finds the specified string, \a subString, in the page, using the given \a options. + The findTextFinished() signal is emitted when a string search is completed. + + To clear the search highlight, just pass an empty string. + + The \a resultCallback must take a QWebEngineFindTextResult parameter. + + \warning We guarantee that the callback (\a resultCallback) is always called, but it might be done + during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid + value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it. + + For example: + \snippet qtwebengine_qwebenginepage_snippet.cpp 0 + + \sa findTextFinished() +*/ + +/*! + \fn QWebEngineSettings *QWebEnginePage::settings() const + Returns a pointer to the page's settings object. +*/ + +/*! + \fn void QWebEnginePage::certificateError(const QWebEngineCertificateError & certificateError) + This signal is emitted when an invalid certificate error is raised while loading a given request. + + The \a certificateError parameter contains information about the certificate and details of the error, + it also provides the way to ignore the error and complete the request or stop loading + the request. + + \sa QWebEngineCertificateError +*/ + +/*! + \fn QString QWebEnginePage::chooseFiles(FileSelectionMode mode, const QStringList& oldFiles, const QStringList& acceptedMimeTypes) + This function is called when the web content requests a file name, for example + as a result of the user clicking on a file upload button in an HTML form. + + \a mode indicates whether only one file or multiple files are expected to be returned. + + A suggested filename may be provided as the first entry of \a oldFiles. \a acceptedMimeTypes is ignored by the default implementation, + but might be used by overrides. +*/ + +/*! + \fn void QWebEnginePage::loadStarted() + + This signal is emitted when a page starts loading content. + + \sa loadFinished(), acceptNavigationRequest() +*/ + +/*! + \fn void QWebEnginePage::loadProgress(int progress) + + This signal is emitted when the global progress status changes. + The current value is provided by \a progress and scales from 0 to 100, + which is the default range of QProgressBar. + It accumulates changes from all the child frames. + +*/ + +/*! + \fn void QWebEnginePage::loadFinished(bool ok) + + This signal is emitted when the page finishes loading content. This signal + is independent of script execution or page rendering. + \a ok will indicate whether the load was successful or any error occurred. + + \note Navigation requests can be delegated to the Qt application instead + of having the HTML handler engine process them by overloading the + acceptNavigationRequest() function. Because the loading process is started + and the loadStarted() signal is emitted \e before the request is accepted + or rejected, a \c loadFinished() signal that returns \c false is to be + expected even after delegating the request. + + \sa loadStarted(), acceptNavigationRequest() +*/ + +/*! + \fn void QWebEnginePage::selectionChanged() + + This signal is emitted whenever the selection changes, either interactively + or programmatically. For example, by calling triggerAction() with a selection action. + + \note When using the mouse to select text by left-clicking and dragging, the signal will be + emitted for each new character selected, and not upon releasing the left mouse button. + + \sa selectedText() +*/ + +/*! + \fn void QWebEnginePage::linkHovered(const QString &url) + + This signal is emitted when the mouse hovers over a link. + \a url contains the target URL of the link. +*/ + +/*! + + \fn void QWebEnginePage::authenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator) + + This signal is emitted when access to \a requestUrl requires authentication. + \a authenticator should be used to pass the user name and password for the connection. +*/ + +/*! + \fn void QWebEnginePage::proxyAuthenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator, const QString &proxyHost) + + This signal is emitted when access to \a requestUrl via \a proxyHost requires authentication for the proxy. + \a authenticator should be used to pass the user name and password for the connection. + +*/ + +/*! + \fn void QWebEnginePage::geometryChangeRequested(const QRect& geom) + + This signal is emitted whenever the document wants to change the position and size of the + page to \a geom. This can happen for example through JavaScript. + + \note \l{QWindow::}{setGeometry()} expects a size excluding the window + decoration, while \a geom includes it. You have to remove the size of the frame margins + from \a geom to handle this signal correctly. + + \code + window->setGeometry(geom.marginsRemoved(window->frameMargins())); + \endcode +*/ + +/*! + \fn void QWebEnginePage::windowCloseRequested() + + This signal is emitted whenever the page requests the web browser window to be closed, + for example through the JavaScript \c{window.close()} call. + + \sa RequestClose +*/ + +/*! + \fn void QWebEnginePage::toHtml(const std::function<void(const QString &)> &resultCallback) const + Asynchronous method to retrieve the page's content as HTML, enclosed in HTML and BODY tags. + Upon successful completion, \a resultCallback is called with the page's content. + + \note \a resultCallback can be any of a function pointer, a functor or a lambda, and it is expected to take a QString parameter. + + \warning We guarantee that the callback (\a resultCallback) is always called, but it might be done + during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid + value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it. + + \sa setHtml(), toPlainText() +*/ + +/*! + \fn void QWebEnginePage::toPlainText(const std::function<void(const QString &)> &resultCallback) const + Asynchronous method to retrieve the page's content converted to plain text, completely stripped of all + HTML formatting. + Upon successful completion, \a resultCallback is called with the page's content. + + \note \a resultCallback can be any of a function pointer, a functor or a lambda, and it is expected to take a QString parameter. + + \warning We guarantee that the callback (\a resultCallback) is always called, but it might be done + during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid + value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it. + + \sa toHtml() +*/ + +/*! + \property QWebEnginePage::title + \brief The title of the page as defined by the HTML \c <title> element. + + If the page has no \c <title> element, then the URL is used instead. For \c + file:// URLs only the filename is used and not the full path. + + By default, before any content has been loaded, this property contains an + empty string. + + \sa titleChanged() +*/ + +/*! + \property QWebEnginePage::url + \brief The URL of the page currently viewed. + + Setting this property clears the view and loads the URL. + + By default, this property contains an empty, invalid URL. + + \sa urlChanged() +*/ + +/*! + \property QWebEnginePage::requestedUrl + \brief The URL that was originally requested to be loaded by the page + that is currently viewed. + + \note The URL may differ from the one returned by url(), which is the actual + URL that results from DNS resolution or redirection. + + \sa url(), setUrl() +*/ + +/*! + \fn void QWebEnginePage::load(const QUrl &url) + Loads \a url into this page. + + \note The view remains the same until enough data has arrived to display the new URL. + + \sa setUrl(), setHtml(), setContent() +*/ + +/*! + \fn void QWebEnginePage::setHtml(const QString &html, const QUrl &baseUrl) + Sets the content of this page to \a html. \a baseUrl is optional and used to resolve relative + URLs in the document, such as referenced images or stylesheets. + + The \a html is loaded immediately; external objects are loaded asynchronously. + + If a script in the \a html runs longer than the default script timeout (currently 10 seconds), + for example due to being blocked by a modal JavaScript alert dialog, this method will return + as soon as possible after the timeout and any subsequent \a html will be loaded asynchronously. + + When using this method, the web engine assumes that external resources, such as JavaScript programs or style + sheets, are encoded in UTF-8 unless otherwise specified. For example, the encoding of an external + script can be specified through the charset attribute of the HTML script tag. It is also possible + for the encoding to be specified by the web server. + + This is a convenience function equivalent to setContent(html, "text/html", baseUrl). + + \note This method will not affect session or global history for the page. + + \warning This function works only for HTML, for other mime types (such as XHTML and SVG) + setContent() should be used instead. + + \warning The content will be percent encoded before being sent to the renderer via IPC. + This may increase its size. The maximum size of the percent encoded content is + 2 megabytes minus 30 bytes. + + \sa toHtml(), setContent(), load() +*/ + +/*! + \fn void QWebEnginePage::setContent(const QByteArray &data, const QString &mimeType, const QUrl &baseUrl) + Sets the content of the web page to \a data. If the \a mimeType argument + 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. + + \note This method will not affect session or global history for the page. + + \warning The content will be percent encoded before being sent to the renderer via IPC. + This may increase its size. The maximum size of the percent encoded content is + 2 megabytes minus 6 bytes plus the length of the mime type string. + + \sa toHtml(), setHtml() +*/ + +/*! + \property QWebEnginePage::zoomFactor + \brief The zoom factor for the page content. + + Valid values are within the range from \c{0.25} to \c{5.0}. The default factor is \c{1.0}. +*/ + +/*! + \fn void QWebEnginePage::runJavaScript(const QString &scriptSource, quint32 worldId = 0, const std::function<void(const QVariant &)> &resultCallback = {}) + \fn void QWebEnginePage::runJavaScript(const QString &scriptSource, const std::function<void(const QVariant &)> &resultCallback) + \since 5.7 + + Runs the JavaScript code contained in \a scriptSource without checking + whether the DOM of the page has been constructed. If you need more + control over how the script is run, consider using \l scripts() instead. + + To avoid conflicts with other scripts executed on the page, the world in + which the script is run is specified by \a worldId. The world ID values are + the same as provided by QWebEngineScript::ScriptWorldId, and between \c 0 + and \c 256. If you leave out the \c world ID, the script is run in the + \c MainWorld. + + When the script has been executed, \a resultCallback is called with the result of the last + executed statement. \c resultCallback can be any of a function pointer, a functor or a lambda, + and it is expected to take a QVariant parameter. For example: + + \code + page.runJavaScript("document.title", [](const QVariant &v) { qDebug() << v.toString(); }); + \endcode + + Only plain data can be returned from JavaScript as the result value. + Supported data types include all of the JSON data types as well as, for + example, \c{Date} and \c{ArrayBuffer}. Unsupported data types include, for + example, \c{Function} and \c{Promise}. + + \warning Do not execute lengthy routines in the callback function, because it might block the + rendering of the web engine page. + + \warning We guarantee that the callback (\a resultCallback) is always called, but it might be done + during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid + value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it. + + \sa scripts(), QWebEngineScript::ScriptWorldId, {Script Injection} +*/ + +/*! + \fn void QWebEnginePage::setFeaturePermission(const QUrl &securityOrigin, Feature feature, PermissionPolicy policy) + + Sets the permission for the web site identified by \a securityOrigin to use \a feature to \a policy. + + \note This method is primarily for calling after a featurePermissionRequested() signal has been emitted + to trigger the feature permission response. It can also be called before a request has been emitted, + but will only set a granted permission for passive checks, mainly for Notification APIs that can check + if permission has already been granted before explicitly requesting it. + + \sa featurePermissionRequested(), featurePermissionRequestCanceled() +*/ + +/*! + \fn void QWebEnginePage::featurePermissionRequested(const QUrl &securityOrigin, Feature feature) + + This signal is emitted when the web site identified by \a securityOrigin requests to make use of + the resource or device identified by \a feature. + + \sa featurePermissionRequestCanceled(), setFeaturePermission() +*/ + +/*! + \fn void QWebEnginePage::featurePermissionRequestCanceled(const QUrl &securityOrigin, Feature feature) + + This signal is emitted when the web site identified by \a securityOrigin cancels a previously issued + request to make use of \a feature. + + \sa featurePermissionRequested(), setFeaturePermission() + +*/ + +/*! + \fn void QWebEnginePage::titleChanged(const QString &title) + + This signal is emitted whenever the title of the page changes. + The \a title string specifies the new title. + + \sa title() +*/ + +/*! + \fn void QWebEnginePage::urlChanged(const QUrl &url) + + This signal is emitted with the URL of the page when the page title is + received. The new URL is specified by \a url. + + \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 new file mode 100644 index 000000000..cd7ff8e8c --- /dev/null +++ b/src/core/doc/src/qwebenginesettings_lgpl.qdoc @@ -0,0 +1,332 @@ +// 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 +// placed inline in the code as usual. + +/*! + \class QWebEngineSettings + \since 5.4 + \brief The QWebEngineSettings class provides an object to store the settings used + by QWebEnginePage. + + \inmodule QtWebEngineCore + + QWebEngineSettings allows configuration of browser properties, such as font sizes and + 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 + settings for that page. If a setting is not configured for a web engine + page, it is looked up in the settings of the profile the page belongs to. + + \sa QWebEnginePage::settings(), QWebEngineView::settings() +*/ + +/*! + \enum QWebEngineSettings::FontFamily + + This enum describes the generic font families defined by CSS 2. + For more information see the + \l{http://www.w3.org/TR/REC-CSS2/fonts.html#generic-font-families}{CSS standard}. + + \value StandardFont + \value FixedFont + \value SerifFont + \value SansSerifFont + \value CursiveFont + \value FantasyFont + \value PictographFont + (added in Qt 5.7, deprecated Qt 6.4) +*/ + +/*! + \enum QWebEngineSettings::FontSize + + This enum describes the font sizes configurable through QWebEngineSettings: + + \value MinimumFontSize The hard minimum font size. + \value MinimumLogicalFontSize The minimum logical font size that is applied + when zooming out. + \value DefaultFontSize The default font size for regular text. + \value DefaultFixedFontSize The default font size for fixed-pitch text. +*/ + +/*! + \enum QWebEngineSettings::WebAttribute + + This enum type specifies settings for web pages: + + \value AutoLoadImages + Automatically dowloads images for web pages. When this setting is + disabled, images are loaded from the cache. Enabled by default. + \value JavascriptEnabled + Enables the running of JavaScript programs in the + \l{QWebEngineScript::MainWorld}{MainWorld}. Enabled by default. + \value JavascriptCanOpenWindows + Allows JavaScript programs to open popup windows without user + interaction. Enabled by default. + \value JavascriptCanAccessClipboard + 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. 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 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 + Enables the Spatial Navigation feature, which means the ability to navigate between + focusable elements, such as hyperlinks and form controls, on a web page by using the + Left, Right, Up and Down arrow keys. For example, if a user presses the + Right key, heuristics determine whether there is an element they might be + 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. 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 + Enables animated scrolling. Disabled by default. + \value ErrorPageEnabled + Enables displaying the built-in error pages of Chromium. Enabled by default. + \value PluginsEnabled + Enables support for Pepper plugins, such as the Flash player. Disabled by default. + See also \l{Pepper Plugin API}. (Added in Qt 5.6) + \value FullScreenSupportEnabled + Enables fullscreen support in an application. Disabled by default. (Added in Qt 5.6) + \value ScreenCaptureEnabled + Enables screen capture in an application. Disabled by default. (Added in Qt 5.7) + \value WebGLEnabled + Enables support for HTML 5 WebGL. Enabled by default if available. (Added in Qt 5.7) + \value Accelerated2dCanvasEnabled + Specifies whether the HTML5 2D canvas should be a OpenGL framebuffer. + This makes many painting operations faster, but slows down pixel access. Enabled by default if available. (Added in Qt 5.7) + \value AutoLoadIconsForPage + Automatically downloads icons for web pages. Enabled by default. (Added in Qt 5.7) + \value TouchIconsEnabled + Enables support for touch icons and precomposed touch icons + Disabled by default. (Added in Qt 5.7) + \value FocusOnNavigationEnabled + Gives focus to the view associated with the page, whenever a navigation operation occurs + (load, stop, reload, reload and bypass cache, forward, backward, set content, and so + on). + Disabled by default. (Added in Qt 5.8) + \value PrintElementBackgrounds + Turns on printing of CSS backgrounds when printing a web page. + Enabled by default. (Added in Qt 5.8) + \value AllowRunningInsecureContent + By default, HTTPS pages cannot run JavaScript, CSS, plugins or + web-sockets from HTTP URLs. This provides an override to get + the old insecure behavior. + Disabled by default. (Added in Qt 5.8) + \value AllowGeolocationOnInsecureOrigins + Since Qt 5.7, only secure origins such as HTTPS have been able to request + Geolocation features. This provides an override to allow non secure + origins to access Geolocation again. + Disabled by default. (Added in Qt 5.9) + \value AllowWindowActivationFromJavaScript + Allows activating windows by using the window.focus() JavaScript + method. Disabled by default. + (Added in Qt 5.10) + \value ShowScrollBars + Shows scroll bars. + Enabled by default. (Added in Qt 5.10) + \value PlaybackRequiresUserGesture + Inhibits playback of media content until the user interacts with + the page. By default, WebEngine uses Chromium settings, as described + in \l {Autoplay Policy Changes}. This is similar to how Chrome on + Android behaves, while the default behavior when it is disabled is + 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. 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 + local network IP addresses, but remote hosts can also see your local network + IP address. + Disabled by default. (Added in Qt 5.11) + \value DnsPrefetchEnabled Specifies whether WebEngine will try to pre-fetch DNS entries to + speed up browsing. + Disabled by default. (Added in Qt 5.12) + \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) +*/ + +/*! + \enum QWebEngineSettings::UnknownUrlSchemePolicy + \since Qt 5.11 + + This enum describes how navigation requests to URLs with unknown schemes are handled. + + \value DisallowUnknownUrlSchemes + Disallows all navigation requests to URLs with unknown schemes. + \value AllowUnknownUrlSchemesFromUserInteraction + Allows navigation requests to URLs with unknown schemes that are issued from + user-interaction (like a mouse-click), whereas other navigation requests (for example + from JavaScript) are suppressed. + \value AllowAllUnknownUrlSchemes + Allows all navigation requests to URLs with unknown schemes. + \omitvalue InheritedUnknownUrlSchemePolicy + + \sa unknownUrlSchemePolicy setUnknownUrlSchemePolicy resetUnknownUrlSchemePolicy +*/ + +/*! + \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. +*/ + +/*! + \fn int QWebEngineSettings::fontSize(FontSize type) const + Returns the default font size for \a type in pixels. +*/ + +/*! + \fn void QWebEngineSettings::resetFontSize(FontSize type) + Resets the font size for \a type to the size specified in the profile that + the page belongs to. +*/ + +/*! + \fn void QWebEngineSettings::setDefaultTextEncoding(const QString& encoding) + Specifies the default text encoding system. + + The value of \a encoding must be a string describing an encoding such as "utf-8" or + "iso-8859-1". If left empty, a default value will be used. For a more + extensive list of encoding names see \l{QTextCodec}. + + \sa defaultTextEncoding() +*/ + +/*! + \fn QString QWebEngineSettings::defaultTextEncoding() const + Returns the default text encoding. + + \sa setDefaultTextEncoding() +*/ + +/*! + \fn QString QWebEngineSettings::fontFamily(FontFamily which) const + Returns the actual font family for the specified generic font family, + \a which. +*/ + +/*! + \fn void QWebEngineSettings::resetFontFamily(FontFamily which) + Resets the actual font family specified by \a which to the one specified + in the profile that the page belongs to. +*/ + +/*! + \fn QWebEngineSettings::UnknownUrlSchemePolicy QWebEngineSettings::unknownUrlSchemePolicy() const + \since Qt 5.11 + Returns the currently selected policy for handling navigation requests to URLs with + unknown schemes. Default is \l{QWebEngineSettings::AllowUnknownUrlSchemesFromUserInteraction}. + \sa setUnknownUrlSchemePolicy resetUnknownUrlSchemePolicy +*/ + +/*! + \fn void QWebEngineSettings::setUnknownUrlSchemePolicy(QWebEngineSettings::UnknownUrlSchemePolicy policy) + \since Qt 5.11 + Sets the policy for handling navigation requests to URLs with unknown schemes to \a policy. + Default is \l{QWebEngineSettings::AllowUnknownUrlSchemesFromUserInteraction}. + \sa unknownUrlSchemePolicy resetUnknownUrlSchemePolicy +*/ + +/*! + \fn void QWebEngineSettings::resetUnknownUrlSchemePolicy() + \since Qt 5.11 + Removes the policy for handling navigation requests to URLs with unknown schemes. + \sa unknownUrlSchemePolicy setUnknownUrlSchemePolicy +*/ + +/*! + \fn void QWebEngineSettings::setAttribute(WebAttribute attribute, bool on) + + Enables or disables the specified \a attribute feature depending on the + value of \a on. +*/ + +/*! + \fn bool QWebEngineSettings::testAttribute(WebAttribute attribute) const + + Returns \c true if \a attribute is enabled; otherwise returns \c false. +*/ + +/*! + \fn void QWebEngineSettings::resetAttribute(WebAttribute attribute) + + 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 +*/ |