diff options
Diffstat (limited to 'src/core/doc')
23 files changed, 3501 insertions, 138 deletions
diff --git a/src/core/doc/QtWebEngineDoc b/src/core/doc/QtWebEngineDoc new file mode 100644 index 000000000..7ab3164fd --- /dev/null +++ b/src/core/doc/QtWebEngineDoc @@ -0,0 +1,3 @@ +#include <QtWebEngineCore/QtWebEngineCore> +#include <QtWebEngineQuick/QtWebEngineQuick> +#include <QtWebEngineWidgets/QtWebEngineWidgets> diff --git a/src/core/doc/about_credits.tmpl b/src/core/doc/about_credits.tmpl new file mode 100644 index 000000000..57fae9e78 --- /dev/null +++ b/src/core/doc/about_credits.tmpl @@ -0,0 +1 @@ +{{entries}} diff --git a/src/core/doc/about_credits_entry.tmpl b/src/core/doc/about_credits_entry.tmpl new file mode 100644 index 000000000..aa94f2945 --- /dev/null +++ b/src/core/doc/about_credits_entry.tmpl @@ -0,0 +1,13 @@ +/*! +\page qtwebengine-3rdparty-{{name-sanitized}}.html +\attribution +\ingroup qtwebengine-licensing +\brief {{license-type}} +\title {{name}} + +\l{{{url}}}{Project Homepage} + +\badcode +{{license}} +\endcode +*/ diff --git a/src/core/doc/qtwebengine.qdocconf b/src/core/doc/qtwebengine.qdocconf new file mode 100644 index 000000000..6b78f13f8 --- /dev/null +++ b/src/core/doc/qtwebengine.qdocconf @@ -0,0 +1,96 @@ +include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) +include($QT_INSTALL_DOCS/config/exampleurl-qtwebengine.qdocconf) + +project = QtWebEngine +description = Qt WebEngine Reference Documentation +version = $QT_VERSION + +qhp.projects = QtWebEngine + +qhp.QtWebEngine.file = qtwebengine.qhp +qhp.QtWebEngine.namespace = org.qt-project.qtwebengine.$QT_VERSION_TAG +qhp.QtWebEngine.virtualFolder = qtwebengine +qhp.QtWebEngine.indexTitle = Qt WebEngine +qhp.QtWebEngine.indexRoot = + +qhp.QtWebEngine.subprojects = classes qmltypes examples + +qhp.QtWebEngine.subprojects.classes.title = C++ Classes and Namespaces +qhp.QtWebEngine.subprojects.classes.indexTitle = Qt WebEngine C++ Classes and Namespaces +qhp.QtWebEngine.subprojects.classes.selectors = class group:qtwebengine-namespaces doc:headerfile +qhp.QtWebEngine.subprojects.classes.sortPages = true + +qhp.QtWebEngine.subprojects.qmltypes.title = QML Types +qhp.QtWebEngine.subprojects.qmltypes.indexTitle = Qt WebEngine QML Types +qhp.QtWebEngine.subprojects.qmltypes.selectors = qmltype +qhp.QtWebEngine.subprojects.qmltypes.sortPages = true + +qhp.QtWebEngine.subprojects.examples.title = Examples +qhp.QtWebEngine.subprojects.examples.indexTitle = Qt WebEngine Examples +qhp.QtWebEngine.subprojects.examples.selectors = doc:example +qhp.QtWebEngine.subprojects.examples.sortPages = true + +manifestmeta.highlighted.names += "QtWebEngine/WebEngine Widgets Simple Browser Example" \ + "QtWebEngine/WebEngine Quick Nano Browser" \ + "QtWebEngine/Recipe Browser" + +tagfile = ../../../doc/qtwebengine/qtwebengine.tags + +# Custom module header for clang that pulls in also QtWebEngineWidgets +moduleheader = QtWebEngineDoc + +# Additional include paths for clang +includepaths += -I . + +depends += qtcore \ + qtcore5compat \ + qtdesigner \ + qtgui \ + qtnetwork \ + qtprintsupport \ + qtpositioning \ + qtqml \ + qtqmlmodels \ + qtquick \ + qtquickcontrols \ + qtdoc \ + qtcmake \ + qtwebchannel \ + qtwebview \ + qtwidgets + +headerdirs += ../../core/api \ + ../../webenginequick/api \ + ../../webenginewidgets/api + +sourcedirs += ../../core/api \ + ../../core/doc \ + ../../webenginequick/api \ + ../../webenginequick/doc \ + ../../webenginewidgets/api \ + ../../webenginewidgets/doc + +exampledirs += ../../../examples \ + ../../core/doc/snippets \ + ../../webenginequick/doc/snippets \ + ../../webenginewidgets/doc/snippets + +#exclude Qt PDF example directories +excludedirs += ../../../examples/pdfwidgets \ + ../../../examples/pdf + +examples.fileextensions += *.aff *.dic *.html + +imagedirs += \ + images \ + ../../webenginequick/doc/images + +navigation.landingpage = "Qt WebEngine" +navigation.cppclassespage = "Qt WebEngine C++ Classes and Namespaces" +navigation.qmltypespage = "Qt WebEngine QML Types" + +# \QWE macro expands to 'Qt WebEngine' without auto-linking anywhere. +macro.QWE = "Qt \\WebEngine" + +# Enforce zero documentation warnings +warninglimit = 0 diff --git a/src/core/doc/snippets/qtwebengine_qwebenginepage_snippet.cpp b/src/core/doc/snippets/qtwebengine_qwebenginepage_snippet.cpp new file mode 100644 index 000000000..6b39eed03 --- /dev/null +++ b/src/core/doc/snippets/qtwebengine_qwebenginepage_snippet.cpp @@ -0,0 +1,14 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +void wrapInFunction() +{ + +//! [0] + m_view->page()->findText(QStringLiteral("Qt"), QWebEnginePage::FindFlags(), [this](const QWebEngineFindTextResult &result) { + if (result.numberOfMatches() == 0) QMessageBox::information(m_view, QString(), QStringLiteral("No occurrences found")); + }); +//! [0] + +} + diff --git a/src/core/doc/snippets/qtwebenginecore_build_snippet.qdoc b/src/core/doc/snippets/qtwebenginecore_build_snippet.qdoc index 94e26c9c5..9a7370d62 100644 --- a/src/core/doc/snippets/qtwebenginecore_build_snippet.qdoc +++ b/src/core/doc/snippets/qtwebenginecore_build_snippet.qdoc @@ -1,35 +1,11 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only //! [0] QT += webenginecore //! [0] - -//! [1] -#include <QtWebEngineCore> -//! [1] +//! [2] +find_package(Qt6 REQUIRED COMPONENTS WebEngineCore) +target_link_libraries(target PRIVATE Qt6::WebEngineCore) +//! [2] diff --git a/src/core/doc/src/external-resources.qdoc b/src/core/doc/src/external-resources.qdoc new file mode 100644 index 000000000..775492c7e --- /dev/null +++ b/src/core/doc/src/external-resources.qdoc @@ -0,0 +1,138 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \externalpage http://www.chromium.org + \title Chromium Project +*/ + +/*! + \externalpage https://developers.google.com/web/tools/chrome-devtools + \title Chrome DevTools +*/ + +/*! + \externalpage https://developer.chrome.com/docs/devtools/console/ + \title Chrome console API +*/ + +/*! + \externalpage http://ffmpeg.org/ + \title FFmpeg +*/ + +/*! + \externalpage http://www.openh264.org/ + \title OpenH264 Project Homepage +*/ + +/*! + \externalpage http://html5demos.com/drag + \title HTML5 Demos - Drag and Drop +*/ + +/*! + \externalpage http://html5demos.com/drag-anything + \title HTML5 Demos - Simple Drag and Drop +*/ + +/*! + \externalpage http://html5demos.com/dnd-upload + \title HTML5 Demos - Drag and Drop, Automatic Upload +*/ + +/*! + \externalpage http://html5demos.com/file-api + \title HTML5 Demos - File API +*/ + +/*! + \externalpage http://www.widevine.com + \title Widevine CDM +*/ + +/*! + \externalpage http://demo.castlabs.com/ + \title castLabs +*/ + +/*! + \externalpage http://ssdemo04.swankmp.net/ + \title Swank Motion Pictures, Inc. +*/ + +/*! + \externalpage https://bitmovin.com/demos/drm + \title Bitmovin Player +*/ + +/*! + \externalpage https://sourceforge.net/projects/hunspell/ + \title Hunspell Project +*/ + +/*! + \externalpage https://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1 + \title RFC 2616 section 19.5.1 +*/ + +/*! + \externalpage https://www.iana.org/assignments/uri-schemes/prov/view-source + \title view-source URI scheme +*/ + +/*! + \externalpage https://wiki.greasespot.net/Metadata_Block + \title Greasemonkey +*/ + +/*! + \externalpage https://http2.github.io/ + \title HTTP/2 +*/ + +/*! + \externalpage https://http2.akamai.com/demo + \title Akamai HTTP/2 Demo +*/ + +/*! + \externalpage https://www.chromium.org/developers/design-documents/user-scripts + \title User Scripts +*/ + +/*! + \externalpage https://wiki.greasespot.net/Metadata_Block#.40name + \title Metadata Block +*/ + +/*! + \externalpage https://developer.mozilla.org/en-US/docs/Web/API/Navigator/registerProtocolHandler + \title registerProtocolHandler +*/ + +/*! + \externalpage https://www.w3.org/TR/notifications + \title Web Notifications API +*/ + +/*! + \externalpage https://developers.google.com/web/updates/2017/09/autoplay-policy-changes + \title Autoplay Policy Changes +*/ + +// Workarounds for broken links introduced by README.chromium license files +/*! + \externalpage # + \title This is the canonical public repository +*/ + +/*! + \externalpage # + \title NA +*/ + +/*! + \externalpage https://source.chromium.org/chromium/chromium/src/+/master:v8/src/base/ieee754.cc + \title source.chromium.org/chromium/chromium/src/+/master:v8/src/base/ieee754.cc +*/ diff --git a/src/core/doc/src/qt6-changes.qdoc b/src/core/doc/src/qt6-changes.qdoc new file mode 100644 index 000000000..5061c77ab --- /dev/null +++ b/src/core/doc/src/qt6-changes.qdoc @@ -0,0 +1,131 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-changes-qt6.html + \title Changes to Qt WebEngine + \ingroup changes-qt-5-to-6 + \brief Migrate Qt WebEngine to Qt 6. + + Qt 6 is a result of the conscious effort to make the framework more + efficient and easy to use. + + We try to maintain binary and source compatibility for all the public + APIs in each release. But some changes were inevitable in an effort to + make Qt a better framework + + In this topic we summarize those changes in Qt WebEngine, and provide guidance + to handle them. + + \section1 Moved Classes + + \section2 The Qt WebEngine module + Has been renamed to the Qt WebEngineQuick module to not collide with the name of + the super module, and to be consistent with other Quick modules. + + If you port your Qt Quick application, please remember to use the new module + name in your qmake project file. + + \code + QT += webenginequick + \endcode + + \section2 Classes moved from Qt WebEngineWidgets to Qt WebEngineCore + Several classes have been moved from Qt WebEngineWidgets to Qt WebEngineCore if they + did not use the Widgets module. In most cases this change should be source compatible unless + you included the module name in the include header, in which case you need to update your + includes. + + \section3 Classes moved with minimal changes + \list + \li QWebEngineHistory + \li QWebEngineProfile + \li QWebEngineScript + \li QWebEngineScriptCollection + \li QWebEngineClientCertificateSelection + \li QWebEngineSettings + \li QWebEngineFullScreenRequest + \endlist + + \section3 QWebEngineCertificateError + Has been unified between QML and C++ versions, so both are now accepted or rejected via methods + on the class. + + \section3 QWebEngineContextMenuData + Has been moved to Core and renamed QWebEngineContextMenuRequest. + + \section3 QWebEngineDownloadItem + Has been moved to Core and renamed QWebEngineDownloadRequest. + + \section3 QWebEnginePage + Has been moved to Core, and API that worked on QWebEngineView or QPrinter has been moved, and can now + be accessed only from QWebEngineView. See Changed API. + + \section2 Classes moved from Qt WebEngineQuick to Qt WebEngineCore + + \section3 WebEngineNavigationRequest + Is now QWebEngineNavigationRequest, and accessible from C++ API as well, adding a more + informative variant of QWebEnginePage::acceptNavigationRequest(). + + \section3 WebEngineNewViewRequest + Is now WebEngineNewWindowRequest and QWebEngineNewWindowRequest, and accessible from C++ API as well, + adding a more informative variant of QWebEnginePage::createWindow(). + + + \section1 Changed API + + \section2 C++ + + \section3 QWebEnginePage::certificateError() + Is now a signal instead of a derived method. The errors are either accepted or rejected + via methods on the QWebEngineCertificateError class. + + \section3 QWebEnginePage::print() + Has been moved to QWebEngineView::print() and no longer takes a callback argument but + signals finished with QWebEngineView::printFinished() instead. It was never possible + to have two active print jobs at the same time. + + \section3 QWebEnginePage::view() + Has been removed as QWebEnginePage and QWebEngineView are now in different modules. The view + associated with a page can be accessed using the static helper QWebEngineView::forPage(). + + \section3 QWebEngineProfile::defaultProfile() + Has been removed. The default profile is now an off-the-record profile, and only used if a + QWebEnginePage is created without an explicit profile. To maintain Qt 5 like behavior, create + a global profile called "Default" and use it when creating every QWebEnginePage. + + \section2 QML + + \section3 WebEngineNavigationRequest + The navigation requests are now accepted or rejected like other request objects using accept() + or reject() methods. + + \section3 WebEngineNewViewRequest + Has been renamed WebEngineNewWindowRequest. + + \section1 Changed Behavior + + \section2 Default Profile + The default profile is now \e{off the record}. To have a standard browser profile with + disk-cache and cookies, we recommend creating your own profile and using that explicitly. + + \section2 QRC Scheme + Can no longer be accessed from custom schemes by default, nor can it access local content + directly. If the Qt 5 behavior is needed, it can be restored by registering the qrc scheme + like a custom URL scheme, and setting the CorsEnabled and LocalAccessAllowed access flags. + \code + QWebEngineUrlScheme qrcScheme(QByteArrayLiteral("qrc")); + qrcScheme.setFlags(QWebEngineUrlScheme::SecureScheme + | QWebEngineUrlScheme::LocalAccessAllowed + | QWebEngineUrlScheme::CorsEnabled + | QWebEngineUrlScheme::ViewSourceAllowed); + QWebEngineUrlScheme::registerScheme(qrcScheme); + \endcode + + \section2 OCSP Certificate Revocation Checking + In Qt 5 OCSP could be enabled on Linux using QWebEngineProfile::setUseForGlobalCertificateVerification(true) + on a QWebEngineProfile. This has been removed in Qt6 as this specific form of OCSP is considered bad. As + of Qt 6.2, no new method for revoked certificate checking on Linux has yet been added. + + +*/ diff --git a/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc b/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc new file mode 100644 index 000000000..6af681cc5 --- /dev/null +++ b/src/core/doc/src/qt_webengine_add_convert_dictionary.qdoc @@ -0,0 +1,54 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-webengine-dictionary.html +\ingroup cmake-commands-qtwebenginecore + +\title qt_add_webengine_dictionary +\keyword qt6_add_webengine_dictionary + +\brief Converts the hunspell dictionary format into \e bdict binary format. + +\cmakecommandsince 6.3 + +\section1 Synopsis + +\badcode +qt_add_webengine_dictionary( + [TARGET] + [SOURCE] + [OUTPUT_DIRECTORY] +) + +\endcode + +\versionlessCMakeCommandsNote qt6_webengine_add_dictionary() + +\section1 Description + + A spell checker in Qt Web Engine needs dictionaries in a specific binary format. + This CMake command converts dictionaries from the \l{Hunspell project}. into the \c bdict + binary format. It creates a \c qtwebengine_dictionaries target, which your project can + use as a dependency. This way your project can easily add dictionaries for the spell + checker. Refer to the \l{WebEngine Widgets Spellchecker Example}{spell checker example} + for more details. + +\section1 Arguments + + \c TARGET is an optinal argument and specifies the name of the application target that should + depend on \c qtwebengine_dictionaries target. In other words it is used to define a build + dependency to create the binary format of dictionaries before building \c TARGET. + + \c SOURCE is the absolute path to the \l{Hunspell project} dictionary for which + a corresponding binary format (\c.bdict) will be created. + + \c OUTPUT_DIRECTORY is an optional argument and specifies the directory where the binary format + of the dictionary will be created. If not specified, \c CMAKE_CURRENT_BINARY_DIR will be used + as \c OUTPUT_DIRECTORY. + + \note The \c qtwebengine_dictionaries directory or \c <CONFIG>/qtwebengine_dictionaries + directories in the case of the multi-config generator is appended to OUTPUT_DIRECTORY. This + helps to utilize dictionaries, as the \c webengine_dictionaries directory is the default + search location. +*/ diff --git a/src/core/doc/src/qtwebengine-debugging.qdoc b/src/core/doc/src/qtwebengine-debugging.qdoc new file mode 100644 index 000000000..3dd4d9276 --- /dev/null +++ b/src/core/doc/src/qtwebengine-debugging.qdoc @@ -0,0 +1,112 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-debugging.html + \title Qt WebEngine Debugging and Profiling + + \section1 Console Logging + + JavaScript executed inside \QWE can use the + \l{Chrome console API} to log information to a console. The logging messages + are forwarded to Qt's logging facilities inside a \c js + \l{QLoggingCategory}{logging category}. However, only warning and fatal + messages are printed by default. To change this, you either have to set custom + rules for the \c js category, or provide custom message handlers + by reimplementing \l{QWebEnginePage::javaScriptConsoleMessage()}, or + connecting to \l{WebEngineView::javaScriptConsoleMessage()}. + + All messages can also be accessed through the \QWE developer + tools. + + \section1 Qt WebEngine Developer Tools + + The \QWE module provides web developer tools that make it easy + to inspect and debug layout and performance issues of any web content. + + The developer tools are accessed as a local web page using a Chromium or + \QWE based browser, such as the Chrome browser. + + To activate the developer tools, start an application that uses \QWE + with the command-line argument \c {--remote-debugging-port=<portnumber>}. + + \note Any WebEngine command line options should be specified after the + \c {--webEngineArgs} option, which is used to separate the user's application + specific options from the WebEngine's ones. + + \badcode + --webEngineArgs --remote-debugging-port=<portnumber> + \endcode + + Where \c <port_number> refers to a local network port. The web developer + tools can then be accessed by launching a browser at the address + \c http://localhost:<port_number>. + + Alternatively, the environment variable QTWEBENGINE_REMOTE_DEBUGGING + can be set. It can be set as either just a port working similarly to + \c --remote-debugging-port or given both a host address and a port. The + latter can be used to control which network interface to export the + interface on, so that you can access the developer tools from a remote + device. + + To avoid WebSocket errors during remote debugging, add an additional command-line + argument \c {--remote-allow-origins=<origin>[,<origin>, ...]}, where \c <origin> refers to the request origin. + Use \c {--remote-allow-origins=*} to allow connections from all origins. If nothing is specified, + \QWE will add \c {--remote-allow-origins=*} to command-line arguments when remote-debugging is enabled, + thereby allowing requests from all origins. + + For a detailed explanation of the capabilities of developer tools, see the + \l {Chrome DevTools} page. + + \section1 Using Command-Line Arguments + + You can use the following command-line arguments while debugging to provide + input for bug reports: + + \list + \li \c {--disable-gpu} disables GPU hardware acceleration. This is + useful when diagnosing OpenGL problems. + \li \c {--disable-logging} disables console logging, which might be + useful for debug builds. + \li \c {--enable-logging --log-level=0} enables console logging and sets + the logging level to 0, which means that messages of the severity + \c info and above are recorded in the log. This is the default for + debug builds. Other possible log levels are \c 1 for warnings, \c 2 + for errors, and \c 3 for fatal errors. + \li \c {--v=1} Increases the logging level beyond what \c {--log-level} + can, and enables logging debug messages up to verbosity level \c 1. + A higher number further increases verbosity, but may result in a + large number of logged messages. Default is \c 0 (no debug messages). + \li \c {--no-sandbox} disables the sandbox for the renderer and plugin + processes. Keep in mind that disabling the sandbox might present a + security risk. + \li \c {--single-process} runs the renderer and plugins in the same + process as the browser. This is useful for getting stack traces for + renderer crashes. + \li \c {--enable-features=NetworkServiceInProcess} runs networking in + the main process. This may help firewall management, since only the + application executable will need to be whitelisted and + not QtWebEngineProcess. It means losing the security of + sandboxing of the network service though. + \endlist + + Alternatively, the environment variable QTWEBENGINE_CHROMIUM_FLAGS can be + set. For example, the following value could be set to disable logging while + debugging an application called \e mybrowser: + + \code + QTWEBENGINE_CHROMIUM_FLAGS="--disable-logging" mybrowser + \endcode + + QTWEBENGINE_CHROMIUM_FLAGS can also be set using \c qputenv from within the + application if called before QtWebEngineQuick::initialize(). + + \section1 Dump WebEngineContext Information + + For dumping the WebEngineContext information, you can set the \c QT_LOGGING_RULES + environment variable to \c "qt.webenginecontext.debug=true". + + The output contains information about the graphical backend, and the way how \QWE + is initialized for the application. This is particularly useful for reproducing + issues. +*/ diff --git a/src/core/doc/src/qtwebengine-deploying.qdoc b/src/core/doc/src/qtwebengine-deploying.qdoc new file mode 100644 index 000000000..3d8a976c8 --- /dev/null +++ b/src/core/doc/src/qtwebengine-deploying.qdoc @@ -0,0 +1,199 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-deploying.html + \title Deploying Qt WebEngine Applications + \ingroup explanations-webtechnologies + + The way to package and deploy applications varies between operating systems. + For Windows and \macos, \l{The Windows Deployment Tool}{windeployqt} and + \l{Deploying Applications on macOS}{macdeployqt} automate the steps to + generate a stand-alone application package. + + When manually deploying applications that depend on \QWE, all the + files that are required to run the application have to be included: + libraries, QML imports, plugins, and translations. + + For more information, see \l {Deploying Qt Applications}. + + \section1 Target Platforms + + \QWE does try to support all \l{Supported Platforms} of Qt. However, + due to different requirements of Chromium this is not always possible. Known + limitations are: + + \list + \li \QWE currently supports only Windows, Linux, and \macos. + + \li On Windows, \QWE only supports Windows Vista or newer as + target platform. Due to use of newer API in Chromium, Windows XP is + not supported. WinRT is not supported, either. + \endlist + + \section1 Deploying Applications Manually + + When manually deploying applications that depend on \QWE, the + following files might have to be deployed: + + \list + \li Libraries + \li QML imports + \li \QWE process + \li Resources + \li Translations + \li Audio and video codecs + \endlist + + \section2 Deploying Libraries + + The following libraries must be deployed with applications that depend on + \QWE: + + \list + \li QtWebEngineCore library + \li QtWebEngineWidgets or QtWebEngine libraries, depending on + application type + \endlist + + \section2 Deploying QML Imports + + If Qt Quick integration is used in the application, the QtWebEngine import + directory needs to be deployed. + + \section2 Deploying \QWE Processes + + \QWE takes advantage of the multi-process model that the Chromium + project offers. The multi-process model requires that the \QWE + Process executable be deployed alongside your application. + + The WebEngine process is executed for each QWebEngineView or WebEngineView + instance. For example, a browser application + with two tabs open should have two separate instances of the process + running. This is a common approach used by most modern web engines to + provide a stable browsing experience. + + At runtime, \QWE looks for the \c QtWebEngineProcess executable in + the directory that + QLibraryInfo::location(QLibraryInfo::LibraryExecutablesPath) returns. + For Qt installations, this is \c QTDIR/libexec (Linux) or \c QTDIR\bin + (Windows). The path can be changed by defining a \c qt.conf file, for + example. Alternatively, an executable path can be set as a value of the + \c QTWEBENGINEPROCESS_PATH environment variable. On \macos, \QWE + looks for the executable in \c .app/Helpers/QtWebEngineProcess. + + \section2 Deploying Resources + + \QWE requires the following resource files: + + \list + \li \c qtwebengine_resources.pak contains the resources needed by + Chromium. + \li \c qtwebengine_devtools_resources.pak contains tools for remote + debugging. + \li \c qtwebengine_resources_100p.pak contains images suitable for low + resolution displays. + \li \c qtwebengine_resources_200p.pak contains images suitable for high + DPI displays. + \li \c icudtl.dat provides support for International Components for + Unicode (ICU). It is the Chromium version of ICU, which is not + needed if \QWE was configured to use the system ICU. + \li \c v8_context_snapshot.bin contains a previously prepared snapshot + of a v8 context used to speed up initialization. Debug builds use + separate snapshots with the file name extension \c .debug.bin instead + of \c .bin. On \macos, there is a snapshot for each architecture named + accordingly, for example \c v8_context_snapshot.arm64.bin or + \c v8_context_snapshot.arm64.debug.bin. + \endlist + + Resources are searched from the following locations: + + \list + \li On Linux and Windows: the \c resources directory in the directory + specified by QLibraryInfo::location(QLibraryInfo::DataPath) + \li On \macos: \c .app/Content/Resources + \li The application directory specified by QCoreApplication::applicationDirPath() + \endlist + + Alternatively, a resources directory path can be set as a value of the + \c QTWEBENGINE_RESOURCES_PATH environment variable. + + \section2 Translations + + Locale data (such as \c en-US.pak) is searched form the following locations: + + \list + \li On \macos: \c .app/Content/Resources + \li On Linux and Windows: \c qtwebengine_locales directory in the + directory specified by + QLibraryInfo::location(QLibraryInfo::TranslationsPath) + \endlist + + Alternatively, a locales directory path can be set as a value of the + \c QTWEBENGINE_LOCALES_PATH environment variable. + + \section2 JavaScript Files in Qt Resource Files + + If your WebEngine application is built using the Qt Quick Compiler, and the application ships + JavaScript files inside .qrc resources, and these files are supposed to be loaded from inside + HTML pages, make sure to specify the resource files in a \c QTQUICK_COMPILER_SKIPPED_RESOURCES + qmake variable inside your project. This prevents the Qt Quick Compiler from trying to generate + C++ code for the corresponding JavaScript code, as well as removing the original JavaScript code + from the Qt resources file, which would lead to broken HTML pages. For example: + + \code + QTQUICK_COMPILER_SKIPPED_RESOURCES += resources/my_resource.qrc + \endcode + + \section2 \macos Specific Deployment Steps + + To deploy a \QWE application on \macos, you will need to ensure that the \QWE process is signed + with an entitlements file that at least contains the entitlements listed in + QtWebEngineCore.framework/Helpers/QtWebEngineProcess.app/Contents/Resources/QtWebEngineProcess.entitlements. + + To deploy a \QWE application that accesses the microphone or camera + on \macos, you will need to provide texts for the messages that will be shown to the user to + explain why the application asks for permission to access to the camera or microphone. + To do this, add the texts to the application's \c Info.plist file using the keys + described below. + + For the camera usage message, provide a text using the following key: + \code + <key>NSCameraUsageDescription</key> + <string>Your message text for camera usage.</string> + \endcode + + See also \l{https://developer.apple.com/documentation/bundleresources/information_property_list/nscamerausagedescription} + {Apple's property list file documentation}. + + For the microphone usage message, provide a text using the following key: + \code + <key>NSMicrophoneUsageDescription</key> + <string>Your message text for microphone usage.</string> + \endcode + + See also \l{https://developer.apple.com/documentation/bundleresources/information_property_list/nsmicrophoneusagedescription} + {Apple's property list file documentation}. + + To notarize an application that accesses the camera or the microphone, + you will need to add the corresponding keys to your application's entitlements file used for + deployment and notarization. + + To enable access to the camera, add: + \code + <key>com.apple.security.device.camera</key> + <true/> + \endcode + + See also \l{https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_device_camera} + {Apple's camera entitlement documentation}. + + To enable access to the microphone, add: + \code + <key>com.apple.security.device.microphone</key> + <true/> + \endcode + + See also \l{https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_device_microphone} + {Apple's microphone entitlement documentation}. +*/ diff --git a/src/core/doc/src/qtwebengine-features.qdoc b/src/core/doc/src/qtwebengine-features.qdoc new file mode 100644 index 000000000..9465d75a2 --- /dev/null +++ b/src/core/doc/src/qtwebengine-features.qdoc @@ -0,0 +1,777 @@ +// Copyright (C) 2019 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-features.html + \title Qt WebEngine Features + \ingroup explanations-webtechnologies + + \brief Summarizes \QWE features. + + \QWE supports the following features: + + \list + \li \l{Audio and Video Codecs} + \li \l{WebEngineDriver} + \li \l{Chromium DevTools} + \li \l{Client Certificates} + \li \l{Custom Schemes} + \li \l{Drag and Drop} + \li \l{Favicon} + \li \l{Fullscreen} + \li \l{Hardware Acceleration} + \li \l{HTML5 DRM} + \li \l{HTML5 Geolocation} + \li \l{HTML5 WebSockets} + \li \l{HTTP/2 Protocol} + \li \l{Local Storage} + \li \l{Native Dialogs} + \li \l{PDF File Viewing} + \li \l{Page Lifecycle API} + \li \l{Print to PDF} + \li \l{Process Models} + \li \l{Spellchecker} + \li \l{Touch} + \li \l{View Source} + \li \l{Web Notifications} + \li \l{WebGL} + \li \l{webrtc_feature}{WebRTC} + \endlist + + \section1 Audio and Video Codecs + + \QWE supports the MPEG-4 Part 14 (MP4) file format only if the + required proprietary audio and video codecs, such as H.264 and MPEG layer-3 + (MP3), have been enabled. Proprietary codecs can be enabled by passing the + following option to the \c configure tool when configuring Qt: + + \badcode + -webengine-proprietary-codecs + \endcode + + For example, the following option could be passed when configuring Qt for + building it at the top level: + + \badcode + configure -webengine-proprietary-codecs + \endcode + + For more information, see \l{Qt Configure Options}. + + When using cmake to build just the \QWE module, the following + command can be used to configure and build (in this example, the \QWE source code is + located in \c {C:\qt\qtwebengine}): + + \badcode + qt-configure-module C:\qt\qtwebengine -webengine-proprietary-codecs + cmake --build . --parallel + \endcode + + \warning When distributing proprietary codec libraries, you must acquire + licenses for them. + + \l FFmpeg is a cross-platform solution to record, convert, and stream audio + and video. It can be configured for use with several codecs, which rises + licensing issues during distribution with the codec libraries. For some + codecs, open source implementations, such as \l{OpenH264 Project Homepage} + {OpenH264}, are available. + + \section1 WebEngineDriver + + With WebEngineDriver, you can automate the testing of web sites across browsers. + WebEngineDriver is based on ChromeDriver and can be used the same way. + For more information about ChromeDriver and its use, visit + \l {https://chromedriver.chromium.org/}{ChromeDriver user site}. + + WebEngineDriver has slight modifications compared to ChromeDriver to be able to connect to + \QWE based browsers. It is compatible with \QWE example browsers, such as + \l {WebEngine Widgets Simple Browser Example}{Simple Browser} or + \l{WebEngine Quick Nano Browser}{Nano Browser}. + + The browser automation is scripted through a WebDriver client like the + \l {https://www.selenium.dev/}{Selenium WebDriver}. + For example, WebEngineDriver can be used with the Python lanugage bindings of + Selenium WebDriver: + + \code + from selenium import webdriver + from selenium.webdriver.chrome.service import Service + + service = Service(executable_path='QTDIR/libexec/webenginedriver') + options = webdriver.ChromeOptions() + options.binary_location = 'path/to/browser_binary' + + driver = webdriver.Chrome(service=service, options=options) + driver.get("http://www.google.com/") + driver.quit() + \endcode + + In this example, + \list + \li \c executable_path has to be set to the WebEngineDriver's binary path + \li \c QTDIR is the directory where Qt is installed + \li \c options.binary_location has to be set to the browser's binary path + \endlist + + \note On Windows: \c executable_path='QTDIR/bin/webenginedriver.exe' + + Before executing the script, the \c QTWEBENGINE_REMOTE_DEBUGGING environment variable has to + be set. Its value is a port number what is used by both the browser and WebEngineDriver to + communicate with each other. + \badcode + export QTWEBENGINE_REMOTE_DEBUGGING=12345 + \endcode + + By executing, the script opens the specified web browser and loads the Google web site. + + WebEngineDriver can be also attached to an already running browser if it was started with the + remote debugging port set. \c options.debugger_address has to be set to the remote debugging + address in the script: + + \code + options.debugger_address = 'localhost:12345' + \endcode + + In this case, \c options.binary_location should not be set because the browser is already + running. The environment variable \c QTWEBENGINE_REMOTE_DEBUGGING is not used by the + WebEngineDriver if \c options.debugger_address is set. + + \note WebEngineDriver must be built with the same version of Chromium as \QWE is using. + + \section1 Chromium DevTools + + The Chromium DevTools provide the ability to inspect and debug layout and + performance issues of any web content. + + This feature can be tested by launching a \QWE application with the + command line option \c {--remote-debugging-port=[your-port]} or by setting + the environment variable \c QTWEBENGINE_REMOTE_DEBUGGING and then using a + Chromium based browser (such as \l{WebEngine Widgets Simple Browser Example} + {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}) to connect + to \c {http://localhost:[your-port]}. + + \note Any WebEngine command line options should be specified after the + \c {--webEngineArgs} option, which is used to separate the user's application + specific options from the WebEngine's ones. + + \badcode + --webEngineArgs --remote-debugging-port=5000 + \endcode + + To avoid WebSocket errors during remote debugging, add an additional command-line argument + \c {--remote-allow-origins=<origin>[,<origin>, ...]}, where \c <origin> refers to the request origin. + Use \c {--remote-allow-origins=*} to allow connections from all origins. If nothing is specified, + \QWE will add \c {--remote-allow-origins=*} to command-line arguments when remote-debugging is enabled, + thereby allowing requests from all origins. + + The Chromium DevTools page can also be shown within the application. To set + this up, you can call either QWebEnginePage::setInspectedPage() to the page + to be inspected, which implicitly loads the DevTools into the \c this page, + or QWebEnginePage::setDevToolsPage() to let the \c this page be inspected. + + The respective QML properties are \l{WebEngineView::devToolsView} + {WebEngineView.devToolsView} and \l{WebEngineView::inspectedView} + {WebEngineView.inspectedView}. + + For more information, see \l {Qt WebEngine Debugging and Profiling}. + + \section1 Client Certificates + + Some web servers, in particular many intranet sites, require the client to + authenticate itself with a certificate, called a \e {client certificate}. \QWE + will read the client certificates installed in the system settings in macOS and + Windows, and on Linux those installed into the NSS database. Certificates can + be installed into the NSS database using the \c pk12util tool. + + By default, \QWE will not offer any client certificates to servers, as doing + so uniquely identifies the user and might violate privacy expectations. + + To activate support for client certificates, an application needs to listen to + the QWebEnginePage::selectClientCertificate or + \l{WebEngineView::selectClientCertificate}{WebEngineView.selectClientCertificate} + signals and select one of the offered + certificates. For applications that can navigate to untrusted web sites, it is + recommended to always give the user a choice before uniquely identifying them + to a remote server. + + In addition to the client certificate stored in system settings, \QWE offers also + the in-memory store. The QWebEngineClientCertificateStore instance can be obtained with + the QWebEngineProfile::clientCertificateStore() method. An application can use this + class to add a new certificate with a QWebEngineClientCertificateStore::add() call. + Note that during the \c selectClientCertificate calls, \QWE lists both system + and in-memory stored clients certificates. + + See also \l{WebEngine Widgets Client Certificate Example}{Client Certificate Example} + for more implementation details. + + \section1 Custom Schemes + + \QWE makes it possible for the application to define its own custom + URL schemes with specialized security policies and transport mechanisms. + + Custom schemes can be used to implement alternative network protocols with + all the usual web security policies, privileged internal schemes for + displaying user interface components or debugging information, sandboxed + schemes with extra restrictions, and so on. + + For more information, see \l QWebEngineUrlScheme and \l + QWebEngineUrlSchemeHandler. + + \section1 Drag and Drop + + \QWE supports HTML5 drag and drop. + + This feature can be tested by opening an HTML5 drag and drop demo, such as + \l{HTML5 Demos - Drag and Drop}, \l{HTML5 Demos - Simple Drag and Drop}, or + \l{HTML5 Demos - Drag and Drop, Automatic Upload}, in \l{WebEngine Widgets + Simple Browser Example}{Simple Browser} or \l{WebEngine Quick Nano Browser} + {Nano Browser}. + + Dragging files into the browser is not actually part of HTML5, but it is + supported. It can be tested by opening \l{HTML5 Demos - File API}. + + Support for this feature was added in Qt 5.7.0. + + \section1 Favicon + + \QWE supports the web site URL icon, \e favicon. Each icon is stored in the internal + database for each \l QWebEngineProfile and can be accessed using a \l QWebEnginePage::icon() + call or a \l {WebEngineView::icon}{WebEngineView.icon} property for the currently loaded content. + + Moreover \QWE provides API for accessing already stored icons in the internal profile's database. + + \note The icon database is not available for off-the-record profiles. + + \section2 QML Favicon Handling + + For accessing icons a \c QQuickImageProvider is registered. This provider can be + accessed by a special URL where the scheme is "image:" and the host is "favicon". + + \qml + Image { + source: "image://favicon/url" + } + \endqml + + The \c url can be the URL of the favicon: + + \qml + Image { + source: "image://favicon/https://www.qt.io/hubfs/2016_Qt_Logo/qt_logo_green_rgb_16x16.png" + } + \endqml + + The \c url also can be a page URL to access its icon: + + \qml + Image { + source: "image://favicon/https://www.qt.io/" + } + \endqml + + If more than one icon is available, the \l {Image::sourceSize} property can be + specified to choose the icon with the desired size. If \l {Image::sourceSize} + is not specified or 0, the largest available icon will be chosen. + + The image provider looks up the requested icon in the existing \l {WebEngineView} + instances. First, it tries to match the currently displayed icons. If no match + has been found it requests the icon from the database. Each profile has its + own icon database and it is stored in the persistent storage thus the stored icons + can be accessed without network connection too. The icon must be previously loaded + to be stored in the database. + + \section2 C++ Favicon Handling + + A user can request an icon from the previously loaded content for each + \l QWebEngineProfile using the \l QWebEngineProfile::requestIconForPageURL() or + \l QWebEngineProfile::requestIconForIconURL() calls. Note that the profile's database is + stored in the persistent storage and can be accessed without a network connection. + + \section1 Fullscreen + + \QWE supports viewing web content in fullscreen mode. For more + information, see \l{WebEngineSettings::fullscreenSupportEnabled} + {WebEngineSettings.fullscreenSupportEnabled}, + \l{WebEngineView::fullScreenRequested}{WebEngineView.fullScreenRequested}, + QWebEngineSettings::FullScreenSupportEnabled, and + QWebEnginePage::fullScreenRequested. + + This feature can be tested by playing a video from YouTube in \l{WebEngine + Widgets Video Player Example}{Video Player} or \l{WebEngine Quick Nano Browser} + {Nano Browser}, and clicking the full screen icon to go into fullscreen + mode. + + Support for this feature was added in Qt 5.6.0. + + \section1 Hardware Acceleration + + QtWebEngine tries to use hardware acceleration for rendering the content. It uses + \c OpenGL or \c OpenGLES APIs to execute rendering calls on the GPU. As a fallback, + software rendering is used whenever the hardware does not meet the required set of + OpenGL functionality. A user can check the current hardware acceleration state by + loading the \c {chrome://gpu} internal page. Moreover, the acceleration can be explicitly + disabled with \c {QTWEBENGINE_CHROMIUM_FLAGS} using the \c {disable-gpu} switch. + For example on Linux: + + \badcode + export QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu + \endcode + + \section1 HTML5 DRM + + \QWE supports viewing DRM protected videos if the \l{Widevine CDM} plugin has been installed. + CDM plugin is a replacement of Flash based plugins for displaying DRM-protected content. + It comes only in a binary format, so it can hide DRM decryption implementation details. + It can be obtained from a third party or from a Google Chrome installation. + + \QWE on startup looks for the \l{Widevine CDM} plugin in well know locations, like + default Google Chrome installation directory or Linux distro specific paths. However, plugin + location can be also passed with \c {QTWEBENGINE_CHROMIUM_FLAGS} using \c {widevine-path}. + + On Windows: + \badcode + set QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="C:/some path/widevinecdm.dll" + \endcode + + On Linux: + \badcode + export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.so" + \endcode + + On macOS: + \badcode + export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.dylib" + \endcode + + + The video format most commonly used by DRM services, H.264, requires + proprietary audio and video codecs. For more information about enabling the + codecs, see \l{Audio and Video Codecs}. + + This feature can be tested by playing a video in \l{WebEngine Widgets Simple Browser + Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser} + from \l{castLabs}, \l{Swank Motion Pictures, Inc.}, or \l{Bitmovin Player}. + + Support for this feature was added in Qt 5.7.0. + + \section1 HTML5 Geolocation + + \QWE supports JavaScript Geolocation API with \l {Qt Positioning} as a + backend. HTML5 geolocation is disabled by default. To explicitly allow it, the application + needs to listen to QWebEnginePage::featurePermissionRequested. Use QWebEnginePage::Geolocation + with a QWebEnginePage::setFeaturePermission() call or \l{WebEngineView::Feature} + with a \l{WebEngineView::grantFeaturePermission} {WebEngineView.grantFeaturePermission}() call + to grant the required permission. + + If \QWE was built with Qt Positioning support then this feature can be + tested by using \l{WebEngine Widgets Maps Example}{Maps} and allowing it to + find the current position of the user. + + \note On Windows 11, enable settings to grant the maps example access to + Windows location services. In the Settings App under + \uicontrol {Privacy & Security} > \uicontrol {Location}, enable \uicontrol + {Location services}, \uicontrol {Let apps access your location} and \uicontrol + {Let desktop apps access your location}. + + See \l{Qt Positioning} for a possible backend setup like the GPS or IP based positioning. + + Support for this feature was added in Qt 5.5.0. + + \section1 HTML5 WebSockets + + \QWE supports the WebSocket JavaScript API to communicate with WebSocket servers + using the \c {ws://} or \c {wss://} protocols. Moreover, integration with Qt WebChannel + and Qt WebSockets enables communication between JavaScript and the native side of + the application. + + The Qt WebChannel module has a great example for a + \l[QtWebChannel]{Qt WebChannel ChatServer Example}{chat server} + and its web based + \l[QtWebChannel]{Qt WebChannel ChatClient HTML Example}{chat client}. + The client works out of the box in the example browsers of \QWE + (such as \l{WebEngine Widgets Simple Browser Example} + {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}). + + \section1 HTTP/2 Protocol + + \QWE supports the Chromium implementation of the \l{HTTP/2} + protocol. + + This feature can be tested by opening an HTTP/2 demo, such as the + \l{Akamai HTTP/2 Demo}, in \l{WebEngine Widgets Simple Browser Example} + {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}. + + \section1 Local Storage + + \QWE supports saving key-value pairs in a \c {Local Storage} with no expiration date. + This is a part of the \l + {https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API} + {Web Storage API}, where a user can access a \c Storage object for the given domains + using the \c Window.localStorage JavaScript property. The stored data will persist even + after the page or the browser application is closed. + + Note that the \c Local Storage can be also disabled with a + \l QWebEngineSettings::LocalStorageEnabled + setting. Moreover, the storage path can be adjusted with a + \l QWebEngineProfile::setPersistentStoragePath + call. + + \code + QWebEngineProfile profile("MyProfile"); + profile.settings()->setAttribute(QWebEngineSettings::LocalStorageEnabled, isEnabled); + profile.setPersistentStoragePath("/path/to/storage"); + \endcode + + \QWE offers also an easy way of investigating the content of the \c {Local Storage} + with \l {Qt WebEngine Developer Tools} by visiting the \uicontrol Application panel + and expanding the \uicontrol {Local Storage} menu. + + \section1 Native Dialogs + + A web page might request dialogs for the following functions: + + \list + \li Entering user credentials for HTTP and proxy authentication + \li Displaying JavaScript alerts, confirmation dialogs, and prompts + \li Picking colors + \li Selecting files + \li Displaying form validation messages + \endlist + + \QWE provides standard dialogs for these functions. In widget-based + applications, the standard dialogs are based on QDialog, whereas in Qt Quick + applications, they can be based either on Qt Quick Controls 1 or Qt Quick + Controls 2 (since Qt 5.8). The latter are used only on \c eglfs platforms. + + To explicitly force either dialogs based on Qt Quick Controls 1 or Qt Quick + Controls 2, set the \c QTWEBENGINE_DIALOG_SET environment variable to either + \c{QtQuickControls1} or \c{QtQuickControls2}. + + \QWE Widgets dialogs can be customized by reimplementing the + QWebEnginePage::chooseFiles(), QWebEnginePage::javaScriptAlert(), + QWebEnginePage::javaScriptConfirm(), and QWebEnginePage::javaScriptPrompt() + functions. + + Since Qt 5.8, Qt Quick dialogs can be customized by connecting to the + WebEngineView::authenticationDialogRequested(), + WebEngineView::javaScriptDialogRequested(), + WebEngineView::colorDialogRequested(), + WebEngineView::fileDialogRequested(), and + WebEngineView::formValidationMessageRequested() signals. For an example, + + \section1 PDF File Viewing + + \QWE supports viewing PDF documents by navigating to them. This feature uses the Chromium + extensions API and PDF viewer plugin to display the PDF documents. + It can be tested in \l{WebEngine Widgets Simple Browser Example}{Simple Browser} or + \l{WebEngine Quick Nano Browser}{Nano Browser}. + + Loading plugins needs to be enabled using QWebEngineSettings::PluginsEnabled or + WebEngineSettings::pluginsEnabled in order to use this feature. + + This feature can be turned on (default) or off via the QWebEngineSettings::PdfViewerEnabled or + WebEngineSettings::pdfViewerEnabled setting. + + Support for this feature was added in Qt 5.13.0. + + \section1 Page Lifecycle API + + \QWE supports the \l {https://wicg.github.io/page-lifecycle/spec.html}{Page + Lifecycle API specification}, a work-in-progress extension to the HTML + standard for allowing user agents to reduce their resource consumption by + freezing or discarding background pages. The feature is exposed both in the + Widgets and QML APIs. + + For an example of the QML API in use, see the \l {WebEngine Lifecycle + Example}. + + Support for this feature was added in Qt 5.14.0. + + \section2 Overview of Lifecycle States + + Each \l {WebEngineView} item (or \l {QWebEnginePage} object) can be in one + of three \e {lifecycle states}: active, frozen, or discarded. These states, + like the sleep states of a CPU, control the resource usage of web views. + + The \e {active} state is the normal, unrestricted state of a web view. All + visible web views are always in the active state, as are all web views that + have not yet finished loading. Only invisible, idle web views can be + transitioned to other lifecycle states. + + The \e {frozen} state is a low CPU usage state. In this state, most HTML + task sources are suspended (frozen) and, as a result, most DOM event + processing and JavaScript execution will also be suspended. The web view + must be invisible in order to be frozen as rendering is not possible in this + state. + + The \e {discarded} state is an extreme resource-saving state. In this state, + the browsing context of the web view will be discarded and the corresponding + renderer subprocess shut down. CPU and memory usage in this state is reduced + virtually to zero. On exiting this state the web page will be automatically + reloaded. The process of entering and exiting the discarded state is similar + to serializing the browsing history of the web view and destroying the view, + then creating a new view and restoring its history. + + See also \l {WebEngineView::LifecycleState}. The equivalent in the Widgets + API is \l {QWebEnginePage::LifecycleState}. + + \section2 The \c {lifecycleState} and \c {recommendedState} Properties + + The \l {WebEngineView::}{lifecycleState} property of the \l {WebEngineView} + type is a read-write property that controls the current lifecycle state of + the web view. This property is designed to place as few restrictions as + possible on what states can be transitioned to. For example, it is allowed + to freeze a web view that is currently playing music in the background, + stopping the music. In order to implement a less aggressive resource-saving + strategy that avoids interrupting user-visible background activity, the \l + {WebEngineView::} {recommendedState} property must be used. + + The \l {WebEngineView::}{recommendedState} property of the \l + {WebEngineView} type is a read-only property that calculates a safe limit on + the \l {WebEngineView::}{lifecycleState} property, taking into account the + current activity of the web view. So, in the example of a web view playing + music in the background, the recommended state will be \c {Active} since a + more aggressive state would stop the music. If the application wants to + avoid interrupting background activity, then it should avoid putting the web + view into a more aggressively resource-saving lifecycle state than what's + given by \l {WebEngineView::}{recommendedState}. + + See also \l {WebEngineView::lifecycleState} and \l + {WebEngineView::recommendedState}. The equivalents in the Widgets API are \l + {QWebEnginePage::lifecycleState} and \l {QWebEnginePage::recommendedState}. + + \section2 The DOM Extensions + + The \l {WebEngineView::}{lifecycleState} property is connected to the \l + {https://wicg.github.io/page-lifecycle/spec.html}{Page Lifecycle API + specification}, which specifies two new DOM events, \c {freeze} and \c + {resume}, and adds a new \c {Document.wasDiscarded} boolean property. The \c + {freeze} and \c {resume} events are fired when transitioning from the \c + {Active} to the \c {Frozen state}, and vice-versa. The \c + {Document.wasDiscarded} property is set to \c {true} when transitioning from + the \c {Discarded} state to the \c {Active} state. + + \section1 Print to PDF + + \QWE supports printing a web page to a PDF file. For more + information, see QWebEnginePage::printToPdf() and + \l{WebEngineView::printToPdf}{WebEngineView.printToPdf}. + + This feature can be tested using \l{WebEngine Widgets Html2Pdf Example} + {Html2Pdf}. + + Support for this feature was added in Qt 5.7.0. + + \section1 Process Models + + \QWE uses multiple OS processes to isolate web sites from each other + and from the client application, improving security and robustness. The + following process models, or ways to divide web sites between OS processes, + are supported: + + \list + \li \l{Process per Site Instance} + \li \l{Process per Site} + \li \l{Single Process} + \endlist + + \section2 Process per Site Instance + + This is the default model. Pages from separate sites are put into separate + processes and separate visits to the same site are also isolated. + + Two web pages are considered as belonging to the same site if they originate + from the same registered domain name (for example, \c wikipedia.org) and + scheme (for example, \c https). This is similar to the same-origin policy + but subdomains are ignored. For example, both \c{https://en.wikipedia.org/} + and \c{https://de.wikipedia.org/} would belong to the same site. + + A site instance is a collection of web pages belonging to the same site. + When the application explicitly loads a URL into \QWE (via \l + QWebEnginePage::setUrl, for example), a new site instance is created for the + page. However, when the user clicks same-site links on the page, the + existing site instance is merely extended with more pages. + + For instance, in the \l{WebEngine Widgets Simple Browser Example}{Simple + Browser} example, when a user opens two tabs and explicitly enters + \c{https://en.wikipedia.org/} into the URL bars, both tabs will have their + own separate OS processes (because explicitly entering a URL creates a new + site instance). However, when the user then middle-clicks some same-site + links to open more tabs, these new tabs will share the same OS process + (because user interaction extends the existing site instance). + + \section2 Process per Site + + Pages from separate sites are put into separate processes. Unlike Process + per Site Instance, all visits to the same site will share an OS process. + + The benefit of this model is reduced memory consumption, because more web + pages will share processes. The drawbacks include reduced security, + robustness, and responsiveness. + + To enable this model, use the command-line argument \c{--process-per-site}. + See \l{Using Command-Line Arguments}. + + \section2 Single Process + + For debugging purposes only, a single process mode can be enabled using the + command-line argument \c{--single-process}. See \l{Using Command-Line + Arguments} and \l{Qt WebEngine Debugging and Profiling}. + + \section1 Spellchecker + + \QWE supports integrating spellchecking support into HTML forms to + enable users to submit spellchecked messages. When the user clicks on + an underlined misspelled word, the default context menu displays up to four + suggestions. Selecting one will replace the misspelled word. + + To be able to check the spelling, the spellchecker needs dictionaries. It + supports dictionaries from the \l{Hunspell project}, but they have to be + compiled into a special binary format. A Hunspell dictionary consists of two + files: + + \list + + \li A \c .dic file that is a dictionary containing words for the + language + \li An \c .aff file that defines the meaning of special flags in the + dictionary + \endlist + + These two files can be converted into the \c bdic format by using the + \c qwebengine_convert_dict tool that is shipped together with Qt. + When the \QWE spellchecker initializes, it will try to load the + \c bdict dictionaries and to check them for consistency. + + If \c QTWEBENGINE_DICTIONARIES_PATH is set, the spellchecker uses the + dictionaries in the specified directory without looking anywere else. + Otherwise, it uses the \e qtwebengine_dictionaries directory relative to the + executable if it exists. If it does not exist, it will look in \c + QT_INSTALL_PREFIX/qtwebengine_dictionaries. + + On macOS, depending on how \QWE is configured at build time, there + are two possibilities how spellchecking data is found: + + \list + \li Hunspell dictionaries (default) - .bdic dictionaries are used, just + like on other platforms + \li Native dictionaries - the macOS spellchecking APIs are used (which + means the results will depend on the installed OS dictionaries) + \endlist + + Thus, in the macOS Hunspell case, \QWE will look in the \e + qtwebengine_dictionaries subdirectory located inside the application bundle + \c Resources directory, and also in the \c Resources directory located + inside the Qt framework bundle. + + To summarize, in case of Hunspell usage, the following paths are considered: + + \list + \li \c QTWEBENGINE_DICTIONARIES_PATH, if set + \li QCoreApplication::applicationDirPath()/qtwebengine_dictionaries + or QCoreApplication::applicationDirPath()/../Contents/Resources/qtwebengine_dictionaries + (on macOS) + \li [QLibraryInfo::DataPath]/qtwebengine_dictionaries + or path/to/QtWebEngineCore.framework/Resources/qtwebengine_dictionaries (Qt framework + bundle on macOS) + \endlist + + Spellchecking is disabled by default and can be enabled per profile by + using the QWebEngineProfile::setSpellCheckEnabled() method in widget-based + applications and the \l {QQuickWebEngineProfile::spellCheckEnabled} + {WebEngineProfile.spellCheckEnabled} property in Qt Quick applications. + + The current language used for spellchecking is defined per profile, and can + be set using the QWebEngineProfile::setSpellCheckLanguages() method or the + \l {QQuickWebEngineProfile::spellCheckLanguages} + {WebEngineProfile.spellCheckLanguages} property. + + This feature can be tested by building and running the + \l{WebEngine Widgets Spellchecker Example}{Spellchecker Example}. + + \QWE can be compiled also without spellchecker support with the use of + a \c {webengine-spellchecker} configure switch. + + \badcode + qt-configure-module path\to\qtwebengine\sources -no-webengine-spellchecker + \endcode + + For more information, see \l{Qt Configure Options}. + + Support for this feature was added in Qt 5.8.0. + + \section1 Touch + + \QWE supports touch devices for navigating and interacting with web pages. + + Applications can prohibit the use of touch events in the following ways: + + \list + \li Passing the flag \c --touch-events=disabled on the command line will disable touch event + support in JavaScript API (meaning \c ontouchstart and related handlers will not be present + in the \c document.window object). Touch events will still be delivered to web pages. + + \li Installing an event filter object using \l {QObject::installEventFilter} on the WebEngine + view focus proxy object, and filtering out all touch events. + + \endlist + + \section1 View Source + + \QWE supports viewing the HTML source of a web page. + + This feature can be used from custom menus or assigned to custom events. + For more information, see WebEngineView::WebAction, and QWebEnginePage::WebAction. + + This feature can be tested by opening a web page in \l{WebEngine Widgets + Simple Browser Example}{Simple Browser} or \l{WebEngine Quick Nano Browser} + {Nano Browser}, and then selecting \c{Page Source} in the context menu. The + \c{Page Source} context menu entry opens the source view in a new tab. + + For opening the source view in the current tab, URLs with \l{view-source URI scheme} + are also supported. For example, you can type the following URL to the URL bar + to view the HTML source of the qt.io web page: + \badcode + view-source:https://www.qt.io/ + \endcode + + Auto-completion of incomplete URLs with \l{view-source URI scheme} makes the usage of + this feature more comfortable. For example, the following incomplete URL also loads + the source view of the qt.io web page: + \badcode + view-source:qt.io + \endcode + + Support for this feature was added in Qt 5.8.0. + + \section1 Web Notifications + + Qt WebEngine supports JavaScript \l{Web Notifications API}. + The application has to explicitly allow the feature by using + QWebEnginePage::Notifications or \l{WebEngineView::Feature} + {WebEngineView.Notifications}. + + Support for this feature was added in Qt 5.13.0. + + \section1 WebGL + + \QWE supports WebGL for some graphics stacks setups. A user can visit the + chrome://gpu page using the QtWebEngine powered application. The \e {Graphics Feature Status} + overview states if WebGL is supported for the current platform setup. A user can also + check the \l {https://webglreport.com}{WebGL Report}. + + The WebGL support is enabled by default. You can disable it with the + \l QWebEngineSettings::WebGLEnabled setting. + + \target webrtc_feature + \section1 WebRTC + + WebRTC provides browsers with Real-Time Communications (RTC) capabilities + via simple APIs. For more information, see \l{WebEngineView::Feature} + {WebEngineView.Feature}, and QWebEnginePage::Feature. + + This feature can be tested by setting up a webcam or microphone and then + opening \c https://test.webrtc.org/ in \l{WebEngine Widgets Simple Browser + Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}. + +*/ diff --git a/src/core/doc/src/qtwebengine-global.qdoc b/src/core/doc/src/qtwebengine-global.qdoc new file mode 100644 index 000000000..7f6636c16 --- /dev/null +++ b/src/core/doc/src/qtwebengine-global.qdoc @@ -0,0 +1,56 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \headerfile <qtwebenginecoreglobal.h> + \inmodule QtWebEngineCore + \title Global Qt WebEngine Core Declarations + \ingroup funclists + + \brief Helper functions for the \QWE Core module. + +*/ + + +/*! + \fn const char *qWebEngineVersion() noexcept + \relates <qtwebenginecoreglobal.h> + \since 6.2 + + Returns the version number of \QWE at run-time as a string + (for example, "6.2.0"). This may be a different version than the + version the application was compiled against, and a different version + than Qt. +*/ + +/*! + \fn const char *qWebEngineChromiumVersion() noexcept + \relates <qtwebenginecoreglobal.h> + \since 6.2 + + Returns the version number of Chromium used by \QWE at run-time + as a string (for example, "83.0.4103.122"). +*/ + +/*! + \fn const char *qWebEngineChromiumSecurityPatchVersion() noexcept + \relates <qtwebenginecoreglobal.h> + \since 6.3 + + Returns the version number of last Chromium version security patches have been + merged from. +*/ + +/*! + \fn QString qWebEngineGetDomainAndRegistry(const QUrl &url) + \relates <qtwebenginecoreglobal.h> + \since 6.6 + + Returns the domain of the host, that is, the effective top-level domain + (eTLD) and the first domain below it, from \a url. + + This function supports internationalized domain names (IDN). In this case, + it returns the domain encoded in Punycode. + + If the host is not a domain, returns an empty string. +*/ diff --git a/src/core/doc/src/qtwebengine-index.qdoc b/src/core/doc/src/qtwebengine-index.qdoc new file mode 100644 index 000000000..b20a96dc1 --- /dev/null +++ b/src/core/doc/src/qtwebengine-index.qdoc @@ -0,0 +1,47 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-index.html + \title Qt WebEngine + + \brief Provides functionality for rendering regions of dynamic web content. + + \QWE provides functionality for rendering regions of dynamic web content. + + The functionality in \QWE is divided into the following modules: + + \annotatedlist qtwebengine-modules + + \section1 Articles and Guides + + \list + \li \l{Qt WebEngine Overview} + \li \l{Qt WebEngine Features} + \li \l{Qt WebEngine Platform Notes} + \li \l{Qt WebEngine Licensing} + \li \l{Qt WebEngine Debugging and Profiling} + \li \l{Deploying Qt WebEngine Applications} + \li \l{Porting from Qt WebKit to Qt WebEngine} + \endlist + + + \section1 Module Evolution + + \l{Changes to Qt WebEngine} lists important changes in the module API + and functionality that were done for the Qt 6 series of Qt. + + \section1 Examples + + \list + \li \l{Qt WebEngine Quick Examples} + \li \l{Qt WebEngine Widgets Examples} + \endlist + + \section1 API References + + \list + \li \l{Qt WebEngine C++ Classes and Namespaces} + \li \l{Qt WebEngine QML Types} + \endlist +*/ diff --git a/src/core/doc/src/qtwebengine-modules.qdoc b/src/core/doc/src/qtwebengine-modules.qdoc new file mode 100644 index 000000000..ee1ad8188 --- /dev/null +++ b/src/core/doc/src/qtwebengine-modules.qdoc @@ -0,0 +1,25 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-modules.html + \title Qt WebEngine C++ Classes and Namespaces + \brief Provides functionality for rendering regions of dynamic web content. + + \QWE provides functionality for rendering regions of dynamic web content. + + \section1 Namespaces + \annotatedlist qtwebengine-namespaces + + \section1 Classes + + \section2 Qt WebEngine Core Module + \generatelist {classesbymodule QtWebEngineCore} + + \section2 Qt WebEngine Widgets Module + \generatelist {classesbymodule QtWebEngineWidgets} + + \section2 Qt WebEngine Quick Module + \generatelist {classesbymodule QtWebEngineQuick} + +*/ diff --git a/src/core/doc/src/qtwebengine-overview.qdoc b/src/core/doc/src/qtwebengine-overview.qdoc new file mode 100644 index 000000000..3a5d30338 --- /dev/null +++ b/src/core/doc/src/qtwebengine-overview.qdoc @@ -0,0 +1,312 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-overview.html + \title Qt WebEngine Overview + \ingroup explanations-webtechnologies + + The \QWE module provides a web browser engine that makes it easy to embed content from + the World Wide Web into your Qt application on platforms that do not have a native web engine. + + \QWE provides C++ classes and QML types for rendering HTML, XHTML, and SVG documents, + styled using Cascading Style Sheets (CSS) and scripted with JavaScript. HTML documents can be + made fully editable by the user through the use of the \c{contenteditable} attribute on HTML + elements. + + \section1 Qt WebEngine Architecture + + \image qtwebengine-architecture.png + + The functionality in \QWE is divided into the following modules: + + \list + \li \l{Qt WebEngine Widgets Module} for creating widget-based web applications + \li \l{Qt WebEngine Module} for creating Qt Quick based web applications + \li \l{Qt WebEngine Core Module} for interacting with Chromium + \endlist + + Page rendering and JavaScript execution are separated from the GUI process into the \QWE + Process. It is a library that must be shipped with the application if the Qt libraries are + bundled into the application. + + \section2 Qt WebEngine Widgets Module + + \image qtwebenginewidgets-model.png + + A \e {web engine view} is the main widget component of the \QWE module. It can be used + in various applications to load web content. Within a view, a \e {web engine page} holds a main + frame that is responsible for web content, the \e history of navigated links, and \e actions. + The view and page are quite similar, as they provide a set of common functions. + + All pages belong to a \e {web engine profile} that contains shared \e settings, \e scripts, and + \e cookies. Profiles can be used to isolate pages from each other. A typical use case is a + dedicated profile for a \e {private browsing} mode, where no information is permanently saved. + + \note The \QWE Widgets module uses the \l{Qt Quick Scene Graph}{Qt Quick scene graph} + to compose the elements of a web page into one view. + + The content is rendered using the graphics card (GPU) capabilities. The scene + graph, in turn, relies on the Qt Rendering Hardware Interface as an abstraction + layer for the different capabilities and APIs a GPU might feature. For more + advice on how to tweak the rendering pipeline, see therefore + \l{Rendering via the Qt Rendering Hardware Interface}. + + \section2 Qt WebEngine Module + + \image qtwebengine-model.png + + The \QWE QML implementation contains the same elements as the \QWE Widgets + implementation, except that there is no separately accessible web engine page. + The supported page functionality is integrated into the web engine view. + + \section2 Qt WebEngine Core Module + + The \QWE core is based on the \l {Chromium Project}. Chromium provides its own network + and painting engines and is developed tightly together with its dependent modules. + Even though the QtNetwork stack is not used, its setup can be synchronized with the \QWE. + See \l {Proxy Support}, \l {Managing Certificates}, \l {Client Certificates}, and + \l {QWebEngineCookieStore} for more details. + + \note \QWE is based on Chromium, but does not contain or use any services + or add-ons that might be part of the Chrome browser that is built and delivered by Google. + You can find more detailed information about the differences between Chromium and Chrome in this + \l{https://chromium.googlesource.com/chromium/src/+/master/docs/chromium_browser_vs_google_chrome.md}{overview} + that is part of the documentation in the \l {Chromium Project} upstream source tree. + + The Chromium version used is the one used by the latest stable Chrome version at the time of Qt feature freeze + for the current version of \QWE. Additional security patches are cherry picked from newer Chrome releases on + every patch release, security patches released in time for the Qt patch release freeze will be included. + If Chrome releases critical fixes outside our release window, the next patch release is sped up to ensure a + patched \QWE is released before the patch details goes public. + + If you need a newer \QWE beyond security fixes, and can not update all of Qt, \QWE supports building with + older version of Qt back to the last Qt LTS. For instance \QWE 6.3, 6.4, and 6.5 can all be built with Qt 6.2. + In Qt LTS releases, \QWE may be fully replaced with such a newer version to make security patching easier. + + The relevant Chromium versions in question can also be read at runtime using the + \l qWebEngineChromiumVersion() method, and \l qWebEngineChromiumSecurityPatchVersion() + to read the current security patch level. You can also find the versions in the \QWE + sources in the CHROMIUM_VERSION file. + + \section2 Qt WebEngine Process + + The \QWE Process is a separate executable that is used to render web pages and + execute JavaScript. This mitigates security issues and isolates crashes caused by specific + content. + + \section1 Embedding Web Content into Widget Based Applications + + Use the QWebEngineView class to display web pages in the simplest way. Because it is a widget, + you can embed QWebEngineView into your forms and use its convenience functions to download and + display web sites. + + \code + QWebEngineView *view = new QWebEngineView(parent); + view->load(QUrl("http://www.qt.io/")); + view->show(); + \endcode + + An instance of QWebEngineView has one QWebEnginePage. QWebEnginePage can have a + QWebEngineHistory that provides access to the page's navigation history and several QAction + objects that apply actions on the web page. In addition, a QWebEnginePage has the ability to + run JavaScript code in the context of the page's main frame and to enable customization of + handlers for specific events like showing custom authentication dialogs. + + Each QWebEnginePage belongs to a QWebEngineProfile that can have a QWebEngineSettings + for specifying page settings, a QWebEngineScriptCollection for running scripts on the page, and + a QWebEngineCookieStore for accessing the HTTP cookies of Chromium. A QWebEnginePage can also + directly point to a script collection. + + For a widget based application, the web engine is automatically initialized, unless it is + placed in a plugin. In that case, it must be initialized in the application main source file + by using \l QtWebEngineQuick::initialize, as illustrated by the following code snippet: + + \code + int main(int argc, char **argv) + { + QtWebEngineQuick::initialize(); + + QApplication app(argc, argv); + + QMainWindow window; + window.show(); + + return app.exec(); + } + \endcode + + \section1 Embedding Web Content into Qt Quick Applications + + The WebEngineView QML type allows Qt Quick applications to render regions of dynamic web + content. A \e{WebEngineView} type may share the screen with other QML types or encompass the + full screen as specified within the Qt Quick application. + + To make sure that OpenGL context can be shared between the GUI and render processes, the web + engine must be initialized by using \l QtWebEngineQuick::initialize in the application main source + file, as illustrated by the following code snippet: + + \code + int main(int argc, char *argv[]) + { + QGuiApplication app(argc, argv); + + QtWebEngineQuick::initialize(); + + QQmlApplicationEngine engine; + engine.load(QUrl("qrc:/main.qml")); + + return app.exec(); + } + \endcode + + An application can load pages into the WebEngineView, using either an URL or HTML string, and + navigate within session history. By default, links to different pages load within the same + WebEngineView object, but web sites may request them to be opened as a new tab, window, or + dialog. + + The following sample QML application loads a web page using the \l{WebEngineView::}{url} + property: + + \quotefromfile minimal/main.qml + \skipto import + \printuntil /^\}/ + + \section1 Script Injection + + \QWE does not allow direct access to the document object model (DOM) of a page. + However, the DOM can be inspected and adapted by injecting scripts. + + The DOM of a page is constructed when the document is ready, typically + when the page is completely loaded. Therefore, executing scripts as soon as a document is + created is not suitable for DOM operations, where one has to wait until the DOM is ready. + + In addition, an injected script shares the same \e world as the other scripts executed on the + page, which might lead to conflicts. To avoid this, the QWebEngineScript class and the + WebEngineScript QML type provide implementations of the Chromium API for + \e{Content Script Extensions}. They specify the + script to run, the injection point, and the world where the script is run. This enables + accessing the DOM to manipulate it within a world. + + Since Qt 5.8, \QWE supports augmenting a script by using the + following \l{Metadata Block}{Greasemonkey-like attributes}: + + \list + \li \c {@exclude <regexp>} + \li \c {@include <regexp>} + \li \c {@match <regexp>} + \li \c {@name <free text>} + \li \c {@run-at [document-start|document-end|document-idle]} + \endlist + + The attributes determine if and when a \l {User Scripts}{user script} is + run. They must be placed immediately in the beginning of the script, inside + a \c ==UserScript== comment: + + \code + // ==UserScript== + // @include http://*.qt.io/* + // @exclude http://wiki.qt.io/* + // ==/UserScript== + + window.alert("Page is from qt.io, but not wiki.qt.io"); + \endcode + + If your WebEngine application is built using the Qt Quick Compiler, and the application ships + JavaScript files inside .qrc resources, consider reading the section + \l{JavaScript Files in Qt Resource Files}. + + \section1 Managing Certificates + + \QWE uses its own network stack, and therefore QSslConfiguration is not used to + open SSL connections. Instead, \QWE uses the root CA certificates from the operating + system to validate the peer's certificate. + + The \l{WebEngineCertificateError::type} and \l{QWebEngineCertificateError::Type} enumerations + provide information about the types of certificate errors that might occur. The errors can be + handled by using the WebEngineView::certificateError QML method or by connecting to the + QWebEnginePage::certificateError signal. + + \section1 Proxy Support + + \QWE uses the proxy settings from \l{Qt Network}, and forwards them to Chromium's + networking stack. If QNetworkProxy::applicationProxy is set, it will also be used for \QWE. + If QNetworkProxyFactory::usesSystemConfiguration() is enabled, the proxy settings + are automatically retrieved from the system. Settings from an installed QNetworkProxyFactory + will be ignored, though. + + In case QNetworkProxy::user() and QNetworkProxy::password() are set, these credentials + will be automatically used for proxy authentication. It is up to the user to provide valid + credentials, since there is no error handling callback. + + If no credentials are set with QNetworkProxy, but the proxy requires authentication, + QWebEnginePage::proxyAuthenticationRequired is emitted. + For Qt Quick, a dialog is shown. + + Not all properties of QNetworkProxy are supported by \QWE. That is, + QNetworkProxy::type(), QNetworkProxy::hostName() and QNetworkProxy::port() are taken into + account. All other proxy settings such as QNetworkProxy::rawHeader() are ignored. + + \section1 High DPI Support + + To support High DPI devices, it is recommended that the application attribute + Qt::AA_EnableHighDpiScaling is set to enable automatic scaling based on the + pixel density of the monitor. In \QWE applications, the scaling + affects the default zooming factor and scrollbar size. + + For example: + + \code + int main(int argc, char *argv[]) + { + QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); + QApplication app(argc, argv); + // ... + } + \endcode + + \QWE bundles images for normal and high-dpi resolutions into + \e qtwebengine_resources_100p.pak and \e qtwebengine_resources_200p.pak + files. Depending on the target resolutions, one or both of these files need + to be deployed. + + For more information, see \l{High DPI}. + + \section1 Using WebEngine Core + + \QWE Core provides an API shared by \QWE and \QWE Widgets for handling + URL requests issued for the networking stack of Chromium and for accessing its HTTP cookies. + + Implementing the QWebEngineUrlRequestInterceptor interface and installing the interceptor on a + profile enables intercepting, blocking, and modifying URL requests (QWebEngineUrlRequestInfo) + before they reach the networking stack of Chromium. + + A QWebEngineUrlSchemeHandler can be registered for a profile to add support for custom URL + schemes. Requests for the scheme are then issued to QWebEngineUrlSchemeHandler::requestStarted() + as QWebEngineUrlRequestJob objects. + + The QWebEngineCookieStore class provides functions for accessing HTTP cookies of Chromium. + The functions can be used to synchronize cookies with QNetworkAccessManager, as well as to set, + delete, and intercept cookies during navigation. + + \section1 Platform Notes + + \QWE currently supports only Windows, Linux, and \macos. Due to Chromium build + requirements it also often requires a newer compiler than the rest of Qt. See + \l{Qt WebEngine Platform Notes} for further details. + + \section1 Related Modules + + \QWE supersedes the \l{http://doc.qt.io/archives/qt-5.3/qtwebkit-index.html}{Qt WebKit} + module, which is based on the + WebKit project, but has not been actively synchronized with the upstream WebKit code since + Qt 5.2 and has been deprecated in Qt 5.5. For tips on how to change a Qt \WebKit widgets + application to use \QWE widgets, see \l{Porting from Qt WebKit to Qt WebEngine}. + + The \l{Qt WebView} module allows to use a native web browser on platforms where one is + available. + + The \l{Qt WebChannel} module can be used to create a bi-directional communication channel + between QObject objects on the C++ side and JavaScript on the QML side. + +*/ diff --git a/src/core/doc/src/qtwebengine-platform-notes.qdoc b/src/core/doc/src/qtwebengine-platform-notes.qdoc new file mode 100644 index 000000000..33bac101a --- /dev/null +++ b/src/core/doc/src/qtwebengine-platform-notes.qdoc @@ -0,0 +1,223 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtwebengine-platform-notes.html + \title Qt WebEngine Platform Notes + + \brief Contains information about issues that are specific to the \QWE module. + + \section1 Building \QWE from Source + + Static builds are not supported. + + The requirements for building Qt modules from source are listed separately for each supported + platform: + + \list + \li \l{Qt for Windows - Building from Source} + \li \l{Qt for X11 Requirements} + \li \l{Qt for macOS - Building from Source} + \endlist + + In addition, the following tools are required for building the \l {Qt WebEngine} module: + + \list + \li \l {All Platforms} + \li \l {Windows} + \li \l {Linux} + \li \l {macOS} + \endlist + + \section2 All Platforms + + On all platforms, the following tools are required at build time: + + \list + \li C++20 compiler support + \li CMake 3.19 or newer + \li \l Python 3 with html5lib library + \li Bison, Flex + \li GPerf + \li Node.js version 14 or later + \endlist + + \section2 Windows + + On Windows, the following additional tools are required: + + \list + \li Visual Studio 2019 or later, or clang-cl version 10 or later + \li Active Template Library (ATL), usually included in the Visual Studio + installation + \li Windows 11 SDK version 10.0.22621.0 or later + \endlist + + \note It is not recommended to use tools from \c msys2 or \c cygwin to build \QWE as it may result in build errors. + + \section2 Linux + + On Linux, Clang or GCC version 9 or later is required. + + \QWE requires \c pkg-config to detect most of its dependencies. The + following \c pkg-config files are required: + + \list + \li \c dbus-1 + \li \c fontconfig + \endlist + + If Qt was configured for \c xcb, the following \c pkg-config files are also + required: + + \list + \li \c libdrm + \li \c xcomposite + \li \c xcursor + \li \c xi + \li \c xrandr + \li \c xscrnsaver + \li \c xtst + \endlist + + \section2 \macos + + On \macos, the following are required: + + \list + \li \macos 10.14 or later + \li Xcode 12.0 or later + \li \macos 11 SDK or later + \endlist + + \note \QWE cannot be built for the 32-bit mode of \macos (using the + \c macx-clang-32 \c mkspec). + + \section1 Using Earlier Qt Versions to Build \QWE + + Building \QWE with earlier Qt versions (down to the last LTS + version) is supported. It means that \QWE 6.4 can be built with + Qt 6.2.x, Qt 6.3.x, and Qt 6.4. + + To use an earlier Qt version to build Qt Webengine: + + \list 1 + \li Download the qtwebengine sources. + \li From the earlier Qt version, run + \c {qmake && make (&& make install)}. + \endlist + + \section1 Mac App Store Compatibility + + Applications using \QWE are not compatible with the Mac App Store, because: + + \list + \li The Chromium part of the code uses several private API methods, which are prohibited by + the App Store. + \li Applications submitted to the App Store must be code-signed with the App Sandbox feature + enabled. The App Sandbox feature interferes with Chromium's own sandbox + initialization, which results in Chromium not being properly initialized. This also + ties in with the private API usage. Furthermore, standalone Chromium itself is not + officially tested with the App Sandbox enabled, and even if work is done to bypass + the App Store's restrictions, that would not guarantee correct behavior of the library. + + \endlist + + \section1 macOS Airplay Support on MacBooks with Dual GPUs + + To make \QWE work correctly when streaming to an AppleTV from a MacBook that supports + GPU switching, it is important to add the \c NSSupportsAutomaticGraphicsSwitching option to the + application Info.plist file, with the value set to \c YES. Otherwise rendering issues might + occur when creating new web engine view instances after Airplay is switched on or off. + + \section1 Default QSurfaceFormat OpenGL Profile Support + + If a new default QSurfaceFormat with a modified OpenGL profile has to be set, it should be set + before the application instance is declared, to make sure that all created OpenGL contexts use + the same OpenGL profile. + + On \macos, if the default QSurfaceFormat is set after the application instance, the application + will exit with qFatal(), and print a message that the default QSurfaceFormat should be set + before the application instance. + + \section1 Sandboxing Support + + \QWE provides out-of-the-box sandboxing support for Chromium render + processes. + + On Linux, note the following restrictions: + + \list + \li The kernel has to support the anonymous namespaces feature + (kernel version 3.8 or later). However, on Debian, Ubuntu, + and other Debian-derived distributions, this feature is off + by default. It can be turned on by setting + \c /proc/sys/kernel/unprivileged_userns_clone to 1. + \li The kernel has to support the \c seccomp-bpf feature (kernel + version 3.5 or later). + \li Setuid sandboxes are not supported and are thus disabled. + \endlist + + To explicitly disable sandboxing, use one of the following options: + + \list + \li Set the \c QTWEBENGINE_DISABLE_SANDBOX environment variable to 1. + \li Pass the \c{--no-sandbox} command line argument to the user + application executable. + \li Set \c QTWEBENGINE_CHROMIUM_FLAGS to \c{--no-sandbox}. + \endlist + + For more information, see \l{Using Command-Line Arguments}. + + \section1 Memory Requirements in Docker Environment + + When running Qt Web Engine examples in a Docker container and browsing + content-heavy sites, BUS errors (SIGBUS) might be reported. Typically, + this is caused by Docker running a container with a too small memory space + (such as 64MB). To fix this problem, increase the memory space size. + + \section1 Accessibility and Performance + + \QWE enables accessibility support for web pages when the following conditions + are met: + + \list + \li Qt Core is configured and built with accessibility support enabled. + \li The QPA plugin is notified by the operating system that accessibility should be + activated. This happens for example when using a screen reader application on Windows + or VoiceOver on \macos. + \endlist + + On some old Linux configurations, accessibility can cause a significant slowdown + on large HTML pages. + + Because of that, \QWE accessibility support can be disabled on Linux, by setting the + \c QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY environment variable to 0. + + \section1 Popups in Fullscreen Applications on Windows + Because of a limitation in the Windows compositor, applications that show a fullscreen web + engine view will not properly display popups or other top-level windows. The reason and + workaround is described in \l {Fullscreen OpenGL Based Windows}. + + \target windows_manifest + \section1 Windows Application Manifest + A manifest is an XML file that is read when the program starts and informs Windows how to run the program. + Some \QWE features may require adding a manifest file for the user application to work correctly on Windows. + + The following snippets show the manifest file's structure and how to embed it into the program. + + \note These code snippets are taken from the \l {WebEngine Quick Nano Browser} example. + + The manifest file defines which Windows versions the application supports. + \l {QWebEngineProfile::} {httpUserAgent} needs this information to report the correct Windows version. + \quotefile ../../../../examples/webenginequick/quicknanobrowser/quicknanobrowser.exe.manifest + + To embed the file into the executable, add it to the sources: + \quotefromfile ../../../../examples/webenginequick/quicknanobrowser/CMakeLists.txt + \skipto qt_add_executable + \dots + \printuntil endif + \dots + + For more information, see the \l {https://learn.microsoft.com/en-us/windows/win32/sbscs/application-manifests} {Application manifest documentation page}. +*/ diff --git a/src/core/doc/src/qtwebenginecore-index.qdoc b/src/core/doc/src/qtwebenginecore-index.qdoc index 692e33d1d..e6fc0b307 100644 --- a/src/core/doc/src/qtwebenginecore-index.qdoc +++ b/src/core/doc/src/qtwebenginecore-index.qdoc @@ -1,49 +1,26 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtwebenginecore-index.html \title Qt WebEngine Core - \brief Provides common API shared by \QWE and \QWE Widgets. + \brief Provides common API shared by \QWE Quick and \QWE Widgets. - \QWE Core provides API shared by \l {Qt WebEngine} and \l {Qt WebEngine Widgets}. + \QWE Core provides API shared by \l {Qt WebEngine QML Types}{Qt WebEngine Quick} and + \l {Qt WebEngine Widgets C++ Classes}{Qt WebEngine Widgets}. \section1 Getting Started - To include the definitions of the module's classes, use the - following directive: - - \snippet qtwebenginecore_build_snippet.qdoc 1 - To link against the module, add this line to your qmake project file: \snippet qtwebenginecore_build_snippet.qdoc 0 + For build with CMake use the \c find_package() command to locate the needed module components + in the Qt6 package and \c target_link_libraries() to link against the module: + + \snippet qtwebenginecore_build_snippet.qdoc 2 + \section1 Articles and Guides \list diff --git a/src/core/doc/src/qtwebenginecore-module.qdoc b/src/core/doc/src/qtwebenginecore-module.qdoc index c976d024c..188609793 100644 --- a/src/core/doc/src/qtwebenginecore-module.qdoc +++ b/src/core/doc/src/qtwebenginecore-module.qdoc @@ -1,53 +1,32 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \module QtWebEngineCore \title Qt WebEngine Core C++ Classes - \brief Provides public API shared by both QtWebEngine and QtWebEngineWidgets. + \brief Provides public API shared by both QtWebEngineQuick and QtWebEngineWidgets. \since 5.6 \ingroup qtwebengine-modules \ingroup modules - - To include the definitions of the module's classes, use the - following directive: - - \snippet qtwebenginecore_build_snippet.qdoc 1 + \qtvariable webenginecore + \qtcmakepackage WebEngineCore If you use qmake to build your projects, \QWE Core is usually - indirectly included through the \l{Qt WebEngine QML Types}{Qt WebEngine} or + indirectly included through the \l{Qt WebEngine QML Types}{Qt WebEngine Quick} or \l{Qt WebEngine Widgets C++ Classes}{Qt WebEngine Widgets} modules. \if !defined(qtforpython) - To link against the module, add this line to your qmake project file: + To link against the module using build with qmake, + add this line to your qmake project file: \snippet qtwebenginecore_build_snippet.qdoc 0 - However, \c webenginecore is implied by adding \c webengine or \c webenginewidgets. + However, \c webenginecore is implied by adding \c webenginequick or \c webenginewidgets. + + For build with CMake use the \c find_package() command to locate the needed module components + in the Qt6 package and \c target_link_libraries() to link against the module: + + \snippet qtwebenginecore_build_snippet.qdoc 2 \endif */ diff --git a/src/core/doc/src/qwebengine-licensing.qdoc b/src/core/doc/src/qwebengine-licensing.qdoc new file mode 100644 index 000000000..936ceff97 --- /dev/null +++ b/src/core/doc/src/qwebengine-licensing.qdoc @@ -0,0 +1,63 @@ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group qtwebengine-licensing +\title Qt WebEngine Licensing + +The \QWE module uses Chromium to provide most of its +functionality. During the build process, Chromium becomes +a part of the \l{Qt WebEngine Core} library. +Therefore, when distributing \QWE, users need to comply +to both the licenses of the \QWE part as developed under +the Qt Project, as well as the licenses that are part of +Chromium. + +The Qt specific parts of the \QWE module are available under +commercial licenses from The Qt Company. Alternatively, +they are available under GNU Lesser General Public License v3.0, +or GNU General Public License v3.0, or +GNU General Public License v2.0. + +The Chromium part contains code available under various +licenses, with the most restrictive license being the +\e{GNU Lesser General Public License v2.1} (LGPL 2.1). +For a full list, see \l{Third-Party Licenses} below. + +\section1 Complying with LGPL 2.1 + +The Qt Company allows commercial customers to +distribute the source code of the \QWE module alongside the +\QWE binaries, and allows recipients to customize and build +\QWE from sources. This includes building and using +such a modified \QWE with an application or system using +an otherwise commercially licensed Qt. + +The Qt Company also keeps the Qt specific parts of the \QWE +module available under the GNU Lesser General Public License v3.0, +or the GNU General Public License v3.0, or +the GNU General Public License v2.0, even if WebEngine is released +as part of a commercial-only Long-Term Support release (LTS, see +also \l{Long-Term Support releases}). + +\section1 Third-Party Licenses + +Third party licenses included in the sources as part of Chromium +are found below. + +\note Any GPL licenses listed below are only used to access Linux system +resources. The \QWE libraries and plugins does not link to nor distribute +GPL binary code, and it does not affect users of \QWE. +*/ + +/*! +\page qtwebengine-3rdparty-chromium-global.html +\attribution +\ingroup qtwebengine-licensing +\title Chromium License +\brief BSD + +The Google-authored portion of Chromium is released under a BSD license: + +\quotefile ../../../3rdparty/chromium/LICENSE +*/ diff --git a/src/core/doc/src/qwebenginehistory_lgpl.qdoc b/src/core/doc/src/qwebenginehistory_lgpl.qdoc new file mode 100644 index 000000000..f61bb3b85 --- /dev/null +++ b/src/core/doc/src/qwebenginehistory_lgpl.qdoc @@ -0,0 +1,272 @@ +// Copyright (C) 2015 The Qt Company Ltd. +// Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +// The documentation in this file was imported from QtWebKit and is thus constrained +// by its LGPL license. Documentation written from scratch for new methods should be +// placed inline in the code as usual. + +/*! + \class QWebEngineHistoryItem + \brief The QWebEngineHistoryItem class represents one item in the history of a web engine page. + \since 5.4 + \inmodule QtWebEngineCore + + Each web engine history item represents an entry in the history stack of a web page, + containing information about the page, its location, and the time when it was last visited. + + \sa QWebEngineHistory, QWebEnginePage::history() +*/ + +/*! + \fn QWebEngineHistoryItem::QWebEngineHistoryItem(const QWebEngineHistoryItem &other) + Constructs a history item from \a other. The new item and \a other + will share their data, and modifying either this item or \a other will + modify both instances. +*/ + +/*! + \fn QWebEngineHistoryItem &QWebEngineHistoryItem::operator=(const QWebEngineHistoryItem &other) + Assigns the \a other history item to this. This item and \a other + will share their data, and modifying either this item or \a other will + modify both instances. +*/ + +/*! + \fn QWebEngineHistoryItem::~QWebEngineHistoryItem() + Destroys the history item. +*/ + +/*! + \fn QUrl QWebEngineHistoryItem::originalUrl() const + Returns the original URL associated with the history item. + + \sa url() +*/ + +/*! + \fn QUrl QWebEngineHistoryItem::url() const + Returns the URL associated with the history item. + + \sa originalUrl(), title(), lastVisited() +*/ + +/*! + \fn QString QWebEngineHistoryItem::title() const + Returns the title of the page associated with the history item. + + \sa url(), lastVisited() +*/ + +/*! + \fn QDateTime QWebEngineHistoryItem::lastVisited() const + Returns the date and time when the page associated with the item was last visited. + + \sa title(), url() +*/ + +/*! + \fn bool QWebEngineHistoryItem::isValid() const + Returns whether this is a valid history item. +*/ + +/*! + \class QWebEngineHistoryModel + \inmodule QtWebEngineCore + \since 6.2 + + \brief A data model that represents the history of a web engine page. + + The QWebEngineHistoryModel type exposes the \e title, \e url, \e icon, and \e offset roles. + The \e title, \e url and \e icon specify the title, URL, and favicon of the visited page. + The \e offset specifies the position of the page in respect to the current page (0). + A positive number indicates that the page was visited after the current page, whereas a + negative number indicates that the page was visited before the current page. + + This type is uncreatable, but it can be accessed by using the QWebEngineHistory::itemsModel, + QWebEngineHistory::backItemsModel, QWebEngineHistory::forwardItemsModel methods. + + \sa QWebEngineHistory +*/ + +/*! + \enum QWebEngineHistoryModel::Roles + + This enum describes specific roles, which history data model supports. + + \value UrlRole URL of the visited page + \value TitleRole Title of the visited page + \value OffsetRole The offset of the page in respect to the current page (0) + \value IconUrlRole Favicon of the visited page +*/ + +/*! + \class QWebEngineHistory + \brief The QWebEngineHistory class represents the history of a web engine page. + \since 5.4 + \inmodule QtWebEngineCore + + Each web engine page contains a history of visited pages that can be accessed + by QWebEnginePage::history(). + + The history uses the concept of a \e{current item}, dividing the pages visited + into those that can be visited by navigating \e back and \e forward using the + back() and forward() functions. The current item can be obtained by calling + currentItem(), and an arbitrary item in the history can be made the current + item by passing it to goToItem(). + + A list of items describing the pages that can be visited by going back can be + obtained by calling the backItems() function; similarly, items describing the + pages ahead of the current page can be obtained with the forwardItems() function. + The total list of items is obtained with the items() function. + + Also, the following QWebEngineHistoryModel data model objects are provided: + + \list + \li \c backItemsModel(), which contains the URLs of visited pages. + \li \c forwardItemsModel(), which contains the URLs of the pages that were visited after visiting + the current page. + \li \c itemsModel(), which contains the URLs of the back and forward items, as well as the URL of + the current page. + \endlist + + Just as with containers, functions are available to examine the history in terms + of a list. Arbitrary items in the history can be obtained with itemAt(), the total + number of items is given by count(), and the history can be cleared with the + clear() function. + + QWebEngineHistory's state can be saved to a QDataStream using the >> operator and loaded + by using the << operator. + + \sa QWebEngineHistoryItem, QWebEnginePage +*/ + +/*! + \fn void QWebEngineHistory::clear() + Clears the history. + + \sa count(), items() +*/ + +/*! + \fn QList<QWebEngineHistoryItem> QWebEngineHistory::items() const + Returns a list of all items currently in the history. + + \sa count(), clear() +*/ + +/*! + \fn QList<QWebEngineHistoryItem> QWebEngineHistory::backItems(int maxItems) const + Returns the list of items in the backwards history list. + At most \a maxItems entries are returned. + + \sa forwardItems() +*/ + +/*! + \fn QList<QWebEngineHistoryItem> QWebEngineHistory::forwardItems(int maxItems) const + Returns the list of items in the forward history list. + At most \a maxItems entries are returned. + + \sa backItems() +*/ + +/*! + \fn QWebEngineHistoryModel *QWebEngineHistory::itemsModel() const + Returns the data model, which represents URLs of back items, forward items, + and the current item in the history. +*/ + +/*! + \fn QWebEngineHistoryModel *QWebEngineHistory::backItemsModel() const + Return the data model, which represents URLs of visited pages. +*/ + +/*! + \fn QWebEngineHistoryModel *QWebEngineHistory::forwardItemsModel() const + Return the data model, which represents URLs of the pages + that were visited after visiting the current page. +*/ + +/*! + \fn bool QWebEngineHistory::canGoBack() const + Returns \c true if there is an item preceding the current item in the history; + otherwise returns \c false. + + \sa canGoForward() +*/ + +/*! + \fn bool QWebEngineHistory::canGoForward() const + Returns \c true if we have an item to go forward to; otherwise returns \c false. + + \sa canGoBack() +*/ + +/*! + \fn void QWebEngineHistory::back() + Sets the current item to be the previous item in the history and goes to the + corresponding page; that is, goes back one history item. + + \sa forward(), goToItem() +*/ + +/*! + \fn void QWebEngineHistory::forward() + Sets the current item to be the next item in the history and goes to the + corresponding page; that is, goes forward one history item. + + \sa back(), goToItem() +*/ + +/*! + \fn void QWebEngineHistory::goToItem(const QWebEngineHistoryItem &item) + Sets the current item to be the specified \a item in the history and goes to the page. + + \sa back(), forward() +*/ + +/*! + \fn QWebEngineHistoryItem QWebEngineHistory::backItem() const + Returns the item before the current item in the history. +*/ + +/*! + \fn QWebEngineHistoryItem QWebEngineHistory::currentItem() const + Returns the current item in the history. +*/ + +/*! + \fn QWebEngineHistoryItem QWebEngineHistory::forwardItem() const + Returns the item after the current item in the history. +*/ + +/*! + \fn int QWebEngineHistory::currentItemIndex() const + Returns the index of the current item in history. +*/ + +/*! + \fn QWebEngineHistoryItem QWebEngineHistory::itemAt(int i) const + Returns the item at index \a i in the history. +*/ + +/*! + \fn int QWebEngineHistory::count() const + Returns the total number of items in the history. +*/ + +/*! + \fn QDataStream& operator<<(QDataStream& stream, const QWebEngineHistory& history) + \relates QWebEngineHistory + + Saves the web engine history \a history into \a stream. +*/ + + +/*! + \fn QDataStream& operator>>(QDataStream& stream, QWebEngineHistory& history) + \relates QWebEngineHistory + + Loads the web engine history from \a stream into \a history. +*/ diff --git a/src/core/doc/src/qwebenginepage_lgpl.qdoc b/src/core/doc/src/qwebenginepage_lgpl.qdoc new file mode 100644 index 000000000..630ea507e --- /dev/null +++ b/src/core/doc/src/qwebenginepage_lgpl.qdoc @@ -0,0 +1,864 @@ +// Copyright (C) 2019 The Qt Company Ltd. +// Copyright (C) 2008, 2009, 2012 Nokia Corporation and/or its subsidiary(-ies) +// Copyright (C) 2007 Staikos Computing Services Inc. +// Copyright (C) 2007 Apple Inc. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +// The documentation in this file was imported from QtWebKit and is thus constrained +// by its LGPL license. Documentation written from scratch for new methods should be +// placed inline in the code as usual. + +/*! + \class QWebEnginePage + \brief The QWebEnginePage class provides an object to view and edit web documents. + \since 5.4 + \inmodule QtWebEngineCore + + A \e {web engine page} holds the contents of an HTML document, the history of navigated + links, and actions. + + QWebEnginePage's API is very similar to QWebEngineView, as you are still provided with + common functions like action() (known as + \l{QWebEngineView::pageAction()}{pageAction}() in QWebEngineView), triggerAction(), + and findText(). + + A page can be loaded using load() or setUrl(). Alternatively, if you have + the HTML content readily available, you can use setHtml(). The GET method is + always used to load URLs. + + The QWebEnginePage class also offers methods to retrieve both the URL currently + loaded by the page (see url()) as well as the URL originally requested + to be loaded (see requestedUrl()). These methods make possible the retrieval + of the URL before and after a DNS resolution or a redirection occurs during + the load process. The requestedUrl() also matches to the URL added to the + page history (\l{QWebEngineHistory}) if load is successful. + + The title of an HTML page can be accessed with the title() property. + Additionally, a page may also specify an icon, which can be accessed + using the icon() or its URL using the iconUrl() property. + If the title or the icon changes, the corresponding titleChanged(), iconChanged() + and iconUrlChanged() signals will be emitted. + The zoomFactor() property enables zooming the contents of the web page by a + scale factor. + + The loadStarted() signal is emitted when the page begins to load, whereas the loadProgress() + signal is emitted whenever an element of the web page completes loading, such as an embedded + image or a script. The loadFinished() signal is emitted when the page contents + have been loaded completely, independent of script execution or page rendering. + Its argument, either \c true or \c false, indicates whether or not the load + operation succeeded. + + An HTML document is loaded in a \e {main frame} within the web page. If it references + \e {child frames} (as defined by the \c <frame> or \c <iframe> elements), they are considered + part of the content. Child frames are individually accessible only through JavaScript. + + Web sites define \e {security origin} for safely accessing each other's resources for + client-side scripting or databases. An origin consist of a host name, a scheme, and a port + number. For example, the sites \c http://www.example.com/my/page.html and + \c http://www.example.com/my/overview.html are allowed to share the same database or access + each other's documents when used in HTML frame sets and JavaScript. At the same time, + \c http://www.malicious.com/evil.html is prevented from accessing the resources of + \c http://www.example.com/, because they are of a different security origin. + By default, local schemes like \c file:// and \c qrc:// are considered to be in the same + security origin, and can access each other's resources. Local resources are by default + restricted from accessing remote content, which means that \c file:// will not be able to + access \c http://domain.com/foo.html. + + Scripts can be executed on the web page by using runJavaScript(), either in the main + JavaScript \e world, along with the rest of the JavaScript coming from the web contents, or in + their own isolated world. While the DOM of the page can be accessed from any world, JavaScript + variables of a function defined in one world are not accessible from a different one. + QWebEngineScript::ScriptWorldId provides some predefined IDs for this purpose. Using the + \c runJavaScript() version without the world ID is the same as running the script in the + \c MainWorld. + + The \l {QWebEngineSettings::FocusOnNavigationEnabled} {FocusOnNavigationEnabled} setting can be + used to make the view associated with the page automatically receive focus when a navigation + operation occurs (like loading or reloading a page or navigating through history). +*/ + +/*! + \enum QWebEnginePage::FindFlag + + This enum describes the options available to the findText() function. The options + can be OR-ed together from the following list: + + \value FindBackward Searches backwards instead of forwards. + \value FindCaseSensitively By default findText() works case insensitive. Specifying this option + changes the behavior to a case sensitive find operation. +*/ + +/*! + \enum QWebEnginePage::WebAction + + This enum describes the types of action which can be performed on the web page. + + Actions only have an effect when they are applicable. + + The availability of actions can be be determined by checking + \l{QAction::}{isEnabled()} on the action returned by action(). + + \value NoWebAction No action is triggered. + \value Back Navigate back in the history of navigated links. + \value Forward Navigate forward in the history of navigated links. + \value Stop Stop loading the current page. + \value Reload Reload the current page. + \value ReloadAndBypassCache Reload the current page, but do not use any local cache. + \value Cut Cut the content currently selected into the clipboard. + \value Copy Copy the content currently selected into the clipboard. + \value Paste Paste content from the clipboard. + \value Undo Undo the last editing action. + \value Redo Redo the last editing action. + \value SelectAll Select all content. This action is only enabled when the page's content is focused. + The focus can be forced by the JavaScript \c{window.focus()} call, or the + \l{QWebEngineSettings::FocusOnNavigationEnabled} {FocusOnNavigationEnabled} setting + should be enabled to get automatic focus. + \value PasteAndMatchStyle Paste content from the clipboard with current style. + + \value [since 5.6] OpenLinkInThisWindow Open the current link in the current window. + \value [since 5.6] OpenLinkInNewWindow Open the current link in a new window. Requires implementation of + \l createWindow() or \l newWindowRequested(). + \value [since 5.6] OpenLinkInNewTab Open the current link in a new tab. Requires implementation of + \l createWindow() or \l newWindowRequested(). + \value [since 5.7] OpenLinkInNewBackgroundTab Open the current link in a new background tab. Requires + implementation of \l createWindow() or \l newWindowRequested(). + \value [since 5.6] CopyLinkToClipboard Copy the current link to the clipboard. + + \value [since 5.6] CopyImageToClipboard Copy the clicked image to the clipboard. + \value [since 5.6] CopyImageUrlToClipboard Copy the clicked image's URL to the clipboard. + \value [since 5.6] CopyMediaUrlToClipboard Copy the hovered audio or video's URL to the clipboard. + \value [since 5.6] ToggleMediaControls Toggle between showing and hiding the controls for the hovered audio + or video element. + \value [since 5.6] ToggleMediaLoop Toggle whether the hovered audio or video should loop on completetion or + not. + \value [since 5.6] ToggleMediaPlayPause Toggle the play/pause state of the hovered audio or video element. + \value [since 5.6] ToggleMediaMute Mute or unmute the hovered audio or video element. + \value [since 5.6] DownloadLinkToDisk Download the current link to the disk. Requires a slot for + \l{QWebEngineProfile::}{downloadRequested()}. + \value [since 5.6] DownloadImageToDisk Download the highlighted image to the disk. Requires a slot for + \l{QWebEngineProfile::}{downloadRequested()}. + \value [since 5.6] DownloadMediaToDisk Download the hovered audio or video to the disk. Requires a slot for + \l{QWebEngineProfile::}{downloadRequested()}. + + \value [since 5.6] InspectElement Trigger any attached Web Inspector to inspect the highlighed element. + \value [since 5.6] ExitFullScreen Exit the fullscreen mode. + \value [since 5.6] RequestClose Request to close the web page. If defined, the \c{window.onbeforeunload} + handler is run, and the user can confirm or reject to close the page. If the close + request is confirmed, \c windowCloseRequested is emitted. + \value [since 5.7] Unselect Clear the current selection. + \value [since 5.7] SavePage Save the current page to disk. MHTML is the default format that is used to store + the web page on disk. Requires a slot for \l{QWebEngineProfile::}{downloadRequested()}. + \value [since 5.8] ViewSource Show the source of the current page in a new tab. Requires implementation of + \l createWindow() or \l newWindowRequested(). + + \value [since 5.10] ToggleBold + Toggles boldness for the selection or at the cursor position. + Requires \c contenteditable="true". + \value [since 5.10] ToggleItalic + Toggles italics for the selection or at the cursor position. + Requires \c contenteditable="true". + \value [since 5.10] ToggleUnderline + Toggles underlining of the selection or at the cursor position. + Requires \c contenteditable="true". + \value [since 5.10] ToggleStrikethrough + Toggles striking through the selection or at the cursor position. + Requires \c contenteditable="true". + + \value [since 5.10] AlignLeft + Aligns the lines containing the selection or the cursor to the left. + Requires \c contenteditable="true". + \value [since 5.10] AlignCenter + Aligns the lines containing the selection or the cursor at the center. + Requires \c contenteditable="true". + \value [since 5.10] AlignRight + Aligns the lines containing the selection or the cursor to the right. + Requires \c contenteditable="true". + \value [since 5.10] AlignJustified + Stretches the lines containing the selection or the cursor so that each + line has equal width. + Requires \c contenteditable="true". + \value [since 5.10] Indent + Indents the lines containing the selection or the cursor. + Requires \c contenteditable="true". + \value [since 5.10] Outdent + Outdents the lines containing the selection or the cursor. + Requires \c contenteditable="true". + + \value [since 5.10] InsertOrderedList + Inserts an ordered list at the current cursor position, deleting the current selection. + Requires \c contenteditable="true". + \value [since 5.10] InsertUnorderedList + Inserts an unordered list at the current cursor position, + deleting the current selection. + Requires \c contenteditable="true". + \value [since 6.6] ChangeTextDirectionLTR + Changes text direction to left-to-right in the focused input element. + \value [since 6.6] ChangeTextDirectionRTL + Changes text direction to right-to-left in the focused input element. + \omitvalue WebActionCount + +*/ + +/*! + \enum QWebEnginePage::WebWindowType + + This enum describes the types of window that can be created by the createWindow() function: + + \value WebBrowserWindow + A complete web browser window. + \value WebBrowserTab + A web browser tab. + \value WebDialog + A window without decoration. + \value [since 5.7] WebBrowserBackgroundTab + A web browser tab without hiding the current visible WebEngineView. +*/ + +/*! + \enum QWebEnginePage::JavaScriptConsoleMessageLevel + + This enum describes the different severity levels a JavaScript console message can have: + + \value InfoMessageLevel The message is purely informative and can safely be ignored. + \value WarningMessageLevel The message informs about unexpected behavior or errors that may + need attention. + \value ErrorMessageLevel The message indicates there has been an error. +*/ + +/*! + \enum QWebEnginePage::FileSelectionMode + + This enum indicates whether the implementation of the chooseFiles() function should + return only one file or may return multiple files: + + \value FileSelectOpen + Return only one file name. + \value FileSelectOpenMultiple + Return multiple file names. + \value FileSelectUploadFolder + Allows users to specify a single existing folder for upload. + \value FileSelectSave + Specify a new file to be created. + + \sa chooseFiles() +*/ + +/*! + \enum QWebEnginePage::PermissionPolicy + \deprecated [6.8] Replaced by QWebEnginePermission::State. + + This enum describes the permission policies that the user may set for data or device access: + + \value PermissionUnknown It is unknown whether the user grants or denies permission. + \value PermissionGrantedByUser The user has granted permission. + \value PermissionDeniedByUser The user has denied permission. + + \sa featurePermissionRequested(), featurePermissionRequestCanceled(), setFeaturePermission(), Feature +*/ + +/*! + \enum QWebEnginePage::NavigationType + + This enum describes the type of a navigation request: + + \value NavigationTypeLinkClicked The navigation request resulted from a clicked link. + \value NavigationTypeTyped The navigation request resulted from an explicitly loaded URL. + \value NavigationTypeFormSubmitted The navigation request resulted from a form submission. + \value NavigationTypeBackForward The navigation request resulted from a back or forward action. + \value NavigationTypeReload The navigation request resulted from a reload action. + \value [since 5.14] NavigationTypeRedirect The navigation request resulted from a content or server controlled redirect. This also includes automatic reloads. + \value NavigationTypeOther The navigation request was triggered by other means not covered by the above. + + \sa acceptNavigationRequest() +*/ + +/*! + \enum QWebEnginePage::Feature + \deprecated [6.8] Replaced by QWebEnginePermission::Feature. + + This enum describes the platform feature access categories that the user may be asked to grant + or deny access to: + + \value Notifications + Web notifications for the end-user. + \value Geolocation + Location hardware or service. + \value MediaAudioCapture + Audio capture devices, such as microphones. + \value MediaVideoCapture + Video devices, such as cameras. + \value MediaAudioVideoCapture + Both audio and video capture devices. + \value MouseLock + Mouse locking, which locks the mouse pointer to the web view and is typically used in + games. + \value [since 5.10] DesktopVideoCapture + Video output capture, that is, the capture of the user's display, + for screen sharing purposes for example. + \value [since 5.10] DesktopAudioVideoCapture + Both audio and video output capture. + \value [since 6.8] ClipboardReadWrite + Read and write access for the clipboard. If both \l{QWebEngineSettings::JavascriptCanPaste} + {JavascriptCanPaste} and \l{QWebEngineSettings::JavascriptCanAccessClipboard} + {JavascriptCanAccessClipboard} settings are enabled, this permission will always be granted + automatically and no feature requests will be made. + \value [since 6.8] LocalFontsAccess + Access to the fonts installed on the user's machine. Only available on desktop platforms. + + \sa featurePermissionRequested(), featurePermissionRequestCanceled(), setFeaturePermission(), PermissionPolicy + +*/ + +/*! + \fn QWebEnginePage::QWebEnginePage(QObject *parent) + Constructs an empty QWebEnginePage with the parent \a parent. +*/ + +/*! + \fn QWebEnginePage::~QWebEnginePage() + Destroys the web page. +*/ + +/*! + \fn QWebEngineHistory *QWebEnginePage::history() const + Returns a pointer to the view's history of navigated web pages. +*/ + +/*! + \fn void QWebEnginePage::javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level, const QString& message, int lineNumber, const QString& sourceID) + This function is called when a JavaScript program tries to print the \a message to the web + browser's console. + + For example, in case of evaluation errors the source URL may be provided in \a sourceID as well + as the \a lineNumber. + + \a level indicates the severity of the event that triggered the message. That is, whether it + was triggered by an error or a less severe event. + + Since Qt 5.6, the default implementation logs the messages in a \c js + \l{QLoggingCategory}{logging category}. + + \sa{Console Logging} +*/ + +/*! + \fn bool QWebEnginePage::acceptNavigationRequest(const QUrl &url, NavigationType type, bool isMainFrame) + \since 5.5 + This function is called upon receiving a request to navigate to the specified \a url by means of + the specified navigation type \a type. \a isMainFrame indicates whether the request corresponds + to the main frame or a child frame. If the function returns \c true, the navigation request is + accepted and \c url is loaded. The default implementation accepts all navigation requests. + + Navigation requests can be delegated to the Qt application instead of having the HTML handler + engine process them by overloading this function. This is necessary when an HTML document is + used as part of the user interface, and not to display external data, for example, when + displaying a list of results. + + \note This function is not called for fragment navigation on the same page. Such navigation, + for example, happens by clicking a link to a '#fragment' within the page. It does not trigger + a load to a different document, even though it changes page's url and adds history entry. + It only serves as a shortcut to scroll within the page. Hence, no delegation of this navigation + type is expected to happen. + + \note The loading process is started and the loadStarted() signal is emitted + \e before the request is accepted or rejected. Therefore, a loadFinished() + signal that returns \c false is to be expected even after delegating the + request. + + \note When using setHtml or setContent with relative links, make + sure to specify a base url, otherwise the links will be considered + invalid and no navigation requests will be emitted. + + The \l{QWebEngineUrlRequestInterceptor} class offers further options for intercepting and + manipulating requests. +*/ + +/*! + \fn void QWebEnginePage::javaScriptAlert(const QUrl &securityOrigin, const QString& msg) + This function is called whenever a JavaScript program running in a frame affiliated with + \a securityOrigin calls the \c alert() function with the message \a msg. + + The default implementation shows the message, \a msg, with QMessageBox::information. +*/ + +/*! + \fn bool QWebEnginePage::javaScriptConfirm(const QUrl &securityOrigin, const QString& msg) + This function is called whenever a JavaScript program running in a frame affiliated with + \a securityOrigin calls the \c confirm() function with the message \a msg. Returns \c true + if the user confirms the message; otherwise returns \c false. + + It is also called when the \c onbeforeunload handler is requesting a confirmation before + leaving a page. + + The default implementation executes the query using QMessageBox::information with QMessageBox::Ok and QMessageBox::Cancel buttons. +*/ + +/*! + \fn bool QWebEnginePage::javaScriptPrompt(const QUrl &securityOrigin, const QString& msg, const QString& defaultValue, QString* result) + This function is called whenever a JavaScript program running in a frame affiliated with \a securityOrigin tries to prompt the user for input. + The program may provide an optional message, \a msg, as well as a default value for the input in \a defaultValue. + + If the prompt was cancelled by the user, the implementation should return \c false; otherwise the + result should be written to \a result and \c true should be returned. If the prompt was not + cancelled by the user, the implementation should return \c true and the result string must not + be null. + + The default implementation uses QInputDialog::getText(). +*/ + +/*! + \fn QWebEnginePage *QWebEnginePage::createWindow(WebWindowType type) + This function is called to create a new window of the specified \a type. For example, when a + JavaScript program requests to open a document in a new window. + + If the new window can be created, the new window's QWebEnginePage is returned; otherwise a null pointer is returned. + + If the view associated with the web page is a QWebEngineView object, then the default implementation forwards + the request to QWebEngineView::createWindow(); otherwise it returns a null pointer. + + If this call is not implemented or does not return a new page, \l newWindowRequested() + is emitted to handle the request. + + \note In the cases when the window creation is being triggered by JavaScript, apart from + reimplementing this method the application must also set + QWebEngineSettings::JavascriptCanOpenWindows to \c true in order for the method to get called. + + \sa QWebEngineView::createWindow(), newWindowRequested() +*/ + +/*! + \fn void QWebEnginePage::triggerAction(WebAction action, bool checked = false) + This function can be called to trigger the specified \a action. + It is also called by \QWE if the user triggers the action, for example + through a context menu item. + + If \a action is a checkable action, then \a checked specifies whether the action + is toggled or not. + + \sa action() +*/ + +/*! + \property QWebEnginePage::hasSelection + \brief Whether this page contains selected content or not. + + \sa selectionChanged() +*/ + +/*! + \property QWebEnginePage::selectedText + \brief The text currently selected. + + By default, this property contains an empty string. + + \sa selectionChanged() +*/ + +/*! + \fn QAction *QWebEnginePage::action(WebAction action) const + Returns a QAction for the specified WebAction \a action. + + The action is owned by the QWebEnginePage but you can customize the look by + changing its properties. + + \l{QWebEnginePage::action(WebAction action)} does not have a default styled icon. + Use \l{QWebEngineView::pageAction()} to have an action with a default styled icon. + + QWebEnginePage also takes care of implementing the action, so that upon + triggering the corresponding action is performed on the page. + + \sa triggerAction() +*/ + +/*! + \fn void QWebEnginePage::findText(const QString &subString, QWebEnginePage::FindFlags options = {}, const std::function<void(const QWebEngineFindTextResult &)> &resultCallback = std::function<void(const QWebEngineFindTextResult &)>) + Finds the specified string, \a subString, in the page, using the given \a options. + The findTextFinished() signal is emitted when a string search is completed. + + To clear the search highlight, just pass an empty string. + + The \a resultCallback must take a QWebEngineFindTextResult parameter. + + \warning We guarantee that the callback (\a resultCallback) is always called, but it might be done + during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid + value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it. + + For example: + \snippet qtwebengine_qwebenginepage_snippet.cpp 0 + + \sa findTextFinished() +*/ + +/*! + \fn QWebEngineSettings *QWebEnginePage::settings() const + Returns a pointer to the page's settings object. +*/ + +/*! + \fn void QWebEnginePage::certificateError(const QWebEngineCertificateError & certificateError) + This signal is emitted when an invalid certificate error is raised while loading a given request. + + The \a certificateError parameter contains information about the certificate and details of the error, + it also provides the way to ignore the error and complete the request or stop loading + the request. + + \sa QWebEngineCertificateError +*/ + +/*! + \fn QString QWebEnginePage::chooseFiles(FileSelectionMode mode, const QStringList& oldFiles, const QStringList& acceptedMimeTypes) + This function is called when the web content requests a file name, for example + as a result of the user clicking on a file upload button in an HTML form. + + \a mode indicates whether only one file or multiple files are expected to be returned. + + A suggested filename may be provided as the first entry of \a oldFiles. \a acceptedMimeTypes is ignored by the default implementation, + but might be used by overrides. +*/ + +/*! + \fn void QWebEnginePage::loadStarted() + + This signal is emitted when a page starts loading content. + + \sa loadFinished(), acceptNavigationRequest() +*/ + +/*! + \fn void QWebEnginePage::loadProgress(int progress) + + This signal is emitted when the global progress status changes. + The current value is provided by \a progress and scales from 0 to 100, + which is the default range of QProgressBar. + It accumulates changes from all the child frames. + +*/ + +/*! + \fn void QWebEnginePage::loadFinished(bool ok) + + This signal is emitted when the page finishes loading content. This signal + is independent of script execution or page rendering. + \a ok will indicate whether the load was successful or any error occurred. + + \note Navigation requests can be delegated to the Qt application instead + of having the HTML handler engine process them by overloading the + acceptNavigationRequest() function. Because the loading process is started + and the loadStarted() signal is emitted \e before the request is accepted + or rejected, a \c loadFinished() signal that returns \c false is to be + expected even after delegating the request. + + \sa loadStarted(), acceptNavigationRequest() +*/ + +/*! + \fn void QWebEnginePage::selectionChanged() + + This signal is emitted whenever the selection changes, either interactively + or programmatically. For example, by calling triggerAction() with a selection action. + + \note When using the mouse to select text by left-clicking and dragging, the signal will be + emitted for each new character selected, and not upon releasing the left mouse button. + + \sa selectedText() +*/ + +/*! + \fn void QWebEnginePage::linkHovered(const QString &url) + + This signal is emitted when the mouse hovers over a link. + \a url contains the target URL of the link. +*/ + +/*! + + \fn void QWebEnginePage::authenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator) + + This signal is emitted when access to \a requestUrl requires authentication. + \a authenticator should be used to pass the user name and password for the connection. +*/ + +/*! + \fn void QWebEnginePage::proxyAuthenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator, const QString &proxyHost) + + This signal is emitted when access to \a requestUrl via \a proxyHost requires authentication for the proxy. + \a authenticator should be used to pass the user name and password for the connection. + +*/ + +/*! + \fn void QWebEnginePage::geometryChangeRequested(const QRect& geom) + + This signal is emitted whenever the document wants to change the position and size of the + page to \a geom. This can happen for example through JavaScript. + + \note \l{QWindow::}{setGeometry()} expects a size excluding the window + decoration, while \a geom includes it. You have to remove the size of the frame margins + from \a geom to handle this signal correctly. + + \code + window->setGeometry(geom.marginsRemoved(window->frameMargins())); + \endcode +*/ + +/*! + \fn void QWebEnginePage::windowCloseRequested() + + This signal is emitted whenever the page requests the web browser window to be closed, + for example through the JavaScript \c{window.close()} call. + + \sa RequestClose +*/ + +/*! + \fn void QWebEnginePage::toHtml(const std::function<void(const QString &)> &resultCallback) const + Asynchronous method to retrieve the page's content as HTML, enclosed in HTML and BODY tags. + Upon successful completion, \a resultCallback is called with the page's content. + + \note \a resultCallback can be any of a function pointer, a functor or a lambda, and it is expected to take a QString parameter. + + \warning We guarantee that the callback (\a resultCallback) is always called, but it might be done + during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid + value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it. + + \sa setHtml(), toPlainText() +*/ + +/*! + \fn void QWebEnginePage::toPlainText(const std::function<void(const QString &)> &resultCallback) const + Asynchronous method to retrieve the page's content converted to plain text, completely stripped of all + HTML formatting. + Upon successful completion, \a resultCallback is called with the page's content. + + \note \a resultCallback can be any of a function pointer, a functor or a lambda, and it is expected to take a QString parameter. + + \warning We guarantee that the callback (\a resultCallback) is always called, but it might be done + during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid + value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it. + + \sa toHtml() +*/ + +/*! + \property QWebEnginePage::title + \brief The title of the page as defined by the HTML \c <title> element. + + If the page has no \c <title> element, then the URL is used instead. For \c + file:// URLs only the filename is used and not the full path. + + By default, before any content has been loaded, this property contains an + empty string. + + \sa titleChanged() +*/ + +/*! + \property QWebEnginePage::url + \brief The URL of the page currently viewed. + + Setting this property clears the view and loads the URL. + + By default, this property contains an empty, invalid URL. + + \sa urlChanged() +*/ + +/*! + \property QWebEnginePage::requestedUrl + \brief The URL that was originally requested to be loaded by the page + that is currently viewed. + + \note The URL may differ from the one returned by url(), which is the actual + URL that results from DNS resolution or redirection. + + \sa url(), setUrl() +*/ + +/*! + \fn void QWebEnginePage::load(const QUrl &url) + Loads \a url into this page. + + \note The view remains the same until enough data has arrived to display the new URL. + + \sa setUrl(), setHtml(), setContent() +*/ + +/*! + \fn void QWebEnginePage::setHtml(const QString &html, const QUrl &baseUrl) + Sets the content of this page to \a html. \a baseUrl is optional and used to resolve relative + URLs in the document, such as referenced images or stylesheets. + + The \a html is loaded immediately; external objects are loaded asynchronously. + + If a script in the \a html runs longer than the default script timeout (currently 10 seconds), + for example due to being blocked by a modal JavaScript alert dialog, this method will return + as soon as possible after the timeout and any subsequent \a html will be loaded asynchronously. + + When using this method, the web engine assumes that external resources, such as JavaScript programs or style + sheets, are encoded in UTF-8 unless otherwise specified. For example, the encoding of an external + script can be specified through the charset attribute of the HTML script tag. It is also possible + for the encoding to be specified by the web server. + + This is a convenience function equivalent to setContent(html, "text/html", baseUrl). + + \note This method will not affect session or global history for the page. + + \warning This function works only for HTML, for other mime types (such as XHTML and SVG) + setContent() should be used instead. + + \warning The content will be percent encoded before being sent to the renderer via IPC. + This may increase its size. The maximum size of the percent encoded content is + 2 megabytes minus 30 bytes. + + \sa toHtml(), setContent(), load() +*/ + +/*! + \fn void QWebEnginePage::setContent(const QByteArray &data, const QString &mimeType, const QUrl &baseUrl) + Sets the content of the web page to \a data. If the \a mimeType argument + is empty, it is assumed that the content is \c{text/plain,charset=US-ASCII}. + + External objects referenced in the content are located relative to \a baseUrl. + For external objects with relative URLs to be loaded, \c baseUrl cannot be empty. + + The \a data is loaded immediately; external objects are loaded asynchronously. + + \note This method will not affect session or global history for the page. + + \warning The content will be percent encoded before being sent to the renderer via IPC. + This may increase its size. The maximum size of the percent encoded content is + 2 megabytes minus 6 bytes plus the length of the mime type string. + + \sa toHtml(), setHtml() +*/ + +/*! + \property QWebEnginePage::zoomFactor + \brief The zoom factor for the page content. + + Valid values are within the range from \c{0.25} to \c{5.0}. The default factor is \c{1.0}. + + \sa zoomFactorChanged() +*/ + +/*! + \fn void QWebEnginePage::runJavaScript(const QString &scriptSource, quint32 worldId = 0, const std::function<void(const QVariant &)> &resultCallback = {}) + \fn void QWebEnginePage::runJavaScript(const QString &scriptSource, const std::function<void(const QVariant &)> &resultCallback) + \since 5.7 + + Runs the JavaScript code contained in \a scriptSource without checking + whether the DOM of the page has been constructed. If you need more + control over how the script is run, consider using \l scripts() instead. + + To avoid conflicts with other scripts executed on the page, the world in + which the script is run is specified by \a worldId. The world ID values are + the same as provided by QWebEngineScript::ScriptWorldId, and between \c 0 + and \c 256. If you leave out the \c world ID, the script is run in the + \c MainWorld. + + When the script has been executed, \a resultCallback is called with the result of the last + executed statement. \c resultCallback can be any of a function pointer, a functor or a lambda, + and it is expected to take a QVariant parameter. For example: + + \code + page.runJavaScript("document.title", [](const QVariant &v) { qDebug() << v.toString(); }); + \endcode + + Only plain data can be returned from JavaScript as the result value. + Supported data types include all of the JSON data types as well as, for + example, \c{Date} and \c{ArrayBuffer}. Unsupported data types include, for + example, \c{Function} and \c{Promise}. + + \warning Do not execute lengthy routines in the callback function, because it might block the + rendering of the web engine page. + + \warning We guarantee that the callback (\a resultCallback) is always called, but it might be done + during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid + value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it. + + \sa scripts(), QWebEngineScript::ScriptWorldId, QWebEngineFrame::runJavaScript, {Script Injection} +*/ + +/*! + \fn void QWebEnginePage::setFeaturePermission(const QUrl &securityOrigin, Feature feature, PermissionPolicy policy) + \deprecated [6.8] Use QWebEnginePermission's \l {QWebEnginePermission::grant} {grant}(), + \l {QWebEnginePermission::deny} {deny}(), and \l {QWebEnginePermission::reset} {reset}() functions instead. + + Sets the permission for the web site identified by \a securityOrigin to use \a feature to \a policy. + + \note This method is primarily for calling after a featurePermissionRequested() signal has been emitted + to trigger the feature permission response. It can also be called before a request has been emitted, + but will only set a granted permission for passive checks, mainly for Notification APIs that can check + if permission has already been granted before explicitly requesting it. + + \sa featurePermissionRequested(), featurePermissionRequestCanceled() +*/ + +/*! + \fn void QWebEnginePage::featurePermissionRequested(const QUrl &securityOrigin, Feature feature) + \deprecated [6.8] Use permissionRequested() instead. + + This signal is emitted when the web site identified by \a securityOrigin requests to make use of + the resource or device identified by \a feature. + + \sa featurePermissionRequestCanceled(), setFeaturePermission() +*/ + +/*! + \fn void QWebEnginePage::featurePermissionRequestCanceled(const QUrl &securityOrigin, Feature feature) + \deprecated [6.8] This signal is no longer emitted. + + This signal is emitted when the web site identified by \a securityOrigin cancels a previously issued + request to make use of \a feature. + + \sa featurePermissionRequested(), setFeaturePermission() + +*/ + +/*! + \fn void QWebEnginePage::permissionRequested(QWebEnginePermission permission) + \since 6.8 + + This signal is emitted when a web site requests to make use of a feature (e.g. geolocation access, + permission to send notifications). The \a permission object can queried for the requesting URL + and the \c{QWebEnginePermission::Feature} it's asking for, as well as to grant or deny permission. +*/ + +/*! + \fn void QWebEnginePage::titleChanged(const QString &title) + + This signal is emitted whenever the title of the page changes. + The \a title string specifies the new title. + + \sa title() +*/ + +/*! + \fn void QWebEnginePage::urlChanged(const QUrl &url) + + This signal is emitted with the URL of the page when the page title is + received. The new URL is specified by \a url. + + \sa url() +*/ + +/*! + \fn void QWebEnginePage::webAuthUxRequested(QWebEngineWebAuthUxRequest *request); + \since 6.7 + + This signal is emitted when a WebAuth authenticator needs user interaction + during the authentication process. These requests are handled by displaying a dialog to the user. + + The \a request contains the information and API required to complete the WebAuth UX request. + + \sa QWebEngineWebAuthUxRequest +*/ + +/*! + \fn void QWebEnginePage::zoomFactorChanged(qreal factor) + \since 6.8 + + This signal is emitted whenever the zoom \a factor for the page changes. + + \sa zoomFactor(), setZoomFactor() +*/ diff --git a/src/core/doc/src/qwebenginesettings_lgpl.qdoc b/src/core/doc/src/qwebenginesettings_lgpl.qdoc index a62abfbab..cd7ff8e8c 100644 --- a/src/core/doc/src/qwebenginesettings_lgpl.qdoc +++ b/src/core/doc/src/qwebenginesettings_lgpl.qdoc @@ -1,22 +1,6 @@ -/* - Copyright (C) 2015 The Qt Company Ltd. - Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Library General Public License for more details. - - You should have received a copy of the GNU Library General Public License - along with this library; see the file COPYING.LIB. If not, write to - the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - Boston, MA 02110-1301, USA. -*/ +// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies) +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // The documentation in this file was imported from QtWebKit and is thus constrained // by its LGPL license. Documentation written from scratch for new methods should be @@ -31,8 +15,8 @@ \inmodule QtWebEngineCore QWebEngineSettings allows configuration of browser properties, such as font sizes and - families, the location of a custom style sheet, and generic attributes, such as JavaScript - support. Individual attributes are set using the setAttribute() function. The + families, and generic attributes, such as JavaScript support. + Individual attributes are set using the setAttribute() function. The \l{QWebEngineSettings::WebAttribute}{WebAttribute} enum further describes each attribute. Each QWebEnginePage object has its own QWebEngineSettings object, which configures the @@ -56,7 +40,7 @@ \value CursiveFont \value FantasyFont \value PictographFont - (added in Qt 5.7) + (added in Qt 5.7, deprecated Qt 6.4) */ /*! @@ -89,21 +73,18 @@ Allows JavaScript programs to read from and write to the clipboard. Writing to the clipboard is always allowed if it is specifically requested by the user. See JavascriptCanPaste to also allow pasting the content of the clipboard content from - JavaScript. + JavaScript. Since unrestricted clipboard access is a potential security concern, it is + recommended that applications leave this disabled and instead respond to + \l{QWebEnginePage::ClipboardReadWrite}{ClipboardReadWrite} feature permission requests. Disabled by default. \value LinksIncludedInFocusChain Includes hyperlinks in the keyboard focus chain. Enabled by default. \value LocalStorageEnabled Enables support for the HTML 5 local storage feature. Enabled by default. \value LocalContentCanAccessRemoteUrls - Allows locally loaded documents to ignore cross-origin rules so that they can access - remote resources that would normally be blocked, because all remote resources are - considered cross-origin for a local file. Remote access that would not be blocked by - cross-origin rules is still possible when this setting is disabled (default). - Note that disabling this setting does not stop XMLHttpRequests or media elements in - local files from accessing remote content. Basically, it only stops some HTML - subresources, such as scripts, and therefore disabling this setting is not a safety - mechanism. + Allows local origin documents to access remote resources that would normally be blocked. + Disabled by default. Note DnsPrefetchEnabled below operates independently of this setting, + and can if enabled, cause remote accesses from local content. \value XSSAuditingEnabled Obsolete and has no effect. \value SpatialNavigationEnabled @@ -114,7 +95,8 @@ trying to reach towards the right and which element they probably want. Disabled by default. \value LocalContentCanAccessFileUrls - Allows locally loaded documents to access other local URLs. Enabled by default. + Allows locally loaded documents to access other local URLs. Disabling this makes QtWebEngine + behave more like Chrome and Firefox does by default. Enabled by default. \value HyperlinkAuditingEnabled Enables support for the \c ping attribute for hyperlinks. Disabled by default. \value ScrollAnimatorEnabled @@ -171,8 +153,11 @@ similar to Chrome on desktops. To overwrite the default behavior, disable this setting. (Added in Qt 5.11) \value JavascriptCanPaste - Enables JavaScript \c{execCommand("paste")}. This also requires - enabling JavascriptCanAccessClipboard. + Enables JavaScript \c{execCommand("paste")}. This also requires enabling + JavascriptCanAccessClipboard. Since unrestricted clipboard access is a potential + security concern, it is recommended that applications leave this disabled + and instead respond to \l{QWebEnginePage::ClipboardReadWrite}{ClipboardReadWrite} + feature permission requests. Disabled by default. (Added in Qt 5.11) \value WebRTCPublicInterfacesOnly Limits WebRTC to public IP addresses only. When disabled WebRTC may also use @@ -185,6 +170,16 @@ \value PdfViewerEnabled Specifies that PDF documents will be opened in the internal PDF viewer instead of being downloaded. Enabled by default. (Added in Qt 5.13) + \value NavigateOnDropEnabled Specifies that navigations can be triggered by dropping URLs on + the view. + Enabled by default. (Added in Qt 6.4) + \value ReadingFromCanvasEnabled Specifies that reading from all canvas elements is enabled. + This setting will have impact on all HTML5 canvas elements irrespective of origin, and can be disabled + to prevent canvas fingerprinting. + Enabled by default. (Added in Qt 6.6) + \value ForceDarkMode Specifies that all web contents will be rendered using a dark theme. + For more information, see \l{https://developer.chrome.com/blog/auto-dark-theme/}{Auto dark theme}. + Disabled by default. (Added in Qt 6.7) */ /*! @@ -201,11 +196,30 @@ from JavaScript) are suppressed. \value AllowAllUnknownUrlSchemes Allows all navigation requests to URLs with unknown schemes. + \omitvalue InheritedUnknownUrlSchemePolicy \sa unknownUrlSchemePolicy setUnknownUrlSchemePolicy resetUnknownUrlSchemePolicy */ /*! + \enum QWebEngineSettings::ImageAnimationPolicy + \since Qt 6.8 + + This enum describes how an image animation should be handled when the image frames + are rendered for animation. + + \value AllowImageAnimation + Allows image animation when the image frames are rendered. + \value AnimateImageOnce + Animate the image once when the image frames are rendered. + \value DisallowImageAnimation + Disallows image animation when the image frames are rendered. + \omitvalue InheritedImageAnimationPolicy + + \sa imageAnimationPolicy setImageAnimationPolicy resetImageAnimationPolicy +*/ + +/*! \fn void QWebEngineSettings::setFontSize(FontSize type, int size) Sets the font size for \a type to \a size in pixels. */ @@ -240,12 +254,6 @@ */ /*! - \fn void QWebEngineSettings::setFontFamily(FontFamily which, const QString& family) - Sets the actual font family to \a family for the specified generic family, - \a which. -*/ - -/*! \fn QString QWebEngineSettings::fontFamily(FontFamily which) const Returns the actual font family for the specified generic font family, \a which. @@ -299,3 +307,26 @@ Resets the setting of \a attribute to the value specified in the profile that the page belongs to. */ + +/*! + \fn QWebEngineSettings::ImageAnimationPolicy QWebEngineSettings::imageAnimationPolicy() const + \since Qt 6.8 + Returns the currently selected policy for handling image animation when the image frames are rendered. + Default is \l{QWebEngineSettings::AllowImageAnimation}. + \sa setImageAnimationPolicy resetImageAnimationPolicy +*/ + +/*! + \fn void QWebEngineSettings::setImageAnimationPolicy(QWebEngineSettings::ImageAnimationPolicy policy) + \since Qt 6.8 + Sets the policy for handling image animation when the image frames are rendered to \a policy. + Default is \l{QWebEngineSettings::AllowImageAnimation}. + \sa imageAnimationPolicy resetImageAnimationPolicy +*/ + +/*! + \fn void QWebEngineSettings::resetImageAnimationPolicy() + \since Qt 6.7 + Removes the policy for handling image animation. + \sa imageAnimationPolicy setImageAnimationPolicy +*/ |