diff options
Diffstat (limited to 'src/webenginequick/doc')
28 files changed, 575 insertions, 2297 deletions
diff --git a/src/webenginequick/doc/snippets/minimal/main.cpp b/src/webenginequick/doc/snippets/minimal/main.cpp new file mode 100644 index 000000000..e17493a36 --- /dev/null +++ b/src/webenginequick/doc/snippets/minimal/main.cpp @@ -0,0 +1,18 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [Minimal Example] +#include <QGuiApplication> +#include <QQmlApplicationEngine> +#include <QtWebEngineQuick/qtwebenginequickglobal.h> + +int main(int argc, char *argv[]) +{ + QCoreApplication::setAttribute(Qt::AA_ShareOpenGLContexts); + QtWebEngineQuick::initialize(); + QGuiApplication app(argc, argv); + QQmlApplicationEngine engine; + engine.load(QUrl(QStringLiteral("qrc:/main.qml"))); + return app.exec(); +} +//! [Minimal Example] diff --git a/src/webenginequick/doc/snippets/minimal/main.qml b/src/webenginequick/doc/snippets/minimal/main.qml new file mode 100644 index 000000000..87a8757df --- /dev/null +++ b/src/webenginequick/doc/snippets/minimal/main.qml @@ -0,0 +1,18 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [Minimal Example] +import QtQuick +import QtQuick.Window +import QtWebEngine + +Window { + width: 1024 + height: 750 + visible: true + WebEngineView { + anchors.fill: parent + url: "https://www.qt.io" + } +} +//! [Minimal Example] diff --git a/src/webenginequick/doc/snippets/qtwebengine_build_snippet.qdoc b/src/webenginequick/doc/snippets/qtwebengine_build_snippet.qdoc index 35bc480bb..f8fbbd669 100644 --- a/src/webenginequick/doc/snippets/qtwebengine_build_snippet.qdoc +++ b/src/webenginequick/doc/snippets/qtwebengine_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 += webengine +QT += webenginequick //! [0] - -//! [1] -#include <QtWebEngine> -//! [1] +//! [2] +find_package(Qt6 REQUIRED COMPONENTS WebEngineQuick) +target_link_libraries(target PRIVATE Qt6::WebEngineQuick) +//! [2] diff --git a/src/webenginequick/doc/snippets/qtwebengine_webengineaction.qml b/src/webenginequick/doc/snippets/qtwebengine_webengineaction.qml new file mode 100644 index 000000000..2fd5f490b --- /dev/null +++ b/src/webenginequick/doc/snippets/qtwebengine_webengineaction.qml @@ -0,0 +1,123 @@ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +import QtQuick +import QtQuick.Window +import QtWebEngine +import QtQuick.Controls +import QtQuick.Layouts + +ApplicationWindow { + id: window + visible: true + width: 800 + height: 600 + title: qsTr("WebEngineAction Example") + + header: ToolBar { + RowLayout { + anchors.fill: parent +//! [0] + ToolButton { + property int itemAction: WebEngineView.Back + text: webEngineView.action(itemAction).text + enabled: webEngineView.action(itemAction).enabled + onClicked: webEngineView.action(itemAction).trigger() + icon.name: webEngineView.action(itemAction).iconName + display: AbstractButton.TextUnderIcon + } +//! [0] + ToolButton { + property int itemAction: WebEngineView.Forward + text: webEngineView.action(itemAction).text + enabled: webEngineView.action(itemAction).enabled + onClicked: webEngineView.action(itemAction).trigger() + icon.name: webEngineView.action(itemAction).iconName + display: AbstractButton.TextUnderIcon + } + + ToolButton { + property int itemAction: webEngineView.loading ? WebEngineView.Stop : WebEngineView.Reload + text: webEngineView.action(itemAction).text + enabled: webEngineView.action(itemAction).enabled + onClicked: webEngineView.action(itemAction).trigger() + icon.name: webEngineView.action(itemAction).iconName + display: AbstractButton.TextUnderIcon + } + + TextField { + Layout.fillWidth: true + + text: webEngineView.url + selectByMouse: true + onEditingFinished: webEngineView.url = utils.fromUserInput(text) + } + + ToolButton { + id: settingsButton + text: "Settings" + icon.name: "settings-configure" + display: AbstractButton.TextUnderIcon + onClicked: settingsMenu.open() + checked: settingsMenu.visible + + Menu { + id: settingsMenu + y: settingsButton.height + + MenuItem { + id: customContextMenuOption + checkable: true + checked: true + + text: "Custom context menu" + } + } + } + } + } + + WebEngineView { + id: webEngineView + url: "https://qt.io" + anchors.fill: parent + + Component.onCompleted: { + profile.downloadRequested.connect(function(download){ + download.accept(); + }) + } + +//! [1] + property Menu contextMenu: Menu { + Repeater { + model: [ + WebEngineView.Back, + WebEngineView.Forward, + WebEngineView.Reload, + WebEngineView.SavePage, + WebEngineView.Copy, + WebEngineView.Paste, + WebEngineView.Cut, + WebEngineView.ChangeTextDirectionLTR, + WebEngineView.ChangeTextDirectionRTL, + ] + MenuItem { + text: webEngineView.action(modelData).text + enabled: webEngineView.action(modelData).enabled + onClicked: webEngineView.action(modelData).trigger() + icon.name: webEngineView.action(modelData).iconName + display: MenuItem.TextBesideIcon + } + } + } + + onContextMenuRequested: function(request) { + if (customContextMenuOption.checked) { + request.accepted = true; + contextMenu.popup(); + } + } +//! [1] + } +} diff --git a/src/webenginequick/doc/snippets/qtwebengine_webengineview_newviewrequested.qml b/src/webenginequick/doc/snippets/qtwebengine_webengineview_newviewrequested.qml index 0835c5246..6b10df752 100644 --- a/src/webenginequick/doc/snippets/qtwebengine_webengineview_newviewrequested.qml +++ b/src/webenginequick/doc/snippets/qtwebengine_webengineview_newviewrequested.qml @@ -1,56 +1,9 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the QtWebEngine module of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** 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. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause -import QtQuick 2.0 -import QtQuick.Window 2.1 -import QtWebEngine 2.0 +import QtQuick +import QtQuick.Window +import QtWebEngine //! [0] QtObject { @@ -74,9 +27,9 @@ QtObject { // Handle the signal. Dynamically create the window and // use its WebEngineView as the destination of our request. - onNewViewRequested: function(request) { + onNewWindowRequested: function(request) { var newWindow = windowComponent.createObject(windowParent); - newWindow.webView.acceptAsNewView(request); + newWindow.webView.acceptAsNewWindow(request); } } } diff --git a/src/webenginequick/doc/src/context_menu_request.qdoc b/src/webenginequick/doc/src/context_menu_request.qdoc index 40b595696..e7d732d5e 100644 --- a/src/webenginequick/doc/src/context_menu_request.qdoc +++ b/src/webenginequick/doc/src/context_menu_request.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype ContextMenuRequest diff --git a/src/webenginequick/doc/src/external-resources.qdoc b/src/webenginequick/doc/src/external-resources.qdoc deleted file mode 100644 index 24648b848..000000000 --- a/src/webenginequick/doc/src/external-resources.qdoc +++ /dev/null @@ -1,146 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \externalpage http://www.chromium.org - \title Chromium Project -*/ - -/*! - \externalpage https://developers.google.com/web/tools/chrome-devtools - \title Chrome DevTools -*/ - -/*! - \externalpage https://developer.chrome.com/docs/devtools/console/ - \title Chrome console API -*/ - -/*! - \externalpage http://ffmpeg.org/ - \title FFmpeg -*/ - -/*! - \externalpage http://www.openh264.org/ - \title OpenH264 Project Homepage -*/ - -/*! - \externalpage http://html5demos.com/drag - \title HTML5 Demos - Drag and Drop -*/ - -/*! - \externalpage http://html5demos.com/drag-anything - \title HTML5 Demos - Simple Drag and Drop -*/ - -/*! - \externalpage http://html5demos.com/dnd-upload - \title HTML5 Demos - Drag and Drop, Automatic Upload -*/ - -/*! - \externalpage http://html5demos.com/file-api - \title HTML5 Demos - File API -*/ - -/*! - \externalpage http://www.widevine.com - \title Widevine CDM -*/ - -/*! - \externalpage http://demo.castlabs.com/ - \title castLabs -*/ - -/*! - \externalpage http://ssdemo04.swankmp.net/ - \title Swank Motion Pictures, Inc. -*/ - -/*! - \externalpage https://bitmovin.com/demos/drm - \title Bitmovin Player -*/ - -/*! - \externalpage https://sourceforge.net/projects/hunspell/ - \title Hunspell Project -*/ - -/*! - \externalpage https://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1 - \title RFC 2616 section 19.5.1 -*/ - -/*! - \externalpage https://www.iana.org/assignments/uri-schemes/prov/view-source - \title view-source URI scheme -*/ - -/*! - \externalpage https://wiki.greasespot.net/Metadata_Block - \title Greasemonkey -*/ - -/*! - \externalpage https://http2.github.io/ - \title HTTP/2 -*/ - -/*! - \externalpage https://http2.akamai.com/demo - \title Akamai HTTP/2 Demo -*/ - -/*! - \externalpage https://www.chromium.org/developers/design-documents/user-scripts - \title User Scripts -*/ - -/*! - \externalpage https://wiki.greasespot.net/Metadata_Block#.40name - \title Metadata Block -*/ - -/*! - \externalpage https://developer.mozilla.org/en-US/docs/Web/API/Navigator/registerProtocolHandler - \title registerProtocolHandler -*/ - -/*! - \externalpage https://www.w3.org/TR/notifications - \title Web Notifications API -*/ - -/*! - \externalpage https://developers.google.com/web/updates/2017/09/autoplay-policy-changes - \title Autoplay Policy Changes -*/ diff --git a/src/webenginequick/doc/src/fullscreen_request.qdoc b/src/webenginequick/doc/src/fullscreen_request.qdoc index ec7d93ba6..60da2748c 100644 --- a/src/webenginequick/doc/src/fullscreen_request.qdoc +++ b/src/webenginequick/doc/src/fullscreen_request.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype FullScreenRequest diff --git a/src/webenginequick/doc/src/loading_info.qdoc b/src/webenginequick/doc/src/loading_info.qdoc index fe8e30a80..c97799e24 100644 --- a/src/webenginequick/doc/src/loading_info.qdoc +++ b/src/webenginequick/doc/src/loading_info.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2021 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) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype WebEngineLoadingInfo @@ -79,6 +55,8 @@ Error is related to the FTP connection. \value WebEngineLoadingInfo.DnsErrorDomain Error is related to the DNS connection. + \value WebEngineLoadingInfo.HttpStatusCodeDomain + Error is the HTTP response status code, even in case of success e.g. the server replied with status 200. */ /*! \qmlproperty int WebEngineLoadingInfo::errorCode diff --git a/src/webenginequick/doc/src/navigation_history.qdoc b/src/webenginequick/doc/src/navigation_history.qdoc index f24668422..94876799d 100644 --- a/src/webenginequick/doc/src/navigation_history.qdoc +++ b/src/webenginequick/doc/src/navigation_history.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype WebEngineHistoryModel @@ -96,7 +72,7 @@ The data models can also be used to create a menu, as illustrated by the following code snippet: - \quotefromfile webengine/quicknanobrowser/BrowserWindow.qml + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml \skipto ToolBar \printuntil onObjectRemoved \printuntil } diff --git a/src/webenginequick/doc/src/qtwebengine-debugging.qdoc b/src/webenginequick/doc/src/qtwebengine-debugging.qdoc deleted file mode 100644 index f84cca312..000000000 --- a/src/webenginequick/doc/src/qtwebengine-debugging.qdoc +++ /dev/null @@ -1,117 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtwebengine-debugging.html - \title Qt WebEngine Debugging and Profiling - - \section1 Console Logging - - JavaScript executed inside \QWE can use the - \l{Chrome console API} to log information to a console. The logging messages - are forwarded to Qt's logging facilities inside a \c js - \l{QLoggingCategory}{logging category}. However, only warning and fatal - messages are printed by default. To change this, you either have to set custom - rules for the \c js category, or provide custom message handlers - by reimplementing \l{QWebEnginePage::javaScriptConsoleMessage()}, or - connecting to \l{WebEngineView::javaScriptConsoleMessage()}. - - All messages can also be accessed through the \QWE developer - tools. - - \section1 Qt WebEngine Developer Tools - - The \QWE module provides web developer tools that make it easy - to inspect and debug layout and performance issues of any web content. - - The developer tools are accessed as a local web page using a Chromium or - \QWE based browser, such as the Chrome browser. - - To activate the developer tools, start an application that uses \QWE - with the command-line arguments: - - \badcode - --remote-debugging-port=<port_number> - \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. - - For a detailed explanation of the capabilities of developer tools, see the - \l {Chrome DevTools} page. - - \section1 Using Command-Line Arguments - - You can use the following command-line arguments while debugging to provide - input for bug reports: - - \list - \li \c {--disable-gpu} disables GPU hardware acceleration. This is - useful when diagnosing OpenGL problems. - \li \c {--disable-logging} disables console logging, which might be - useful for debug builds. - \li \c {--enable-logging --log-level=0} enables console logging and sets - the logging level to 0, which means that messages of the severity - \c info and above are recorded in the log. This is the default for - debug builds. Other possible log levels are \c 1 for warnings, \c 2 - for errors, and \c 3 for fatal errors. - \li \c {--v=1} Increases the logging level beyond what \c {--log-level} - can, and enables logging debug messages up to verbosity level \c 1. - A higher number further increases verbosity, but may result in a - large number of logged messages. Default is \c 0 (no debug messages). - \li \c {--no-sandbox} disables the sandbox for the renderer and plugin - processes. Keep in mind that disabling the sandbox might present a - security risk. - \li \c {--single-process} runs the renderer and plugins in the same - process as the browser. This is useful for getting stack traces for - renderer crashes. - \li \c {--enable-features=NetworkServiceInProcess} runs networking in - the main process. This may help firewall management, since only the - application executable will need to be whitelisted and - not QtWebEngineProcess. It means losing the security of - sandboxing of the network service though. - \endlist - - Alternatively, the environment variable QTWEBENGINE_CHROMIUM_FLAGS can be - set. For example, the following value could be set to disable logging while - debugging an application called \e mybrowser: - - \code - QTWEBENGINE_CHROMIUM_FLAGS="--disable-logging" mybrowser - \endcode - - QTWEBENGINE_CHROMIUM_FLAGS can also be set using {qputenv} from within the - application if called before QtWebEngineQuick::initialize(). -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-deploying.qdoc b/src/webenginequick/doc/src/qtwebengine-deploying.qdoc deleted file mode 100644 index 7b9f3fd4a..000000000 --- a/src/webenginequick/doc/src/qtwebengine-deploying.qdoc +++ /dev/null @@ -1,158 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtwebengine-deploying.html - \title Deploying Qt WebEngine Applications - - The way to package and deploy applications varies between operating systems. - For Windows and \macos, \l{The Windows Deployment Tool}{windeployqt} and - \l{Deploying Applications on macOS}{macdeployqt} automate the steps to - generate a stand-alone application package. - - When manually deploying applications that depend on \QWE, all the - files that are required to run the application have to be included: - libraries, QML imports, plugins, and translations. - - For more information, see \l {Deploying Qt Applications}. - - \section1 Target Platforms - - \QWE does try to support all \l{Supported Platforms} of Qt. However, - due to different requirements of Chromium this is not always possible. Known - limitations are: - - \list - \li \QWE currently supports only Windows, Linux, and \macos. - - \li On Windows, \QWE only supports Windows Vista or newer as - target platform. Due to use of newer API in Chromium, Windows XP is - not supported. WinRT is not supported, either. - \endlist - - \section1 Deploying Applications Manually - - When manually deploying applications that depend on \QWE, the - following files might have to be deployed: - - \list - \li Libraries - \li QML imports - \li \QWE process - \li Resources - \li Translations - \li Audio and video codecs - \endlist - - \section2 Deploying Libraries - - The following libraries must be deployed with applications that depend on - \QWE: - - \list - \li QtWebEngineCore library - \li QtWebEngineWidgets or QtWebEngine libraries, depending on - application type - \endlist - - \section2 Deploying QML Imports - - If Qt Quick integration is used in the application, the QtWebEngine import - directory needs to be deployed. - - \section2 Deploying \QWE Processes - - \QWE takes advantage of the multi-process model that the Chromium - project offers. The multi-process model requires that the \QWE - Process executable be deployed alongside your application. - - The WebEngine process is executed for each QWebEngineView or WebEngineView - instance. For example, a browser application - with two tabs open should have two separate instances of the process - running. This is a common approach used by most modern web engines to - provide a stable browsing experience. - - At runtime, \QWE looks for the \c QtWebEngineProcess executable in - the directory that - QLibraryInfo::location(QLibraryInfo::LibraryExecutablesPath) returns. - For Qt installations, this is \c QTDIR/libexec (Linux) or \c QTDIR\bin - (Windows). The path can be changed by defining a \c qt.conf file, for - example. Alternatively, an executable path can be set as a value of the - \c QTWEBENGINEPROCESS_PATH environment variable. On \macos, \QWE - looks for the executable in \c .app/Helpers/QtWebEngineProcess. - - \section2 Deploying Resources - - \QWE requires the following resource files: - - \list - \li \c qtwebengine_resources.pak contains the resources needed by - Chromium. - \li \c qtwebengine_devtools_resources.pak contains tools for remote - debugging. - \li \c qtwebengine_resources_100p.pak contains images suitable for low - resolution displays. - \li \c qtwebengine_resources_200p.pak contains images suitable for high - DPI displays. - \li \c icudtl.dat provides support for International Components for - Unicode (ICU). It is the Chromium version of ICU, which is not - needed if \QWE was configured to use the system ICU. - \endlist - - Resources are searched from the following locations: - - \list - \li On Linux and Windows: the \c resources directory in the directory - specified by QLibraryInfo::location(QLibraryInfo::DataPath) - \li On \macos: \c .app/Content/Resources - \endlist - - \section2 Translations - - Locale data (such as \c en-US.pak) is searched form the following locations: - - \list - \li On \macos: \c .app/Content/Resources - \li On Linux and Windows: \c qtwebengine_locales directory in the - directory specified by - QLibraryInfo::location(QLibraryInfo::TranslationsPath) - \endlist - - \section2 JavaScript Files in Qt Resource Files - - If your WebEngine application is built using the Qt Quick Compiler, and the application ships - JavaScript files inside .qrc resources, and these files are supposed to be loaded from inside - HTML pages, make sure to specify the resource files in a \c QTQUICK_COMPILER_SKIPPED_RESOURCES - qmake variable inside your project. This prevents the Qt Quick Compiler from trying to generate - C++ code for the corresponding JavaScript code, as well as removing the original JavaScript code - from the Qt resources file, which would lead to broken HTML pages. For example: - - \code - QTQUICK_COMPILER_SKIPPED_RESOURCES += resources/my_resource.qrc - \endcode - -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-examples.qdoc b/src/webenginequick/doc/src/qtwebengine-examples.qdoc index d31895078..eebf18ba1 100644 --- a/src/webenginequick/doc/src/qtwebengine-examples.qdoc +++ b/src/webenginequick/doc/src/qtwebengine-examples.qdoc @@ -1,35 +1,10 @@ -/**************************************************************************** -** -** 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 /*! \group webengine-examples - \title Qt WebEngine Examples + \title Qt WebEngine Quick Examples \brief Examples demonstrating the \QWE usage. - \ingroup all-examples These examples and demonstrations show a range of different uses for \l{Qt WebEngine}, from displaying Web pages within a QML user interface to an implementation of diff --git a/src/webenginequick/doc/src/qtwebengine-features.qdoc b/src/webenginequick/doc/src/qtwebengine-features.qdoc deleted file mode 100644 index 24bc9d7aa..000000000 --- a/src/webenginequick/doc/src/qtwebengine-features.qdoc +++ /dev/null @@ -1,683 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtwebengine-features.html - \title Qt WebEngine Features - - \brief Summarizes \QWE features. - - \QWE supports the following features: - - \list - \li \l{Audio and Video Codecs} - \li \l{Chromium DevTools} - \li \l{Client Certificates} - \li \l{Custom Schemes} - \li \l{Drag and Drop} - \li \l{Fullscreen} - \li \l{HTML5 DRM} - \li \l{HTML5 Geolocation} - \li \l{HTTP/2 Protocol} - \li \l{Native Dialogs} - \li \l{Pepper Plugin API} - \li \l{PDF File Viewing} - \li \l{Page Lifecycle API} - \li \l{Print to PDF} - \li \l{Process Models} - \li \l{Spellchecker} - \li \l{Touch} - \li \l{View Source} - \li \l{webrtc_feature}{WebRTC} - \li \l{Web Notifications} - \li \l{Favicon Handling} - \endlist - - \section1 Audio and Video Codecs - - \QWE supports the MPEG-4 Part 14 (MP4) file format only if the - required proprietary audio and video codecs, such as H.264 and MPEG layer-3 - (MP3), have been enabled. Proprietary codecs can be enabled by passing the - following option to the \c configure tool when configuring Qt: - - \code - -webengine-proprietary-codecs - \endcode - - For example, the following option could be passed when configuring Qt for - building it at the top level: - - \code - configure -webengine-proprietary-codecs - \endcode - - For more information, see \l{Qt Configure Options}. - - When using qmake to build just the \QWE module, the following - command can be used (in this example, the \QWE source code is - located in \c {C:\qt\qtwebengine}): - - \code - qmake C:\qt\qtwebengine -- -webengine-proprietary-codecs - \endcode - - \warning When distributing proprietary codec libraries, you must acquire - licenses for them. - - \l FFmpeg is a cross-platform solution to record, convert, and stream audio - and video. It can be configured for use with several codecs, which rises - licensing issues during distribution with the codec libraries. For some - codecs, open source implementations, such as \l{OpenH264 Project Homepage} - {OpenH264}, are available. - - \section1 Chromium DevTools - - The Chromium DevTools provide the ability to inspect and debug layout and - performance issues of any web content. - - This feature can be tested by launching a \QWE application with the - command line option \c {--remote-debugging-port=[your-port]} or by setting - the environment variable \c QTWEBENGINE_REMOTE_DEBUGGING, and then using a - Chromium based browser (such as \l{WebEngine Widgets Simple Browser Example} - {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}) to connect - to \c {http://localhost:[your-port]}. - - The Chromium DevTools page can also be shown within the application. To set - this up, you can call either QWebEnginePage::setInspectedPage() to the page - to be inspected, which implicitly loads the DevTools into the \c this page, - or QWebEnginePage::setDevToolsPage() to let the \c this page be inspected. - - The respective QML properties are \l{WebEngineView::devToolsView} - {WebEngineView.devToolsView} and \l{WebEngineView::inspectedView} - {WebEngineView.inspectedView}. - - For more information, see \l {Qt WebEngine Debugging and Profiling}. - - \section1 Client Certificates - - Some web servers, in particular many intranet sites, require the client to - authenticate itself with a certificate, called a \e {client certificate}. \QWE - will read the client certificates installed in the system settings in macOS and - Windows, and on Linux those installed into the NSS database. Certificates can - be installed into the NSS database using the \c pk12util tool. - - By default, \QWE will not offer any client certificates to servers, as doing - so uniquely identifies the user and might violate privacy expectations. - - To activate support for client certificates, an application needs to listen to - the QWebEnginePage::selectClientCertificate or - \l{WebEngineView::selectClientCertificate}{WebEngineView.selectClientCertificate} - signals and select one of the offered - certificates. For applications that can navigate to untrusted web sites, it is - recommended to always give the user a choice before uniquely identifying them - to a remote server. - - \section1 Custom Schemes - - \QWE makes it possible for the application to define its own custom - URL schemes with specialized security policies and transport mechanisms. - - Custom schemes can be used to implement alternative network protocols with - all the usual web security policies, privileged internal schemes for - displaying user interface compoments or debugging information, sandboxed - schemes with extra restrictions, and so on. - - For more information, see \l QWebEngineUrlScheme and \l - QWebEngineUrlSchemeHandler. - - \section1 Drag and Drop - - \QWE supports HTML5 drag and drop. - - This feature can be tested by opening an HTML5 drag and drop demo, such as - \l{HTML5 Demos - Drag and Drop}, \l{HTML5 Demos - Simple Drag and Drop}, or - \l{HTML5 Demos - Drag and Drop, Automatic Upload}, in \l{WebEngine Widgets - Simple Browser Example}{Simple Browser} or \l{WebEngine Quick Nano Browser} - {Nano Browser}. - - Dragging files into the browser is not actually part of HTML5, but it is - supported. It can be tested by opening \l{HTML5 Demos - File API}. - - Support for this feature was added in Qt 5.7.0. - - \section1 Fullscreen - - \QWE supports viewing web content in fullscreen mode. For more - information, see \l{WebEngineSettings::fullscreenSupportEnabled} - {WebEngineSettings.fullscreenSupportEnabled}, - \l{WebEngineView::fullScreenRequested}{WebEngineView.fullScreenRequested}, - QWebEngineSettings::FullScreenSupportEnabled, and - QWebEnginePage::fullScreenRequested. - - This feature can be tested by playing a video from YouTube in \l{WebEngine - Widgets Video Player Example}{Video Player} or \l{WebEngine Quick Nano Browser} - {Nano Browser}, and clicking the full screen icon to go into fullscreen - mode. - - Support for this feature was added in Qt 5.6.0. - - \section1 HTML5 DRM - - \QWE supports viewing DRM protected videos if the \l{Widevine CDM} plugin has been installed. - CDM plugin is a replacement of Flash based plugins for displaying DRM-protected content. - It comes only in a binary format, so it can hide DRM decryption implementation details. - It can be obtained from a third party or from a Google Chrome installation. - - \QWE on startup looks for the \l{Widevine CDM} plugin in well know locations, like - default Google Chrome installation directory or Linux distro specific paths. However, plugin - location can be also passed with \c {QTWEBENGINE_CHROMIUM_FLAGS} using \c {widevine-path}. - - On Windows: - \code - set QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="C:/some path/widevinecdm.dll" - \endcode - - On Linux: - \code - export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.so" - \endcode - - On macOS: - \code - export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.dylib" - \endcode - - - The video format most commonly used by DRM services, H.264, requires - proprietary audio and video codecs. For more information about enabling the - codecs, see \l{Audio and Video Codecs}. - - This feature can be tested by playing a video in \l{WebEngine Widgets Simple Browser - Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser} - from \l{castLabs}, \l{Swank Motion Pictures, Inc.}, or \l{Bitmovin Player}. - - Support for this feature was added in Qt 5.7.0. - - \section1 HTML5 Geolocation - - \QWE supports JavaScript Geolocation API with \l {Qt Location} as a - backend. The application has to explicitly allow the feature by using - QWebEnginePage::Geolocation or \l{WebEngineView::Feature} - {WebEngineView.Feature}. - - If Qt Location has been built before \QWE then this feature can be - tested by using \l{WebEngine Widgets Maps Example}{Maps} and allowing it to - find the current position of the user. Note that on Windows an external GPS - receiver must be connected to the application. For more information, see - \l{Qt Positioning}. - - Support for this feature was added in Qt 5.5.0. - - \section1 HTTP/2 Protocol - - \QWE supports the Chromium implementation of the \l{HTTP/2} - protocol. - - This feature can be tested by opening an HTTP/2 demo, such as the - \l{Akamai HTTP/2 Demo}, in \l{WebEngine Widgets Simple Browser Example} - {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}. - - \section1 Native Dialogs - - A web page might request dialogs for the following functions: - - \list - \li Entering user credentials for HTTP and proxy authentication - \li Displaying JavaScript alerts, confirmation dialogs, and prompts - \li Picking colors - \li Selecting files - \li Displaying form validation messages - \endlist - - \QWE provides standard dialogs for these functions. In widget-based - applications, the standard dialogs are based on QDialog, whereas in Qt Quick - applications, they can be based either on Qt Quick Controls 1 or Qt Quick - Controls 2 (since Qt 5.8). The latter are used only on \c eglfs platforms. - - To explicitly force either dialogs based on Qt Quick Controls 1 or Qt Quick - Controls 2, set the \c QTWEBENGINE_DIALOG_SET environment variable to either - \c{QtQuickControls1} or \c{QtQuickControls2}. - - \QWE Widgets dialogs can be customized by reimplementing the - QWebEnginePage::chooseFiles(), QWebEnginePage::javaScriptAlert(), - QWebEnginePage::javaScriptConfirm(), and QWebEnginePage::javaScriptPrompt() - functions. - - Since Qt 5.8, Qt Quick dialogs can be customized by connecting to the - WebEngineView::authenticationDialogRequested(), - WebEngineView::javaScriptDialogRequested(), - WebEngineView::colorDialogRequested(), - WebEngineView::fileDialogRequested(), and - WebEngineView::formValidationMessageRequested() signals. For an example, - see \l{WebEngine Qt Quick Custom Dialogs Example}. - - \section1 Pepper Plugin API - - \QWE supports loading Pepper Plugin API (PPAPI) plugins if - WebEngineSettings::pluginsEnabled or QWebEngineSettings::PluginsEnabled - is set. - - Except for the Adobe Flash Player plugin, the plugins must be loaded - manually using the Chromium command line syntax with the - \c --register-pepper-plugins argument. The argument value is a list of - entries, separated by commas, that contain the file path and one or several - MIME types, separated by semicolons: - - \code - <file-path-plugin1>;<mime-type-plugin1>,<file-path-plugin2>;<mime-type1-plugin2>;<mime-type2-plugin2> - \endcode - - For example: - - \code - --register-pepper-plugins="libppapi_example.so;application/x-ppapi-example" - \endcode - - The MIME type is important because it determines which embeds the plugin is - used for. - - Support for this feature was added in Qt 5.6.0. - - \section2 Pepper Flash Player Plugin Support - - The Pepper Flash player plugin can be loaded automatically if it is - installed in one of the following locations, depending on the platform: - - \list - \li Windows - \code - C:\Windows\SysWOW64\Macromed\Flash\pepflashplayer*.dll - C:\Windows\System32\Macromed\Flash\pepflashplayer*.dll - \endcode - \li OS X - \code - /Library/Internet Plug-Ins/PepperFlashPlayer/PepperFlashPlayer.plugin - \endcode - \li Linux - \code - /usr/lib/pepperflashplugin-nonfree/libpepflashplayer.so - /usr/lib/adobe-flashplugin/libpepflashplayer.so - /usr/lib/PepperFlash/libpepflashplayer.so - /usr/lib64/chromium/PepperFlash/libpepflashplayer.so - \endcode - \endlist - - You can also load the Pepper Flash player from a specific location by using - command line arguments: - - \code - --ppapi-flash-path=./libpepflashplayer.so - \endcode - - By default, the Flash version is set to \c{11.2.999.999}. You can use the - \c{ppapi-flash-version=} argument to set another Flash version in the - format \c{major.minor.build.revision}: - - \code - --ppapi-flash-version=16.0.0.235 - \endcode - - This feature can be tested in \l{WebEngine Widgets Simple Browser Example}{Simple Browser} - or \l{WebEngine Quick Nano Browser}{Nano Browser} if the Adobe Flash PPAPI - plugin is installed and plugins are enabled in the browser. To test the - feature, the \c https://helpx.adobe.com/flash-player.html page can be opened - in the browser. - - \section1 PDF File Viewing - - \QWE supports viewing PDF documents by navigating to them. This feature uses the Chromium - extensions API and PDF viewer plugin to display the PDF documents. - It can be tested in \l{WebEngine Widgets Simple Browser Example}{Simple Browser} or - \l{WebEngine Quick Nano Browser}{Nano Browser}. - - Loading plugins needs to be enabled using QWebEngineSettings::PluginsEnabled or - WebEngineSettings::pluginsEnabled in order to use this feature. - - This feature can be turned on (default) or off via the QWebEngineSettings::PdfViewerEnabled or - WebEngineSettings::pdfViewerEnabled setting. - - Support for this feature was added in Qt 5.13.0. - - \section1 Page Lifecycle API - - \QWE supports the \l {https://wicg.github.io/page-lifecycle/spec.html}{Page - Lifecycle API specification}, a work-in-progress extension to the HTML - standard for allowing user agents to reduce their resource consumption by - freezing or discarding background pages. The feature is exposed both in the - Widgets and QML APIs. - - For an example of the QML API in use, see the \l {WebEngine Lifecycle - Example}. - - Support for this feature was added in Qt 5.14.0. - - \section2 Overview of Lifecycle States - - Each \l {WebEngineView} item (or \l {QWebEnginePage} object) can be in one - of three \e {lifecycle states}: active, frozen, or discarded. These states, - like the sleep states of a CPU, control the resource usage of web views. - - The \e {active} state is the normal, unrestricted state of a web view. All - visible web views are always in the active state, as are all web views that - have not yet finished loading. Only invisible, idle web views can be - transitioned to other lifecycle states. - - The \e {frozen} state is a low CPU usage state. In this state, most HTML - task sources are suspended (frozen) and, as a result, most DOM event - processing and JavaScript execution will also be suspended. The web view - must be invisible in order to be frozen as rendering is not possible in this - state. - - The \e {discarded} state is an extreme resource-saving state. In this state, - the browsing context of the web view will be discarded and the corresponding - renderer subprocess shut down. CPU and memory usage in this state is reduced - virtually to zero. On exiting this state the web page will be automatically - reloaded. The process of entering and exiting the discarded state is similar - to serializing the browsing history of the web view and destroying the view, - then creating a new view and restoring its history. - - See also \l {WebEngineView::LifecycleState}. The equivalent in the Widgets - API is \l {QWebEnginePage::LifecycleState}. - - \section2 The \c {lifecycleState} and \c {recommendedState} Properties - - The \l {WebEngineView::}{lifecycleState} property of the \l {WebEngineView} - type is a read-write property that controls the current lifecycle state of - the web view. This property is designed to place as few restrictions as - possible on what states can be transitioned to. For example, it is allowed - to freeze a web view that is currently playing music in the background, - stopping the music. In order to implement a less aggressive resource-saving - strategy that avoids interrupting user-visible background activity, the \l - {WebEngineView::} {recommendedState} property must be used. - - The \l {WebEngineView::}{recommendedState} property of the \l - {WebEngineView} type is a read-only property that calculates a safe limit on - the \l {WebEngineView::}{lifecycleState} property, taking into account the - current activity of the web view. So, in the example of a web view playing - music in the background, the recommended state will be \c {Active} since a - more aggressive state would stop the music. If the application wants to - avoid interrupting background activity, then it should avoid putting the web - view into a more aggressively resource-saving lifecycle state than what's - given by \l {WebEngineView::}{recommendedState}. - - See also \l {WebEngineView::lifecycleState} and \l - {WebEngineView::recommendedState}. The equivalents in the Widgets API are \l - {QWebEnginePage::lifecycleState} and \l {QWebEnginePage::recommendedState}. - - \section2 The DOM Extensions - - The \l {WebEngineView::}{lifecycleState} property is connected to the \l - {https://wicg.github.io/page-lifecycle/spec.html}{Page Lifecycle API - specification}, which specifies two new DOM events, \c {freeze} and \c - {resume}, and adds a new \c {Document.wasDiscarded} boolean property. The \c - {freeze} and \c {resume} events are fired when transitioning from the \c - {Active} to the \c {Frozen state}, and vice-versa. The \c - {Document.wasDiscarded} property is set to \c {true} when transitioning from - the \c {Discarded} state to the \c {Active} state. - - \section1 Print to PDF - - \QWE supports printing a web page to a PDF file. For more - information, see QWebEnginePage::printToPdf() and - \l{WebEngineView::printToPdf}{WebEngineView.printToPdf}. - - This feature can be tested using \l{WebEngine Widgets Html2Pdf Example} - {Html2Pdf}. - - Support for this feature was added in Qt 5.7.0. - - \section1 Process Models - - \QWE uses multiple OS processes to isolate web sites from each other - and from the client application, improving security and robustness. The - following process models, or ways to divide web sites between OS processes, - are supported: - - \list - \li \l{Process per Site Instance} - \li \l{Process per Site} - \li \l{Single Process} - \endlist - - \section2 Process per Site Instance - - This is the default model. Pages from separate sites are put into separate - processes and separate visits to the same site are also isolated. - - Two web pages are considered as belonging to the same site if they originate - from the same registered domain name (for example, \c wikipedia.org) and - scheme (for example, \c https). This is similar to the same-origin policy - but subdomains are ignored. For example, both \c{https://en.wikipedia.org/} - and \c{https://de.wikipedia.org/} would belong to the same site. - - A site instance is a collection of web pages belonging to the same site. - When the application explicitly loads a URL into \QWE (via \l - QWebEnginePage::setUrl, for example), a new site instance is created for the - page. However, when the user clicks same-site links on the page, the - existing site instance is merely extended with more pages. - - For instance, in the \l{WebEngine Widgets Simple Browser Example}{Simple - Browser} example, when a user opens two tabs and explicitly enters - \c{https://en.wikipedia.org/} into the URL bars, both tabs will have their - own separate OS processes (because explicitly entering a URL creates a new - site instance). However, when the user then middle-clicks some same-site - links to open more tabs, these new tabs will share the same OS process - (because user interaction extends the existing site instance). - - \section2 Process per Site - - Pages from separate sites are put into separate processes. Unlike Process - per Site Instance, all visits to the same site will share an OS process. - - The benefit of this model is reduced memory consumption, because more web - pages will share processes. The drawbacks include reduced security, - robustness, and responsiveness. - - To enable this model, use the command-line argument \c{--process-per-site}. - See \l{Using Command-Line Arguments}. - - \section2 Single Process - - For debugging purposes only, a single process mode can be enabled using the - command-line argument \c{--single-process}. See \l{Using Command-Line - Arguments} and \l{Qt WebEngine Debugging and Profiling}. - - \section1 Spellchecker - - \QWE supports integrating spellchecking support into HTML forms to - enable users to submit spellchecked messages. When the user clicks on - an underlined misspelled word, the default context menu displays up to four - suggestions. Selecting one will replace the misspelled word. - - To be able to check the spelling, the spellchecker needs dictionaries. It - supports dictionaries from the \l{Hunspell project}, but they have to be - compiled into a special binary format. A Hunspell dictionary consists of two - files: - - \list - - \li A \c .dic file that is a dictionary containing words for the - language - \li An \c .aff file that defines the meaning of special flags in the - dictionary - \endlist - - These two files can be converted into the \c bdic format by using the - \c qwebengine_convert_dict tool that is shipped together with Qt. - When the \QWE spellchecker initializes, it will try to load the - \c bdict dictionaries and to check them for consistency. - - If \c QTWEBENGINE_DICTIONARIES_PATH is set, the spellchecker uses the - dictionaries in the specified directory without looking anywere else. - Otherwise, it uses the \e qtwebengine_dictionaries directory relative to the - executable if it exists. If it does not exist, it will look in \c - QT_INSTALL_PREFIX/qtwebengine_dictionaries. - - On macOS, depending on how \QWE is configured at build time, there - are two possibilities how spellchecking data is found: - - \list - \li Hunspell dictionaries (default) - .bdic dictionaries are used, just - like on other platforms - \li Native dictionaries - the macOS spellchecking APIs are used (which - means the results will depend on the installed OS dictionaries) - \endlist - - Thus, in the macOS Hunspell case, \QWE will look in the \e - qtwebengine_dictionaries subdirectory located inside the application bundle - \c Resources directory, and also in the \c Resources directory located - inside the Qt framework bundle. - - To summarize, in case of Hunspell usage, the following paths are considered: - - \list - \li \c QTWEBENGINE_DICTIONARIES_PATH, if set - \li QCoreApplication::applicationDirPath()/qtwebengine_dictionaries - or QCoreApplication::applicationDirPath()/../Contents/Resources/qtwebengine_dictionaries - (on macOS) - \li [QLibraryInfo::DataPath]/qtwebengine_dictionaries - or path/to/QtWebEngineCore.framework/Resources/qtwebengine_dictionaries (Qt framework - bundle on macOS) - \endlist - - Spellchecking is disabled by default and can be enabled per profile by - using the QWebEngineProfile::setSpellCheckEnabled() method in widget-based - applications and the \l {QQuickWebEngineProfile::spellCheckEnabled} - {WebEngineProfile.spellCheckEnabled} property in Qt Quick applications. - - The current language used for spellchecking is defined per profile, and can - be set using the QWebEngineProfile::setSpellCheckLanguages() method or the - \l {QQuickWebEngineProfile::spellCheckLanguages} - {WebEngineProfile.spellCheckLanguages} property. - - This feature can be tested by building and running the - \l{WebEngine Widgets Spellchecker Example}{Spellchecker Example}. - - Support for this feature was added in Qt 5.8.0. - - \section1 Touch - - \QWE supports touch devices for navigating and interacting with web pages. - - Applications can prohibit the use of touch events in the following ways: - - \list - \li Passing the flag \c --touch-events=disabled on the command line will disable touch event - support in JavaScript API (meaning \c ontouchstart and related handlers will not be present - in the \c document.window object). Touch events will still be delivered to web pages. - - \li Installing an event filter object using \l {QObject::installEventFilter} on the WebEngine - view focus proxy object, and filtering out all touch events. - - \endlist - - \section1 View Source - - \QWE supports viewing the HTML source of a web page. - - This feature can be used from custom menus or assigned to custom events. - For more information, see WebEngineView::WebAction, and QWebEnginePage::WebAction. - - This feature can be tested by opening a web page in \l{WebEngine Widgets - Simple Browser Example}{Simple Browser} or \l{WebEngine Quick Nano Browser} - {Nano Browser}, and then selecting \c{Page Source} in the context menu. The - \c{Page Source} context menu entry opens the source view in a new tab. - - For opening the source view in the current tab, URLs with \l{view-source URI scheme} - are also supported. For example, you can type the following URL to the URL bar - to view the HTML source of the qt.io web page: - \code - view-source:https://www.qt.io/ - \endcode - - Auto-completion of incomplete URLs with \l{view-source URI scheme} makes the usage of - this feature more comfortable. For example, the following incomplete URL also loads - the source view of the qt.io web page: - \code - view-source:qt.io - \endcode - - Support for this feature was added in Qt 5.8.0. - - \target webrtc_feature - \section1 WebRTC - - WebRTC provides browsers with Real-Time Communications (RTC) capabilities - via simple APIs. For more information, see \l{WebEngineView::Feature} - {WebEngineView.Feature} and QWebEnginePage::Feature. - - This feature can be tested by setting up a webcam or microphone and then - opening \c https://test.webrtc.org/ in \l{WebEngine Widgets Simple Browser - Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}. - - \section1 Web Notifications - - Qt WebEngine supports JavaScript \l{Web Notifications API}. - The application has to explicitly allow the feature by using - QWebEnginePage::Notifications or \l{WebEngineView::Feature} - {WebEngineView.Notifications}. - - Support for this feature was added in Qt 5.13.0. - - \section1 Favicon Handling - - For accessing icons a \c QQuickImageProvider is registered. This provider can be - accessed by a special URL where the scheme is "image:" and the host is "favicon". - For example, - \qml - Image { - source: "image://favicon/url" - } - \endqml - - The \c url can be the URL of the favicon. For example, - \qml - Image { - source: "image://favicon/https://www.qt.io/hubfs/2016_Qt_Logo/qt_logo_green_rgb_16x16.png" - } - \endqml - - The \c url also can be a page URL to access its icon. For example, - \qml - Image { - source: "image://favicon/https://www.qt.io/" - } - \endqml - - If more than one icon is available, the \l {Image::sourceSize} property can be - specified to choose the icon with the desired size. If \l {Image::sourceSize} - is not specified or 0, the largest available icon will be chosen. - - The image provider looks up the requested icon in the existing \l {WebEngineView} - instances. First, it tries to match the currently displayed icons. If no match - has been found it requests the icon from the database. Each profile has its - own icon database and it is stored in the persistent storage thus the stored icons - can be accessed without network connection too. The icon must be previously loaded - to be stored in the database. - - \note The icon database is not available for off-the-record profiles. -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-index.qdoc b/src/webenginequick/doc/src/qtwebengine-index.qdoc deleted file mode 100644 index f668cf87b..000000000 --- a/src/webenginequick/doc/src/qtwebengine-index.qdoc +++ /dev/null @@ -1,65 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtwebengine-index.html - \title Qt WebEngine - - \brief Provides functionality for rendering regions of dynamic web content. - - \QWE provides functionality for rendering regions of dynamic web content. - - The functionality in \QWE is divided into the following modules: - - \annotatedlist qtwebengine-modules - - \section1 Articles and Guides - - \list - \li \l{Qt WebEngine Overview} - \li \l{Qt WebEngine Features} - \li \l{Qt WebEngine Platform Notes} - \li \l{Qt WebEngine Licensing} - \li \l{Qt WebEngine Debugging and Profiling} - \li \l{Deploying Qt WebEngine Applications} - \li \l{Porting from Qt WebKit to Qt WebEngine} - \endlist - - \section1 Examples - - \list - \li \l{Qt WebEngine Examples} - \li \l{Qt WebEngine Widgets Examples} - \endlist - - \section1 API References - - \list - \li \l{Qt WebEngine C++ Classes and Namespaces} - \li \l{Qt WebEngine QML Types} - \endlist -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-module.qdoc b/src/webenginequick/doc/src/qtwebengine-module.qdoc index 5554bd519..6f50cc2f4 100644 --- a/src/webenginequick/doc/src/qtwebengine-module.qdoc +++ b/src/webenginequick/doc/src/qtwebengine-module.qdoc @@ -1,46 +1,25 @@ -/**************************************************************************** -** -** 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 QtWebEngine - \title Qt WebEngine C++ Classes + \module QtWebEngineQuick + \title Qt WebEngine Quick C++ Classes \brief Exposes C++ functionality to Qt Quick. \ingroup modules + \ingroup qtwebengine-modules + \qtvariable webenginequick + \qtcmakepackage WebEngineQuick - The \QWE module exposes C++ functionality to Qt Quick. - - To include the definitions of the module's classes, use the - following directive: - - \snippet qtwebengine_build_snippet.qdoc 1 + The \QWE Quick module exposes C++ functionality to Qt Quick. \if !defined(qtforpython) To link against the module, add the following to your qmake project file: \snippet qtwebengine_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 qtwebengine_build_snippet.qdoc 2 \endif */ diff --git a/src/webenginequick/doc/src/qtwebengine-modules.qdoc b/src/webenginequick/doc/src/qtwebengine-modules.qdoc deleted file mode 100644 index 759284ad9..000000000 --- a/src/webenginequick/doc/src/qtwebengine-modules.qdoc +++ /dev/null @@ -1,48 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtwebengine-modules.html - \title Qt WebEngine C++ Classes and Namespaces - \brief Provides functionality for rendering regions of dynamic web content. - - \e {Qt WebEngine} provides functionality for rendering regions of dynamic web content. - - \section1 Namespaces - \annotatedlist qtwebengine-namespaces - - \section1 Classes - - \section2 Qt WebEngineCore Module - \generatelist {classesbymodule QtWebEngineCore} - - \section2 Qt WebEngineWidgets Module - \generatelist {classesbymodule QtWebEngineWidgets} - - \section2 Qt WebEngineQuick Module - \generatelist {classesbymodule QtWebEngineQuick} -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-overview.qdoc b/src/webenginequick/doc/src/qtwebengine-overview.qdoc deleted file mode 100644 index 099142f80..000000000 --- a/src/webenginequick/doc/src/qtwebengine-overview.qdoc +++ /dev/null @@ -1,315 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtwebengine-overview.html - \title Qt WebEngine Overview - - The \QWE module provides a web browser engine that makes it easy to embed content from - the World Wide Web into your Qt application on platforms that do not have a native web engine. - - \QWE provides C++ classes and QML types for rendering HTML, XHTML, and SVG documents, - styled using Cascading Style Sheets (CSS) and scripted with JavaScript. HTML documents can be - made fully editable by the user through the use of the \c{contenteditable} attribute on HTML - elements. - - \section1 Qt WebEngine Architecture - - \image qtwebengine-architecture.png - - The functionality in \QWE is divided into the following modules: - - \list - \li \l{Qt WebEngine Widgets Module} for creating widget-based web applications - \li \l{Qt WebEngine Module} for creating Qt Quick based web applications - \li \l{Qt WebEngine Core Module} for interacting with Chromium - \endlist - - Page rendering and JavaScript execution are separated from the GUI process into the \QWE - Process. It is a library that must be shipped with the application if the Qt libraries are - bundled into the application. - - \section2 Qt WebEngine Widgets Module - - \image qtwebenginewidgets-model.png - - A \e {web engine view} is the main widget component of the \QWE module. It can be used - in various applications to load web content. Within a view, a \e {web engine page} holds a main - frame that is responsible for web content, the \e history of navigated links, and \e actions. - The view and page are quite similar, as they provide a set of common functions. - - All pages belong to a \e {web engine profile} that contains shared \e settings, \e scripts, and - \e cookies. Profiles can be used to isolate pages from each other. A typical use case is a - dedicated profile for a \e {private browsing} mode, where no information is permanently saved. - - \note The \QWE Widgets module uses the \l{Qt Quick Scene Graph}{Qt Quick scene graph} - to compose the elements of a web page into one view. This means that the UI process - requires OpenGL ES 2.0 or OpenGL 2.0 for its rendering. - - \section2 Qt WebEngine Module - - \image qtwebengine-model.png - - The \QWE QML implementation contains the same elements as the \QWE Widgets - implementation, except that there is no separately accessible web engine page. - The supported page functionality is integrated into the web engine view. - - \section2 Qt WebEngine Core Module - - The \QWE core is based on the \l {Chromium Project}. Chromium provides its own network - and painting engines and is developed tightly together with its dependent modules. - - \note \QWE is based on Chromium, but does not contain or use any services - or add-ons that might be part of the Chrome browser that is built and delivered by Google. - You can find more detailed information about the differences between Chromium and Chrome in this - \l{https://chromium.googlesource.com/chromium/src/+/master/docs/chromium_browser_vs_google_chrome.md}{overview} - that is part of the documentation in the \l {Chromium Project} upstream source tree. - - This version of \QWE is based on Chromium version 87.0.4280, with additional security - fixes from newer versions. - - \section2 Qt WebEngine Process - - The \QWE Process is a separate executable that is used to render web pages and - execute JavaScript. This mitigates security issues and isolates crashes caused by specific - content. - - \section1 Embedding Web Content into Widget Based Applications - - Use the QWebEngineView class to display web pages in the simplest way. Because it is a widget, - you can embed QWebEngineView into your forms and use its convenience functions to download and - display web sites. - - \code - QWebEngineView *view = new QWebEngineView(parent); - view->load(QUrl("http://www.qt.io/")); - view->show(); - \endcode - - An instance of QWebEngineView has one QWebEnginePage. QWebEnginePage can have a - QWebEngineHistory that provides access to the page's navigation history and several QAction - objects that apply actions on the web page. In addition, a QWebEnginePage has the ability to - run JavaScript code in the context of the page's main frame and to enable customization of - handlers for specific events like showing custom authentication dialogs. - - Each QWebEnginePage belongs to a QWebEngineProfile that can have a QWebEngineSettings - for specifying page settings, a QWebEngineScriptCollection for running scripts on the page, and - a QWebEngineCookieStore for accessing the HTTP cookies of Chromium. A QWebEnginePage can also - directly point to a script collection. - - For a widget based application, the web engine is automatically initialized, unless it is - placed in a plugin. In that case, it must be initialized in the application main source file - by using \l QtWebEngineQuick::initialize, as illustrated by the following code snippet: - - \code - int main(int argc, char **argv) - { - QApplication app(argc, argv); - - QtWebEngineQuick::initialize(); - - QMainWindow window; - window.show(); - - return app.exec(); - } - \endcode - - \section1 Embedding Web Content into Qt Quick Applications - - The WebEngineView QML type allows Qt Quick applications to render regions of dynamic web - content. A \e{WebEngineView} type may share the screen with other QML types or encompass the - full screen as specified within the Qt Quick application. - - To make sure that OpenGL context can be shared between the GUI and render processes, the web - engine must be initialized by using \l QtWebEngineQuick::initialize in the application main source - file, as illustrated by the following code snippet: - - \code - int main(int argc, char *argv[]) - { - QGuiApplication app(argc, argv); - - QtWebEngineQuick::initialize(); - - QQmlApplicationEngine engine; - engine.load(QUrl("qrc:/main.qml")); - - return app.exec(); - } - \endcode - - An application can load pages into the WebEngineView, using either an URL or HTML string, and - navigate within session history. By default, links to different pages load within the same - WebEngineView object, but web sites may request them to be opened as a new tab, window, or - dialog. - - The following sample QML application loads a web page using the \l{WebEngineView::}{url} - property: - - \quotefromfile webengine/minimal/main.qml - \skipto import - \printuntil /^\}/ - - \section1 Script Injection - - \QWE does not allow direct access to the document object model (DOM) of a page. - However, the DOM can be inspected and adapted by injecting scripts. - - The DOM of a page is constructed when the document is ready, typically - when the page is completely loaded. Therefore, executing scripts as soon as a document is - created is not suitable for DOM operations, where one has to wait until the DOM is ready. - - In addition, an injected script shares the same \e world as the other scripts executed on the - page, which might lead to conflicts. To avoid this, the QWebEngineScript class and the - WebEngineScript QML type provide implementations of the Chromium API for - \e{Content Script Extensions}. They specify the - script to run, the injection point, and the world where the script is run. This enables - accessing the DOM to manipulate it within a world. - - Since Qt 5.8, \QWE supports augmenting a script by using the - following \l{Metadata Block}{Greasemonkey-like attributes}: - - \list - \li \c {@exclude <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::error} and \l{QWebEngineCertificateError::Type} enumerations - provide information about the types of certificate errors that might occur. The errors can be - handled by using the WebEngineView::certificateError QML method or by connecting to the - QWebEnginePage::certificateError signal. - - \section1 Proxy Support - - \QWE uses the proxy settings from \l{Qt Network}, and forwards them to Chromium's - networking stack. If QNetworkProxy::applicationProxy is set, it will also be used for \QWE. - If QNetworkProxyFactory::usesSystemConfiguration() is enabled, the proxy settings - are automatically retrieved from the system. Settings from an installed QNetworkProxyFactory - will be ignored, though. - - In case QNetworkProxy::user() and QNetworkProxy::password() are set, these credentials - will be automatically used for proxy authentication. It is up to the user to provide valid - credentials, since there is no error handling callback. - - If no credentials are set with QNetworkProxy, but the proxy requires authentication, - QWebEnginePage::proxyAuthenticationRequired is emitted. - For Qt Quick, a dialog is shown. - - Not all properties of QNetworkProxy are supported by \QWE. That is, - QNetworkProxy::type(), QNetworkProxy::hostName() and QNetworkProxy::port() are taken into - account. All other proxy settings such as QNetworkProxy::rawHeader() are ignored. - - \section1 High DPI Support - - To support High DPI devices, it is recommended that the application attribute - Qt::AA_EnableHighDpiScaling is set to enable automatic scaling based on the - pixel density of the monitor. In \QWE applications, the scaling - affects the default zooming factor and scrollbar size. - - For example: - - \code - int main(int argc, char *argv[]) - { - QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); - QApplication app(argc, argv); - // ... - } - \endcode - - \QWE bundles images for normal and high-dpi resolutions into - \e qtwebengine_resources_100p.pak and \e qtwebengine_resources_200p.pak - files. Depending on the target resolutions, one or both of these files need - to be deployed. - - For more information, see \l{High DPI}. - - \section1 Using WebEngine Core - - \QWE Core provides an API shared by \QWE and \QWE Widgets for handling - URL requests issued for the networking stack of Chromium and for accessing its HTTP cookies. - - Implementing the QWebEngineUrlRequestInterceptor interface and installing the interceptor on a - profile enables intercepting, blocking, and modifying URL requests (QWebEngineUrlRequestInfo) - before they reach the networking stack of Chromium. - - A QWebEngineUrlSchemeHandler can be registered for a profile to add support for custom URL - schemes. Requests for the scheme are then issued to QWebEngineUrlSchemeHandler::requestStarted() - as QWebEngineUrlRequestJob objects. - - The QWebEngineCookieStore class provides functions for accessing HTTP cookies of Chromium. - The functions can be used to synchronize cookies with QNetworkAccessManager, as well as to set, - delete, and intercept cookies during navigation. - - \section1 Platform Notes - - \QWE currently supports only Windows, Linux, and \macos. Due to Chromium build - requirements it also often requires a newer compiler than the rest of Qt. See - \l{Qt WebEngine Platform Notes} for further details. - - \section1 Related Modules - - \QWE supersedes the \l{http://doc.qt.io/archives/qt-5.3/qtwebkit-index.html}{Qt WebKit} - module, which is based on the - WebKit project, but has not been actively synchronized with the upstream WebKit code since - Qt 5.2 and has been deprecated in Qt 5.5. For tips on how to change a Qt \WebKit widgets - application to use \QWE widgets, see \l{Porting from Qt WebKit to Qt WebEngine}. - - The \l{Qt WebView} module allows to use a native web browser on platforms where one is - available. - - The \l{Qt WebChannel} module can be used to create a bi-directional communication channel - between QObject objects on the C++ side and JavaScript on the QML side. - -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-platform-notes.qdoc b/src/webenginequick/doc/src/qtwebengine-platform-notes.qdoc deleted file mode 100644 index 08eaf72bb..000000000 --- a/src/webenginequick/doc/src/qtwebengine-platform-notes.qdoc +++ /dev/null @@ -1,238 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtwebengine-platform-notes.html - \title Qt WebEngine Platform Notes - - \brief Contains information about issues that are specific to the \QWE module. - - \section1 Building \QWE from Source - - Static builds are not supported. - - The requirements for building Qt 5 modules from source are listed separately for each supported - platform: - - \list - \li \l{Qt for Windows - Building from Source} - \li \l{Qt for X11 Requirements} - \li \l{Qt for macOS - Building from Source} - \endlist - - In addition, the following tools are required for building the \l {Qt WebEngine} module: - - \list - \li \l {All Platforms} - \li \l {Windows} - \li \l {Linux} - \li \l {macOS} - \endlist - - The tests for skipping the \QWE build are located in the - \c qtwebengine repository, in the \c tools\qmake\mkspecs subdirectory. - They can be found by searching for \c skipBuild. - - \section2 All Platforms - - On all platforms, the following tools are required at build time: - - \list - \li \l Python 2.7.5 or later. Python 3 is not supported. - \li Bison, Flex - \li GPerf - \li Node.js version 8 or later (version 12 or later is recommended) - \endlist - - \section2 Windows - - On Windows, the following additional tools are required: - - \list - \li Visual Studio 2017 version 15.8 or later, or clang-cl version 8 or later - \li Active Template Library (ATL), usually included in the Visual Studio - installation - \li Windows 10 SDK version 10.0.19041 or later - \endlist - - \QWE can only be built on 64-bit Windows, with a x64-bit toolchain. - For building \QWE for x86 applications, you need to configure - and compile Qt with the Visual Studio 2017 x64 to x86 cross-compile - toolchain. This toolchain can be set up on the command line by running - \c{vcvarsall.bat amd64_x86}. - - \section2 Linux - - On Linux, Clang or GCC version 5 or later is required. - Supported configurations are \c linux-g++, \c{linux-clang} and \c{linux-clang-libc++} - - \QWE requires \c pkg-config to detect most of its dependencies. The - following \c pkg-config files are required: - - \list - \li \c dbus-1 - \li \c fontconfig - \endlist - - If Qt was configured for \c xcb, the following \c pkg-config files are also - required: - - \list - \li \c libdrm - \li \c xcomposite - \li \c xcursor - \li \c xi - \li \c xrandr - \li \c xscrnsaver - \li \c xtst - \endlist - - Further, development packages for \c khr and \c libcap need to be installed. - - \section2 \macos - - On \macos, the following are required: - - \list - \li \macos 10.13 or later - \li Xcode 10.0 or later - \li \macos 10.13 SDK or later - \endlist - - \note \QWE cannot be built for the 32-bit mode of \macos (using the - \c macx-clang-32 \c mkspec). - - \section1 Using Earlier Qt Versions to Build \QWE - - Building \QWE with earlier Qt versions (down to the last LTS - version) is supported. It means that \QWE 5.15 can be built with - Qt 5.12.x, Qt 5.14.x, and Qt 5.15. - - To use an earlier Qt version to build Qt Webengine: - - \list 1 - \li Download the qtwebengine sources. - \li From the earlier Qt version, run - \c {qmake && make (&& make install)}. - \endlist - - \section1 Mac App Store Compatibility - - Applications using \QWE are not compatible with the Mac App Store, because: - - \list - \li The Chromium part of the code uses several private API methods, which are prohibited by - the App Store. - \li Applications submitted to the App Store must be code-signed with the App Sandbox feature - enabled. The App Sandbox feature interferes with Chromium's own sandbox - initialization, which results in Chromium not being properly initialized. This also - ties in with the private API usage. Furthermore, standalone Chromium itself is not - officially tested with the App Sandbox enabled, and even if work is done to bypass - the App Store's restrictions, that would not guarantee correct behavior of the library. - - \endlist - - \section1 macOS Airplay Support on MacBooks with Dual GPUs - - To make \QWE work correctly when streaming to an AppleTV from a MacBook that supports - GPU switching, it is important to add the \c NSSupportsAutomaticGraphicsSwitching option to the - application Info.plist file, with the value set to \c YES. Otherwise rendering issues might - occur when creating new web engine view instances after Airplay is switched on or off. - - \section1 Default QSurfaceFormat OpenGL Profile Support - - If a new default QSurfaceFormat with a modified OpenGL profile has to be set, it should be set - before the application instance is declared, to make sure that all created OpenGL contexts use - the same OpenGL profile. - - On \macos, if the default QSurfaceFormat is set after the application instance, the application - will exit with qFatal(), and print a message that the default QSurfaceFormat should be set - before the application instance. - - \section1 Sandboxing Support - - \QWE provides out-of-the-box sandboxing support for Chromium render - processes. - - On Linux, note the following restrictions: - - \list - \li The kernel has to support the anonymous namespaces feature - (kernel version 3.8 or later). However, on Debian, Ubuntu, - and other Debian-derived distributions, this feature is off - by default. It can be turned on by setting - \c /proc/sys/kernel/unprivileged_userns_clone to 1. - \li The kernel has to support the \c seccomp-bpf feature (kernel - version 3.5 or later). - \li Setuid sandboxes are not supported and are thus disabled. - \endlist - - To explicitly disable sandboxing, use one of the following options: - - \list - \li Set the \c QTWEBENGINE_DISABLE_SANDBOX environment variable to 1. - \li Pass the \c{--no-sandbox} command line argument to the user - application executable. - \li Set \c QTWEBENGINE_CHROMIUM_FLAGS to \c{--no-sandbox}. - \endlist - - For more information, see \l{Using Command-Line Arguments}. - - \section1 Memory Requirements in Docker Environment - - When running Qt Web Engine examples in a Docker container and browsing - content-heavy sites, BUS errors (SIGBUS) might be reported. Typically, - this is caused by Docker running a container with a too small memory space - (such as 64MB). To fix this problem, increase the memory space size. - - \section1 Accessibility and Performance - - \QWE enables accessibility support for web pages when the following conditions - are met: - - \list - \li Qt Core is configured and built with accessibility support enabled. - \li The QPA plugin is notified by the operating system that accessibility should be - activated. This happens for example when using a screen reader application on Windows - or VoiceOver on \macos. - \endlist - - Due to some limitations, the Linux QPA plugin almost always reports that accessibility should - be activated. On big HTML pages, this can cause a significant slowdown in rendering speed. - - Because of that, from Qt 5.9 onwards, \QWE accessibility support is disabled by default - on Linux. - It can be re-enabled by setting the \c QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY environment - variable to a non-empty value. - - \section1 Popups in Fullscreen Applications on Windows - Because of a limitation in the Windows compositor, applications that show a fullscreen web - engine view will not properly display popups or other top-level windows. The reason and - workaround for the issue can be found at \l {Fullscreen OpenGL Based Windows} and - \l {QWindowsWindowFunctions::setHasBorderInFullScreen}. - -*/ diff --git a/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc b/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc index 4fd7e3a3b..ecf3a4a6e 100644 --- a/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc +++ b/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc @@ -1,48 +1,29 @@ -/**************************************************************************** -** -** Copyright (C) 2018 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) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \qmlmodule QtWebEngine 1.10 + \qmlmodule QtWebEngine \title Qt WebEngine QML Types \brief Provides QML types for rendering web content within a QML application. \ingroup qtwebengine-modules \ingroup qmlmodules - The QML types can be imported into your application using the following import statements in - your .qml file: + To link against the module using build with qmake, + add the following QT variable to your qmake .pro file: - \qml - import QtWebEngine 1.10 - \endqml + \snippet qtwebengine_build_snippet.qdoc 0 - To link against the module, add the following QT variable to your qmake .pro - file: + 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: - \badcode - QT += webengine - \endcode + \snippet qtwebengine_build_snippet.qdoc 2 + + The minimal amount of code needed to load and display an HTML page using the QML engine + requires a proper initialization: + + \snippet minimal/main.cpp Minimal Example + + Where the content of main.qml is simply: + + \snippet minimal/main.qml Minimal Example */ diff --git a/src/webenginequick/doc/src/quota_request.qdoc b/src/webenginequick/doc/src/quota_request.qdoc index ee64c0484..01f4ec286 100644 --- a/src/webenginequick/doc/src/quota_request.qdoc +++ b/src/webenginequick/doc/src/quota_request.qdoc @@ -1,37 +1,17 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype QuotaRequest \instantiates QWebEngineQuotaRequest \inqmlmodule QtWebEngine \since QtWebEngine 1.7 + \deprecated [6.5] Requesting host quota is no longer supported by Chromium. - \brief A utility type for the WebEngineView::quotaRequested() signal. + The behavior of navigator.webkitPersistentStorage + is identical to navigator.webkitTemporaryStorage. + + For further details, see https://crbug.com/1233525 \sa WebEngineView::quotaRequested() */ @@ -39,36 +19,18 @@ /*! \qmlproperty url QuotaRequest::origin \readonly - - The URL of the web page that issued the quota request. */ /*! \qmlproperty qint64 QuotaRequest::requestedSize \readonly - - Contains the size of the requested disk space in bytes. */ /*! \qmlmethod void QuotaRequest::accept() - - Accepts the quota request. - - \qml - WebEngineView { - onQuotaRequested: function(request) { - if (request.requestedSize <= 5 * 1024 * 1024) - request.accept(); - else - request.reject(); - } - } - \endqml */ /*! \qmlmethod void QuotaRequest::reject() - Rejects the quota request. */ diff --git a/src/webenginequick/doc/src/qwebengine-licensing.qdoc b/src/webenginequick/doc/src/qwebengine-licensing.qdoc deleted file mode 100644 index f6a0a6c32..000000000 --- a/src/webenginequick/doc/src/qwebengine-licensing.qdoc +++ /dev/null @@ -1,53 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\group qtwebengine-licensing -\title Qt WebEngine Licensing - -The Qt specific parts of the \QWE module are dual-licensed -under Commercial and GNU Lesser General Public License (LGPLv3). -In addition, the module contains code licensed under LGPLv2. - -The module includes a snapshot of Chromium. As such, users need to -respect the licenses of Chromium, and third-party code included in -Chromium. The arguably most restrictive license to be respected by -all users is LGPLv2.1. - -Third party licenses included in the sources are: -*/ - -/*! -\page qtwebengine-3rdparty-chromium-global.html attribution -\ingroup qtwebengine-licensing -\title Chromium License -\brief BSD - -The Google-authored portion of Chromium is released under a BSD license: - -\quotefile ../../../3rdparty/chromium/LICENSE -*/ diff --git a/src/webenginequick/doc/src/register_protocol_handler_request.qdoc b/src/webenginequick/doc/src/register_protocol_handler_request.qdoc index b3ebcb31b..d69f4d264 100644 --- a/src/webenginequick/doc/src/register_protocol_handler_request.qdoc +++ b/src/webenginequick/doc/src/register_protocol_handler_request.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype RegisterProtocolHandlerRequest diff --git a/src/webenginequick/doc/src/touch_selection_menu_request.qdoc b/src/webenginequick/doc/src/touch_selection_menu_request.qdoc new file mode 100644 index 000000000..9ca6ed36b --- /dev/null +++ b/src/webenginequick/doc/src/touch_selection_menu_request.qdoc @@ -0,0 +1,79 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype TouchSelectionMenuRequest + //! \instantiates QQuickWebEngineTouchSelectionMenuRequest + \inqmlmodule QtWebEngine + \since QtWebEngine 6.3 + + \brief A request for showing a touch selection menu. + + A TouchSelectionMenuRequest is passed as an argument of the + WebEngineView::touchSelectionMenuRequest signal. It provides further + information about the context of the request. The \l selectionBounds + property provides the origin of the request. + + The \l accepted property of the request indicates whether the request + is handled by the user code or the default touch selection menu should + be displayed. + + The following code uses a custom menu to handle the request: + + \code + WebEngineView { + id: view + // ... + onTouchSelectionMenuRequested: function(request) { + request.accepted = true; + myMenu.x = request.selectionBounds.x; + myMenu.y = request.selectionBounds.y; + myMenu.trigger.connect(view.triggerWebAction); + myMenu.popup(); + } + // ... + } + \endcode +*/ + +/*! + \qmlproperty rect TouchSelectionMenuRequest::selectionBounds + \readonly + + The position of the bound rectangle from the touch text + selection. +*/ + +/*! + \qmlproperty bool TouchSelectionMenuRequest::accepted + + Indicates whether the touch selection menu request has + been handled by the signal handler. + + If the property is \c false after any signal handlers + for WebEngineView::touchSelectionMenuRequested have been executed, + a default touch selection menu will be shown. + To prevent this, set \c{request.accepted} to \c true. + + The default is \c false. + + \note The default content of the touch selection menu depends + on the web element for which the request was actually generated. +*/ + + +/*! + \qmlproperty flags QQuickWebEngineTouchSelectionMenuRequest::touchSelectionCommandFlags + \readonly + \since QtWebEngine 6.3 + + \note In the default touch selection menu, showing the context menu + is always available as a separate action. + + \value QQuickWebEngineTouchSelectionMenuRequest.Cut + Cut is available. + \value QQuickWebEngineTouchSelectionMenuRequest.Copy + Copy is available. + \value QQuickWebEngineTouchSelectionMenuRequest.Paste + Paste is available. +*/ diff --git a/src/webenginequick/doc/src/webengine_certificate_error.qdoc b/src/webenginequick/doc/src/webengine_certificate_error.qdoc index 8c032dc8b..93bad9fb1 100644 --- a/src/webenginequick/doc/src/webengine_certificate_error.qdoc +++ b/src/webenginequick/doc/src/webengine_certificate_error.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype WebEngineCertificateError @@ -33,18 +9,18 @@ \brief A utility type for ignoring certificate errors or rejecting erroneous certificates. - This QML type contains information about a certificate error that occurred. The \l error + This QML type contains information about a certificate error that occurred. The \l type property holds the reason that the error occurred and the \l description property holds a short localized description of the error. The \l url property holds the URL that triggered the error. - The certificate can be rejected by calling \l rejectCertificate, which will stop loading the + The certificate can be rejected by calling \l rejectCertificate(), which will stop loading the web engine request. By default, an invalid certificate will be automatically rejected. - The certificate error can be ignored by calling \l ignoreCertificateError, which will + The certificate error can be ignored by calling \l acceptCertificate(), which will resume loading the request. - It is possible to defer the decision of rejecting a certificate by calling \l defer, + It is possible to defer the decision of rejecting a certificate by calling \l defer(), which is useful when waiting for user input. \sa WebEngineView::certificateError @@ -54,11 +30,10 @@ This function should be called when there is a need to postpone the decision whether to ignore a certificate error, for example, while waiting for user input. When called, the function pauses the - URL request until WebEngineCertificateError::ignoreCertificateError() or - WebEngineCertificateError::rejectCertificate() is called. + URL request until acceptCertificate() or rejectCertificate() is called. */ /*! - \qmlmethod void WebEngineCertificateError::ignoreCertificateError() + \qmlmethod void WebEngineCertificateError::acceptCertificate() The certificate error is ignored, and the web engine view continues to load the requested URL. */ @@ -74,7 +49,7 @@ The URL that triggered the error. */ /*! - \qmlproperty enumeration WebEngineCertificateError::error + \qmlproperty enumeration WebEngineCertificateError::type \readonly The type of the error. diff --git a/src/webenginequick/doc/src/webengine_download_request.qdoc b/src/webenginequick/doc/src/webengine_download_request.qdoc index 845a8ff07..96d84e0a3 100644 --- a/src/webenginequick/doc/src/webengine_download_request.qdoc +++ b/src/webenginequick/doc/src/webengine_download_request.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \qmltype WebEngineDownloadRequest diff --git a/src/webenginequick/doc/src/webenginescript.qdoc b/src/webenginequick/doc/src/webenginescript.qdoc new file mode 100644 index 000000000..9708ffbf8 --- /dev/null +++ b/src/webenginequick/doc/src/webenginescript.qdoc @@ -0,0 +1,98 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype WebEngineScript + \instantiates QWebEngineScript + \brief Enables the programmatic injection of scripts in the JavaScript engine. + \since QtWebEngine 1.1 + \ingroup qmlvaluetypes + \inqmlmodule QtWebEngine + + The WebEngineScript type enables the programmatic injection of so called \e {user scripts} in + the JavaScript engine at different points, determined by injectionPoint, during the loading of + web content. + + Scripts can be executed 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. The worldId property provides some predefined IDs for this + purpose. + + The following \l Greasemonkey attributes are supported: + \c @exclude, \c @include, \c @name, \c @match, and \c @run-at. + + Use \l{WebEngineScriptCollection} to access a list of scripts attached to the web view. +*/ + +/*! + \qmlproperty string WebEngineScript::name + + The name of the script. Can be useful to retrieve a particular script from + \l{WebEngineScriptCollection::find}{WebEngineScriptCollection.find} method. +*/ + +/*! + \qmlproperty url WebEngineScript::sourceUrl + + This property holds the remote source location of the user script (if any). + + Unlike \l sourceCode, this property allows referring to user scripts that + are not already loaded in memory, for instance, when stored on disk. + + Setting this property will change the \l sourceCode of the script. + + \note At present, only file-based sources are supported. + + \sa sourceCode +*/ + +/*! + \qmlproperty string WebEngineScript::sourceCode + + This property holds the JavaScript source code of the user script. + + \sa sourceUrl +*/ + +/*! + \qmlproperty enumeration WebEngineScript::injectionPoint + + The point in the loading process at which the script will be executed. + The default value is \c Deferred. + + \value WebEngineScript.DocumentCreation + The script will be executed as soon as the document is created. This is not suitable for + any DOM operation. + \value WebEngineScript.DocumentReady + The script will run as soon as the DOM is ready. This is equivalent to the + \c DOMContentLoaded event firing in JavaScript. + \value WebEngineScript.Deferred + The script will run when the page load finishes, or 500 ms after the document is ready, + whichever comes first. +*/ + +/*! + \qmlproperty enumeration WebEngineScript::worldId + + The world ID defining which isolated world the script is executed in. + + \value WebEngineScript.MainWorld + The world used by the page's web contents. It can be useful in order to expose custom + functionality to web contents in certain scenarios. + \value WebEngineScript.ApplicationWorld + The default isolated world used for application level functionality implemented in + JavaScript. + \value WebEngineScript.UserWorld + The first isolated world to be used by scripts set by users if the application is not + making use of more worlds. As a rule of thumb, if that functionality is exposed to the + application users, each individual script should probably get its own isolated world. +*/ + +/*! + \qmlproperty int WebEngineScript::runOnSubframes + + Set this property to \c true if the script is executed on every frame in the page, or \c false + if it is only ran for the main frame. + The default value is \c{false}. +*/ diff --git a/src/webenginequick/doc/src/webengineview_lgpl.qdoc b/src/webenginequick/doc/src/webengineview_lgpl.qdoc index 7c13d140a..eeae34dcc 100644 --- a/src/webenginequick/doc/src/webengineview_lgpl.qdoc +++ b/src/webenginequick/doc/src/webengineview_lgpl.qdoc @@ -1,24 +1,7 @@ -/* - * Copyright (C) 2019 The Qt Company Ltd. - * Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies) - * Copyright (c) 2012 Hewlett-Packard Development Company, L.P. - * - * 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 program 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 program; see the file COPYING.LIB. If not, write to - * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - * Boston, MA 02110-1301, USA. - * - */ +// Copyright (C) 2019 The Qt Company Ltd. +// Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies) +// Copyright (c) 2012 Hewlett-Packard Development Company, L.P. +// 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. @@ -41,7 +24,7 @@ \l QtWebEngineQuick::initialize in the application main source file, as illustrated by the following code snippet: - \quotefromfile webengine/minimal/main.cpp + \quotefromfile minimal/main.cpp \skipto main \printuntil } @@ -56,7 +39,7 @@ The following sample QML application loads a web page using the \c url property: - \quotefromfile webengine/minimal/main.qml + \quotefromfile minimal/main.qml \skipto import \printuntil /^\}/ @@ -74,10 +57,10 @@ \section2 Interaction 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 \l newViewRequested() signal + may request them to be opened as a new tab, window, or dialog. The \l newWindowRequested() signal is emitted when a request to load the page in a separate web engine view is issued. The NewViewDestination property describes how the new view should be opened. In addition, the - WebEngineNewViewRequest utility type can be used to load web pages in separate web engine views. + WebEngineNewWindowRequest utility type can be used to load web pages in separate web engine views. The \l findText() method can be used to search for a string on a web page, using the options described by \l FindFlags. @@ -327,11 +310,13 @@ /*! - \qmlproperty list<WebEngineScript> WebEngineView::userScripts + \qmlproperty WebEngineScriptCollection WebEngineView::userScripts \readonly \since QtWebEngine 1.1 - List of WebEngineScript objects attached to the view. + The user scripts' collection associated with the view. + + \sa WebEngineScriptCollection */ /*! @@ -371,9 +356,8 @@ This method offers a lower-level alternative to the \c{url} property, which references HTML pages via URL. - External objects, such as stylesheets or images referenced in the HTML - document, should be located relative to \a baseUrl. For external objects to - be loaded, \c baseUrl cannot be empty. For example, if \a html + \a baseUrl is optional and used to resolve relative URLs in the document, + such as referenced images or stylesheets. For example, if \a html is retrieved from \c http://www.example.com/documents/overview.html, which is the base URL, then an image referenced with the relative URL, \c diagram.png, should be at \c{http://www.example.com/documents/diagram.png}. @@ -570,8 +554,8 @@ */ /*! - \qmlsignal WebEngineView::newViewRequested(WebEngineNewViewRequest request) - \since QtWebEngine 1.1 + \qmlsignal WebEngineView::newWindowRequested(WebEngineNewWindowRequest request) + \since QtWebEngine 2.0 This signal is emitted when \a request is issued to load a page in a separate web engine view. This can either be because the current page requested it explicitly @@ -579,23 +563,23 @@ while holding Shift, Ctrl, or a built-in combination that triggers the page to open in a new window. - The signal is handled by calling acceptAsNewView() on the destination view. + The signal is handled by calling acceptAsNewWindow() on the destination view. If this signal is not handled, the requested load will fail. An example implementation: \snippet qtwebengine_webengineview_newviewrequested.qml 0 - \sa WebEngineNewViewRequest, {WebEngine Quick Nano Browser} + \sa WebEngineNewWindowRequest, {WebEngine Quick Nano Browser} */ /*! - \qmlmethod void WebEngineView::acceptAsNewView(QWebEngineNewWindowRequest *request) + \qmlmethod void WebEngineView::acceptAsNewWindow(QWebEngineNewWindowRequest *request) \since QtWebEngine 2.0 - Handle the newViewRequested signal by opening the \a request in this view. + Handle the newWindowRequested signal by opening the \a request in this view. - \sa newViewRequested + \sa newWindowRequested */ /*! @@ -765,10 +749,10 @@ Open the current link in the current window. (Added in Qt 5.6) \value WebEngineView.OpenLinkInNewWindow Open the current link in a new window. Requires a handler for the - \l newViewRequested() signal. (Added in Qt 5.6) + \l newWindowRequested() signal. (Added in Qt 5.6) \value WebEngineView.OpenLinkInNewTab Open the current link in a new tab. Requires a handler for the - \l newViewRequested() signal. (Added in Qt 5.6) + \l newWindowRequested() signal. (Added in Qt 5.6) \value WebEngineView.CopyLinkToClipboard Copy the current link to the clipboard. (Added in Qt 5.6) \value WebEngineView.CopyImageToClipboard @@ -802,9 +786,10 @@ Exit the fullscreen mode. (Added in Qt 5.6) \value WebEngineView.SavePage Save the current web page to disk. (Added in Qt 5.7) + \omitvalue WebEngineView.OpenLinkInNewBackgroundTab \value WebEngineView.ViewSource Show the source of the current page in a new tab. Requires a handler for the - \l newViewRequested() signal. (Added in Qt 5.8) + \l newWindowRequested() signal. (Added in Qt 5.8) \value WebEngineView.ToggleBold Toggles boldness for the selection or at the cursor position. @@ -846,6 +831,10 @@ Inserts an unordered list at the current cursor position, deleting the current selection. Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.ChangeTextDirectionLTR + Changes text direction to left-to-right in the focused input element. (Added in Qt 6.6) + \value WebEngineView.ChangeTextDirectionRTL + Changes text direction to right-to-left in the focused input element. (Added in Qt 6.6) \omitvalue WebActionCount */ @@ -863,13 +852,22 @@ Video devices, such as cameras. \value WebEngineView.MediaAudioVideoCapture Both audio and video capture devices. - \value DesktopVideoCapture + \value WebEngineView.DesktopVideoCapture Video output capture, that is, the capture of the user's display. (Added in Qt 5.10) - \value DesktopAudioVideoCapture + \value WebEngineView.DesktopAudioVideoCapture Both audio and video output capture. (Added in Qt 5.10) - \value WebEnginView.Notifications + \value WebEngineView.Notifications Web notifications for the end-user. + \value WebEngineView.ClipboardReadWrite + Read and write access for the clipboard. If both \l{WebEngineSettings::JavascriptCanPaste} + {JavascriptCanPaste} and \l{WebEngineSettings::JavascriptCanAccessClipboard} + {JavascriptCanAccessClipboard} settings are enabled, this permission will always be granted + automatically and no feature requests will be made. + (Added in Qt 6.8) + \value WebEngineView.LocalFontsAccess + Access to the fonts installed on the user's machine. Only available on desktop platforms. + (Added in Qt 6.8) \sa featurePermissionRequested(), grantFeaturePermission() */ @@ -1011,8 +1009,6 @@ \value WebEngineView.EnvelopePrc10 \value WebEngineView.EnvelopeYou4 \value WebEngineView.LastPageSize = \c EnvelopeYou4 - \omitvalue NPageSize - \omitvalue NPaperSize \sa WebEngineView::printToPdf() */ @@ -1090,8 +1086,6 @@ Also if the audio is paused, this signal is emitted with an approximate \b{two-second delay}, from the moment the audio is paused. - This signal is also emitted for Flash plugin audio. - If a web page contains two videos that are started in sequence, this signal gets emitted only once, for the first video to generate sound. After both videos are stopped, the signal is emitted upon the last sound generated. @@ -1167,8 +1161,6 @@ \a wasRecentlyAudible, is changed, due to audio being played or stopped. \note The signal is also emitted when calling the setAudioMuted method. - Also if the audio is paused, this signal is emitted with an approximate \b{2 second - delay}, from the moment the audio is paused. */ /*! @@ -1249,10 +1241,13 @@ /*! \qmlsignal WebEngineView::quotaRequested(QuotaRequest request) \since QtWebEngine 1.7 + \deprecated [6.5] This signal is no longer emitted. + + Requesting host quota is no longer supported by Chromium. + The behavior of navigator.webkitPersistentStorage + is identical to navigator.webkitTemporaryStorage. - This signal is emitted when the web page issues a \a request for a larger persistent storage - than the application's current allocation in File System API. The default quota - is 0 bytes. + For further details, see https://crbug.com/1233525 \sa QuotaRequest */ @@ -1316,6 +1311,20 @@ */ /*! + \qmlproperty WebEngineView WebEngineView::devToolsId + \since QtWebEngine 6.6 + \readonly + + The id of the developer tools host associated with this page. + + If remote debugging is enabled (see \l{Qt WebEngine Developer Tools}), the id can be used to + build the URL to connect to the developer tool websocket: + \c{ws://localhost:<debugggin-port>/devtools/page/<id>)}. The websocket can be used to to interact + with the page using the \l{https://chromedevtools.github.io/devtools-protocol/}{DevTools + Protocol}. +*/ + +/*! \qmlmethod WebEngineAction WebEngineView::action(WebAction action) \since 5.12 @@ -1331,10 +1340,11 @@ */ /*! - \qmlsignal WebEngineView::printRequest + \qmlsignal WebEngineView::printRequested \since QtWebEngine 1.8 - This signal is emitted when the JavaScript \c{window.print()} method is called. + This signal is emitted when the JavaScript \c{window.print()} method is called or the user pressed the print + button of PDF viewer plugin. Typically, the signal handler can simply call printToPdf(). \sa printToPdf @@ -1477,3 +1487,99 @@ \sa renderProcessPid */ + +/*! + \qmlsignal WebEngineView::touchSelectionMenuRequested(TouchSelectionMenuRequest *request) + \since QtWebEngine 6.3 + \readonly + + This signal is emitted when a touch selection menu is requested at a specified position. + + The \a request can be handled by using the methods of the TouchSelectionMenuRequest + type. + + \note Signal handlers need to call \c{request.accepted = true} to prevent a default touch + selection menu from showing up. + + \sa TouchSelectionMenuRequest +*/ + +/*! + \qmlproperty Component WebEngineView::touchHandleDelegate + \since QtWebEngine 6.4 + + The \a touchHandleDelegate provides a template defining visual touch handles instantiated by the view + whenever touch selection handling is required. + + The handle's position, opacity, and visibility are updated automatically. + The delegate should be a QML Item or any QML type which inherits it. + + \note If no QML Item is set, the default touch handles will be shown. + + The following code uses a custom touch handle delegate: + + \code + WebEngineView { + // ... + touchHandleDelegate: Rectangle { + color: "red" + } + // ... + } + \endcode + + The touch handles can be also switched dynamically: + + \code + Component { + id: circleTouchHandle + Rectangle { + color: "blue" + radius: 50 + } + } + function showDefaultHandle(isDefault) { + if (isDefault) + webEngineView.touchHandleDelegate = circleTouchHandle + else + webEngineView.touchHandleDelegate = null + } + \endcode + + \note If no delegate is provided, Chromium's default touch handles will appear. + +*/ + +/*! + \qmlmethod void WebEngineView::save(const QString &filePath, QWebEngineDownloadRequest::SavePageFormat format) + \since QtWebEngine 6.6 + + Save the current web page to disk. + + The web page is saved to \a filePath in the specified \a{format}. + + This is a shortcut for the following actions: + \list + \li Trigger the Save web action. + \li Accept the next download item and set the specified file path and save format. + \endlist + + This function issues an asynchronous download request for the web page and returns immediately. + + \sa QWebEngineDownloadRequest::SavePageFormat +*/ + +/*! + \qmlsignal WebEngineView::webAuthUxRequested(QWebEngineWebAuthUxRequest *request); + \since QtWebEngine 6.7 + + This signal is emitted when a WebAuth authenticator requires 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 +*/ + + \sa {WebEngine Qt Quick Custom Touch Handle Example} +*/ |