From 5df6af0652939c8bad85ca7c8d5b948c0a1a6255 Mon Sep 17 00:00:00 2001 From: Allan Sandfeld Jensen Date: Thu, 19 Aug 2021 10:47:42 +0200 Subject: Move the rest of the super module documentation to core module Previously parts were moved, but these were left behind in the quick module. Change-Id: Icef469e14d073170ec5b2296048874d2b7439385 Reviewed-by: Kirill Burtsev (cherry picked from commit dbc4a6f5a74c6903a24f3cc377887fd47d67b5e1) Reviewed-by: Qt Cherry-pick Bot --- src/core/doc/src/external-resources.qdoc | 146 +++++ src/core/doc/src/qtwebengine-debugging.qdoc | 117 ++++ src/core/doc/src/qtwebengine-deploying.qdoc | 158 +++++ src/core/doc/src/qtwebengine-features.qdoc | 683 +++++++++++++++++++++ src/core/doc/src/qtwebengine-index.qdoc | 71 +++ src/core/doc/src/qtwebengine-modules.qdoc | 48 ++ src/core/doc/src/qtwebengine-overview.qdoc | 315 ++++++++++ src/core/doc/src/qtwebengine-platform-notes.qdoc | 238 +++++++ src/core/doc/src/qwebengine-licensing.qdoc | 53 ++ src/webenginequick/doc/src/external-resources.qdoc | 146 ----- .../doc/src/qtwebengine-debugging.qdoc | 117 ---- .../doc/src/qtwebengine-deploying.qdoc | 158 ----- .../doc/src/qtwebengine-features.qdoc | 683 --------------------- src/webenginequick/doc/src/qtwebengine-index.qdoc | 71 --- .../doc/src/qtwebengine-modules.qdoc | 48 -- .../doc/src/qtwebengine-overview.qdoc | 315 ---------- .../doc/src/qtwebengine-platform-notes.qdoc | 238 ------- .../doc/src/qwebengine-licensing.qdoc | 53 -- 18 files changed, 1829 insertions(+), 1829 deletions(-) create mode 100644 src/core/doc/src/external-resources.qdoc create mode 100644 src/core/doc/src/qtwebengine-debugging.qdoc create mode 100644 src/core/doc/src/qtwebengine-deploying.qdoc create mode 100644 src/core/doc/src/qtwebengine-features.qdoc create mode 100644 src/core/doc/src/qtwebengine-index.qdoc create mode 100644 src/core/doc/src/qtwebengine-modules.qdoc create mode 100644 src/core/doc/src/qtwebengine-overview.qdoc create mode 100644 src/core/doc/src/qtwebengine-platform-notes.qdoc create mode 100644 src/core/doc/src/qwebengine-licensing.qdoc delete mode 100644 src/webenginequick/doc/src/external-resources.qdoc delete mode 100644 src/webenginequick/doc/src/qtwebengine-debugging.qdoc delete mode 100644 src/webenginequick/doc/src/qtwebengine-deploying.qdoc delete mode 100644 src/webenginequick/doc/src/qtwebengine-features.qdoc delete mode 100644 src/webenginequick/doc/src/qtwebengine-index.qdoc delete mode 100644 src/webenginequick/doc/src/qtwebengine-modules.qdoc delete mode 100644 src/webenginequick/doc/src/qtwebengine-overview.qdoc delete mode 100644 src/webenginequick/doc/src/qtwebengine-platform-notes.qdoc delete mode 100644 src/webenginequick/doc/src/qwebengine-licensing.qdoc diff --git a/src/core/doc/src/external-resources.qdoc b/src/core/doc/src/external-resources.qdoc new file mode 100644 index 000000000..24648b848 --- /dev/null +++ b/src/core/doc/src/external-resources.qdoc @@ -0,0 +1,146 @@ +/**************************************************************************** +** +** Copyright (C) 2017 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$ +** +****************************************************************************/ + +/*! + \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 +*/ diff --git a/src/core/doc/src/qtwebengine-debugging.qdoc b/src/core/doc/src/qtwebengine-debugging.qdoc new file mode 100644 index 000000000..f84cca312 --- /dev/null +++ b/src/core/doc/src/qtwebengine-debugging.qdoc @@ -0,0 +1,117 @@ +/**************************************************************************** +** +** Copyright (C) 2017 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$ +** +****************************************************************************/ + +/*! + \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 arguments: + + \badcode + --remote-debugging-port= + \endcode + + Where \c refers to a local network port. The web developer + tools can then be accessed by launching a browser at the address + \c http://localhost:. + + 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. + + 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 {qputenv} from within the + application if called before QtWebEngineQuick::initialize(). +*/ diff --git a/src/core/doc/src/qtwebengine-deploying.qdoc b/src/core/doc/src/qtwebengine-deploying.qdoc new file mode 100644 index 000000000..7b9f3fd4a --- /dev/null +++ b/src/core/doc/src/qtwebengine-deploying.qdoc @@ -0,0 +1,158 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page qtwebengine-deploying.html + \title Deploying Qt WebEngine Applications + + 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. + \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 + \endlist + + \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 + + \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 + +*/ diff --git a/src/core/doc/src/qtwebengine-features.qdoc b/src/core/doc/src/qtwebengine-features.qdoc new file mode 100644 index 000000000..24bc9d7aa --- /dev/null +++ b/src/core/doc/src/qtwebengine-features.qdoc @@ -0,0 +1,683 @@ +/**************************************************************************** +** +** Copyright (C) 2019 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtwebengine-features.html + \title Qt WebEngine Features + + \brief Summarizes \QWE features. + + \QWE supports the following features: + + \list + \li \l{Audio and Video Codecs} + \li \l{Chromium DevTools} + \li \l{Client Certificates} + \li \l{Custom Schemes} + \li \l{Drag and Drop} + \li \l{Fullscreen} + \li \l{HTML5 DRM} + \li \l{HTML5 Geolocation} + \li \l{HTTP/2 Protocol} + \li \l{Native Dialogs} + \li \l{Pepper Plugin API} + \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{webrtc_feature}{WebRTC} + \li \l{Web Notifications} + \li \l{Favicon Handling} + \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: + + \code + -webengine-proprietary-codecs + \endcode + + For example, the following option could be passed when configuring Qt for + building it at the top level: + + \code + configure -webengine-proprietary-codecs + \endcode + + For more information, see \l{Qt Configure Options}. + + When using qmake to build just the \QWE module, the following + command can be used (in this example, the \QWE source code is + located in \c {C:\qt\qtwebengine}): + + \code + qmake C:\qt\qtwebengine -- -webengine-proprietary-codecs + \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 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]}. + + 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. + + \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 compoments 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 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 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: + \code + set QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="C:/some path/widevinecdm.dll" + \endcode + + On Linux: + \code + export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.so" + \endcode + + On macOS: + \code + 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 Location} as a + backend. The application has to explicitly allow the feature by using + QWebEnginePage::Geolocation or \l{WebEngineView::Feature} + {WebEngineView.Feature}. + + If Qt Location has been built before \QWE then this feature can be + tested by using \l{WebEngine Widgets Maps Example}{Maps} and allowing it to + find the current position of the user. Note that on Windows an external GPS + receiver must be connected to the application. For more information, see + \l{Qt Positioning}. + + Support for this feature was added in Qt 5.5.0. + + \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 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, + see \l{WebEngine Qt Quick Custom Dialogs Example}. + + \section1 Pepper Plugin API + + \QWE supports loading Pepper Plugin API (PPAPI) plugins if + WebEngineSettings::pluginsEnabled or QWebEngineSettings::PluginsEnabled + is set. + + Except for the Adobe Flash Player plugin, the plugins must be loaded + manually using the Chromium command line syntax with the + \c --register-pepper-plugins argument. The argument value is a list of + entries, separated by commas, that contain the file path and one or several + MIME types, separated by semicolons: + + \code + ;,;; + \endcode + + For example: + + \code + --register-pepper-plugins="libppapi_example.so;application/x-ppapi-example" + \endcode + + The MIME type is important because it determines which embeds the plugin is + used for. + + Support for this feature was added in Qt 5.6.0. + + \section2 Pepper Flash Player Plugin Support + + The Pepper Flash player plugin can be loaded automatically if it is + installed in one of the following locations, depending on the platform: + + \list + \li Windows + \code + C:\Windows\SysWOW64\Macromed\Flash\pepflashplayer*.dll + C:\Windows\System32\Macromed\Flash\pepflashplayer*.dll + \endcode + \li OS X + \code + /Library/Internet Plug-Ins/PepperFlashPlayer/PepperFlashPlayer.plugin + \endcode + \li Linux + \code + /usr/lib/pepperflashplugin-nonfree/libpepflashplayer.so + /usr/lib/adobe-flashplugin/libpepflashplayer.so + /usr/lib/PepperFlash/libpepflashplayer.so + /usr/lib64/chromium/PepperFlash/libpepflashplayer.so + \endcode + \endlist + + You can also load the Pepper Flash player from a specific location by using + command line arguments: + + \code + --ppapi-flash-path=./libpepflashplayer.so + \endcode + + By default, the Flash version is set to \c{11.2.999.999}. You can use the + \c{ppapi-flash-version=} argument to set another Flash version in the + format \c{major.minor.build.revision}: + + \code + --ppapi-flash-version=16.0.0.235 + \endcode + + This feature can be tested in \l{WebEngine Widgets Simple Browser Example}{Simple Browser} + or \l{WebEngine Quick Nano Browser}{Nano Browser} if the Adobe Flash PPAPI + plugin is installed and plugins are enabled in the browser. To test the + feature, the \c https://helpx.adobe.com/flash-player.html page can be opened + in the browser. + + \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}. + + 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: + \code + view-source:https://www.qt.io/ + \endcode + + Auto-completion of incomplete URLs with \l{view-source URI scheme} makes the usage of + this feature more comfortable. For example, the following incomplete URL also loads + the source view of the qt.io web page: + \code + view-source:qt.io + \endcode + + Support for this feature was added in Qt 5.8.0. + + \target webrtc_feature + \section1 WebRTC + + WebRTC provides browsers with Real-Time Communications (RTC) capabilities + via simple APIs. For more information, see \l{WebEngineView::Feature} + {WebEngineView.Feature} and QWebEnginePage::Feature. + + This feature can be tested by setting up a webcam or microphone and then + opening \c https://test.webrtc.org/ in \l{WebEngine Widgets Simple Browser + Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}. + + \section1 Web Notifications + + Qt WebEngine supports JavaScript \l{Web Notifications API}. + 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 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". + For example, + \qml + Image { + source: "image://favicon/url" + } + \endqml + + The \c url can be the URL of the favicon. For example, + \qml + Image { + source: "image://favicon/https://www.qt.io/hubfs/2016_Qt_Logo/qt_logo_green_rgb_16x16.png" + } + \endqml + + The \c url also can be a page URL to access its icon. For example, + \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. + + \note The icon database is not available for off-the-record profiles. +*/ diff --git a/src/core/doc/src/qtwebengine-index.qdoc b/src/core/doc/src/qtwebengine-index.qdoc new file mode 100644 index 000000000..725b80637 --- /dev/null +++ b/src/core/doc/src/qtwebengine-index.qdoc @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \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 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..759284ad9 --- /dev/null +++ b/src/core/doc/src/qtwebengine-modules.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page qtwebengine-modules.html + \title Qt WebEngine C++ Classes and Namespaces + \brief Provides functionality for rendering regions of dynamic web content. + + \e {Qt WebEngine} provides functionality for rendering regions of dynamic web content. + + \section1 Namespaces + \annotatedlist qtwebengine-namespaces + + \section1 Classes + + \section2 Qt WebEngineCore Module + \generatelist {classesbymodule QtWebEngineCore} + + \section2 Qt WebEngineWidgets Module + \generatelist {classesbymodule QtWebEngineWidgets} + + \section2 Qt WebEngineQuick 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..099142f80 --- /dev/null +++ b/src/core/doc/src/qtwebengine-overview.qdoc @@ -0,0 +1,315 @@ +/**************************************************************************** +** +** Copyright (C) 2017 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$ +** +****************************************************************************/ + +/*! + \page qtwebengine-overview.html + \title Qt WebEngine Overview + + 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. + + \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. + + This version of \QWE is based on Chromium version 87.0.4280, with additional security + fixes from newer versions. + + \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) + { + QApplication app(argc, argv); + + QtWebEngineQuick::initialize(); + + 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 webengine/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 } + \li \c {@include } + \li \c {@match } + \li \c {@name } + \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::error} 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..08eaf72bb --- /dev/null +++ b/src/core/doc/src/qtwebengine-platform-notes.qdoc @@ -0,0 +1,238 @@ +/**************************************************************************** +** +** Copyright (C) 2020 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$ +** +****************************************************************************/ + +/*! + \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 5 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 + + The tests for skipping the \QWE build are located in the + \c qtwebengine repository, in the \c tools\qmake\mkspecs subdirectory. + They can be found by searching for \c skipBuild. + + \section2 All Platforms + + On all platforms, the following tools are required at build time: + + \list + \li \l Python 2.7.5 or later. Python 3 is not supported. + \li Bison, Flex + \li GPerf + \li Node.js version 8 or later (version 12 or later is recommended) + \endlist + + \section2 Windows + + On Windows, the following additional tools are required: + + \list + \li Visual Studio 2017 version 15.8 or later, or clang-cl version 8 or later + \li Active Template Library (ATL), usually included in the Visual Studio + installation + \li Windows 10 SDK version 10.0.19041 or later + \endlist + + \QWE can only be built on 64-bit Windows, with a x64-bit toolchain. + For building \QWE for x86 applications, you need to configure + and compile Qt with the Visual Studio 2017 x64 to x86 cross-compile + toolchain. This toolchain can be set up on the command line by running + \c{vcvarsall.bat amd64_x86}. + + \section2 Linux + + On Linux, Clang or GCC version 5 or later is required. + Supported configurations are \c linux-g++, \c{linux-clang} and \c{linux-clang-libc++} + + \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 + + Further, development packages for \c khr and \c libcap need to be installed. + + \section2 \macos + + On \macos, the following are required: + + \list + \li \macos 10.13 or later + \li Xcode 10.0 or later + \li \macos 10.13 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 5.15 can be built with + Qt 5.12.x, Qt 5.14.x, and Qt 5.15. + + 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 + + Due to some limitations, the Linux QPA plugin almost always reports that accessibility should + be activated. On big HTML pages, this can cause a significant slowdown in rendering speed. + + Because of that, from Qt 5.9 onwards, \QWE accessibility support is disabled by default + on Linux. + It can be re-enabled by setting the \c QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY environment + variable to a non-empty value. + + \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 for the issue can be found at \l {Fullscreen OpenGL Based Windows} and + \l {QWindowsWindowFunctions::setHasBorderInFullScreen}. + +*/ diff --git a/src/core/doc/src/qwebengine-licensing.qdoc b/src/core/doc/src/qwebengine-licensing.qdoc new file mode 100644 index 000000000..f6a0a6c32 --- /dev/null +++ b/src/core/doc/src/qwebengine-licensing.qdoc @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2017 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$ +** +****************************************************************************/ + +/*! +\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. + +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/webenginequick/doc/src/external-resources.qdoc b/src/webenginequick/doc/src/external-resources.qdoc deleted file mode 100644 index 24648b848..000000000 --- a/src/webenginequick/doc/src/external-resources.qdoc +++ /dev/null @@ -1,146 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 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$ -** -****************************************************************************/ - -/*! - \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 -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-debugging.qdoc b/src/webenginequick/doc/src/qtwebengine-debugging.qdoc deleted file mode 100644 index f84cca312..000000000 --- a/src/webenginequick/doc/src/qtwebengine-debugging.qdoc +++ /dev/null @@ -1,117 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 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$ -** -****************************************************************************/ - -/*! - \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 arguments: - - \badcode - --remote-debugging-port= - \endcode - - Where \c refers to a local network port. The web developer - tools can then be accessed by launching a browser at the address - \c http://localhost:. - - 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. - - 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 {qputenv} from within the - application if called before QtWebEngineQuick::initialize(). -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-deploying.qdoc b/src/webenginequick/doc/src/qtwebengine-deploying.qdoc deleted file mode 100644 index 7b9f3fd4a..000000000 --- a/src/webenginequick/doc/src/qtwebengine-deploying.qdoc +++ /dev/null @@ -1,158 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \page qtwebengine-deploying.html - \title Deploying Qt WebEngine Applications - - 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. - \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 - \endlist - - \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 - - \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 - -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-features.qdoc b/src/webenginequick/doc/src/qtwebengine-features.qdoc deleted file mode 100644 index 24bc9d7aa..000000000 --- a/src/webenginequick/doc/src/qtwebengine-features.qdoc +++ /dev/null @@ -1,683 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtwebengine-features.html - \title Qt WebEngine Features - - \brief Summarizes \QWE features. - - \QWE supports the following features: - - \list - \li \l{Audio and Video Codecs} - \li \l{Chromium DevTools} - \li \l{Client Certificates} - \li \l{Custom Schemes} - \li \l{Drag and Drop} - \li \l{Fullscreen} - \li \l{HTML5 DRM} - \li \l{HTML5 Geolocation} - \li \l{HTTP/2 Protocol} - \li \l{Native Dialogs} - \li \l{Pepper Plugin API} - \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{webrtc_feature}{WebRTC} - \li \l{Web Notifications} - \li \l{Favicon Handling} - \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: - - \code - -webengine-proprietary-codecs - \endcode - - For example, the following option could be passed when configuring Qt for - building it at the top level: - - \code - configure -webengine-proprietary-codecs - \endcode - - For more information, see \l{Qt Configure Options}. - - When using qmake to build just the \QWE module, the following - command can be used (in this example, the \QWE source code is - located in \c {C:\qt\qtwebengine}): - - \code - qmake C:\qt\qtwebengine -- -webengine-proprietary-codecs - \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 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]}. - - 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. - - \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 compoments 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 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 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: - \code - set QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="C:/some path/widevinecdm.dll" - \endcode - - On Linux: - \code - export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.so" - \endcode - - On macOS: - \code - 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 Location} as a - backend. The application has to explicitly allow the feature by using - QWebEnginePage::Geolocation or \l{WebEngineView::Feature} - {WebEngineView.Feature}. - - If Qt Location has been built before \QWE then this feature can be - tested by using \l{WebEngine Widgets Maps Example}{Maps} and allowing it to - find the current position of the user. Note that on Windows an external GPS - receiver must be connected to the application. For more information, see - \l{Qt Positioning}. - - Support for this feature was added in Qt 5.5.0. - - \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 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, - see \l{WebEngine Qt Quick Custom Dialogs Example}. - - \section1 Pepper Plugin API - - \QWE supports loading Pepper Plugin API (PPAPI) plugins if - WebEngineSettings::pluginsEnabled or QWebEngineSettings::PluginsEnabled - is set. - - Except for the Adobe Flash Player plugin, the plugins must be loaded - manually using the Chromium command line syntax with the - \c --register-pepper-plugins argument. The argument value is a list of - entries, separated by commas, that contain the file path and one or several - MIME types, separated by semicolons: - - \code - ;,;; - \endcode - - For example: - - \code - --register-pepper-plugins="libppapi_example.so;application/x-ppapi-example" - \endcode - - The MIME type is important because it determines which embeds the plugin is - used for. - - Support for this feature was added in Qt 5.6.0. - - \section2 Pepper Flash Player Plugin Support - - The Pepper Flash player plugin can be loaded automatically if it is - installed in one of the following locations, depending on the platform: - - \list - \li Windows - \code - C:\Windows\SysWOW64\Macromed\Flash\pepflashplayer*.dll - C:\Windows\System32\Macromed\Flash\pepflashplayer*.dll - \endcode - \li OS X - \code - /Library/Internet Plug-Ins/PepperFlashPlayer/PepperFlashPlayer.plugin - \endcode - \li Linux - \code - /usr/lib/pepperflashplugin-nonfree/libpepflashplayer.so - /usr/lib/adobe-flashplugin/libpepflashplayer.so - /usr/lib/PepperFlash/libpepflashplayer.so - /usr/lib64/chromium/PepperFlash/libpepflashplayer.so - \endcode - \endlist - - You can also load the Pepper Flash player from a specific location by using - command line arguments: - - \code - --ppapi-flash-path=./libpepflashplayer.so - \endcode - - By default, the Flash version is set to \c{11.2.999.999}. You can use the - \c{ppapi-flash-version=} argument to set another Flash version in the - format \c{major.minor.build.revision}: - - \code - --ppapi-flash-version=16.0.0.235 - \endcode - - This feature can be tested in \l{WebEngine Widgets Simple Browser Example}{Simple Browser} - or \l{WebEngine Quick Nano Browser}{Nano Browser} if the Adobe Flash PPAPI - plugin is installed and plugins are enabled in the browser. To test the - feature, the \c https://helpx.adobe.com/flash-player.html page can be opened - in the browser. - - \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}. - - 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: - \code - view-source:https://www.qt.io/ - \endcode - - Auto-completion of incomplete URLs with \l{view-source URI scheme} makes the usage of - this feature more comfortable. For example, the following incomplete URL also loads - the source view of the qt.io web page: - \code - view-source:qt.io - \endcode - - Support for this feature was added in Qt 5.8.0. - - \target webrtc_feature - \section1 WebRTC - - WebRTC provides browsers with Real-Time Communications (RTC) capabilities - via simple APIs. For more information, see \l{WebEngineView::Feature} - {WebEngineView.Feature} and QWebEnginePage::Feature. - - This feature can be tested by setting up a webcam or microphone and then - opening \c https://test.webrtc.org/ in \l{WebEngine Widgets Simple Browser - Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}. - - \section1 Web Notifications - - Qt WebEngine supports JavaScript \l{Web Notifications API}. - 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 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". - For example, - \qml - Image { - source: "image://favicon/url" - } - \endqml - - The \c url can be the URL of the favicon. For example, - \qml - Image { - source: "image://favicon/https://www.qt.io/hubfs/2016_Qt_Logo/qt_logo_green_rgb_16x16.png" - } - \endqml - - The \c url also can be a page URL to access its icon. For example, - \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. - - \note The icon database is not available for off-the-record profiles. -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-index.qdoc b/src/webenginequick/doc/src/qtwebengine-index.qdoc deleted file mode 100644 index 725b80637..000000000 --- a/src/webenginequick/doc/src/qtwebengine-index.qdoc +++ /dev/null @@ -1,71 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \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 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/webenginequick/doc/src/qtwebengine-modules.qdoc b/src/webenginequick/doc/src/qtwebengine-modules.qdoc deleted file mode 100644 index 759284ad9..000000000 --- a/src/webenginequick/doc/src/qtwebengine-modules.qdoc +++ /dev/null @@ -1,48 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \page qtwebengine-modules.html - \title Qt WebEngine C++ Classes and Namespaces - \brief Provides functionality for rendering regions of dynamic web content. - - \e {Qt WebEngine} provides functionality for rendering regions of dynamic web content. - - \section1 Namespaces - \annotatedlist qtwebengine-namespaces - - \section1 Classes - - \section2 Qt WebEngineCore Module - \generatelist {classesbymodule QtWebEngineCore} - - \section2 Qt WebEngineWidgets Module - \generatelist {classesbymodule QtWebEngineWidgets} - - \section2 Qt WebEngineQuick Module - \generatelist {classesbymodule QtWebEngineQuick} -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-overview.qdoc b/src/webenginequick/doc/src/qtwebengine-overview.qdoc deleted file mode 100644 index 099142f80..000000000 --- a/src/webenginequick/doc/src/qtwebengine-overview.qdoc +++ /dev/null @@ -1,315 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 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$ -** -****************************************************************************/ - -/*! - \page qtwebengine-overview.html - \title Qt WebEngine Overview - - 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. - - \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. - - This version of \QWE is based on Chromium version 87.0.4280, with additional security - fixes from newer versions. - - \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) - { - QApplication app(argc, argv); - - QtWebEngineQuick::initialize(); - - 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 webengine/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 } - \li \c {@include } - \li \c {@match } - \li \c {@name } - \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::error} 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/webenginequick/doc/src/qtwebengine-platform-notes.qdoc b/src/webenginequick/doc/src/qtwebengine-platform-notes.qdoc deleted file mode 100644 index 08eaf72bb..000000000 --- a/src/webenginequick/doc/src/qtwebengine-platform-notes.qdoc +++ /dev/null @@ -1,238 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 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$ -** -****************************************************************************/ - -/*! - \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 5 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 - - The tests for skipping the \QWE build are located in the - \c qtwebengine repository, in the \c tools\qmake\mkspecs subdirectory. - They can be found by searching for \c skipBuild. - - \section2 All Platforms - - On all platforms, the following tools are required at build time: - - \list - \li \l Python 2.7.5 or later. Python 3 is not supported. - \li Bison, Flex - \li GPerf - \li Node.js version 8 or later (version 12 or later is recommended) - \endlist - - \section2 Windows - - On Windows, the following additional tools are required: - - \list - \li Visual Studio 2017 version 15.8 or later, or clang-cl version 8 or later - \li Active Template Library (ATL), usually included in the Visual Studio - installation - \li Windows 10 SDK version 10.0.19041 or later - \endlist - - \QWE can only be built on 64-bit Windows, with a x64-bit toolchain. - For building \QWE for x86 applications, you need to configure - and compile Qt with the Visual Studio 2017 x64 to x86 cross-compile - toolchain. This toolchain can be set up on the command line by running - \c{vcvarsall.bat amd64_x86}. - - \section2 Linux - - On Linux, Clang or GCC version 5 or later is required. - Supported configurations are \c linux-g++, \c{linux-clang} and \c{linux-clang-libc++} - - \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 - - Further, development packages for \c khr and \c libcap need to be installed. - - \section2 \macos - - On \macos, the following are required: - - \list - \li \macos 10.13 or later - \li Xcode 10.0 or later - \li \macos 10.13 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 5.15 can be built with - Qt 5.12.x, Qt 5.14.x, and Qt 5.15. - - 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 - - Due to some limitations, the Linux QPA plugin almost always reports that accessibility should - be activated. On big HTML pages, this can cause a significant slowdown in rendering speed. - - Because of that, from Qt 5.9 onwards, \QWE accessibility support is disabled by default - on Linux. - It can be re-enabled by setting the \c QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY environment - variable to a non-empty value. - - \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 for the issue can be found at \l {Fullscreen OpenGL Based Windows} and - \l {QWindowsWindowFunctions::setHasBorderInFullScreen}. - -*/ diff --git a/src/webenginequick/doc/src/qwebengine-licensing.qdoc b/src/webenginequick/doc/src/qwebengine-licensing.qdoc deleted file mode 100644 index f6a0a6c32..000000000 --- a/src/webenginequick/doc/src/qwebengine-licensing.qdoc +++ /dev/null @@ -1,53 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 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$ -** -****************************************************************************/ - -/*! -\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. - -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 -*/ -- cgit v1.2.3