diff options
Diffstat (limited to 'src/webenginequick/doc/src')
16 files changed, 3044 insertions, 0 deletions
diff --git a/src/webenginequick/doc/src/context_menu_request.qdoc b/src/webenginequick/doc/src/context_menu_request.qdoc new file mode 100644 index 000000000..e7d732d5e --- /dev/null +++ b/src/webenginequick/doc/src/context_menu_request.qdoc @@ -0,0 +1,194 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype ContextMenuRequest + //! \instantiates QQuickWebEngineContextMenuRequest + \inqmlmodule QtWebEngine + \since QtWebEngine 1.4 + + \brief A request for showing a context menu. + + A ContextMenuRequest is passed as an argument of the + WebEngineView::contextMenuRequested signal. It provides further + information about the context of the request. The \l position + 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 context menu should + be displayed. + + The following code uses a custom menu to handle the request: + + \code + WebEngineView { + id: view + // ... + onContextMenuRequested: function(request) { + request.accepted = true; + myMenu.x = request.x; + myMenu.y = request.y; + myMenu.trigger.connect(view.triggerWebAction); + myMenu.popup(); + } + // ... + } + \endcode +*/ + +/*! + \qmlproperty point ContextMenuRequest::position + \readonly + + The position of the user action from where the context + menu request originates. +*/ + +/*! + \qmlproperty string ContextMenuRequest::selectedText + \readonly + + The selected text the context menu was created for. +*/ + +/*! + \qmlproperty string ContextMenuRequest::linkText + \readonly + + The text of the link if the context menu was requested for a link. +*/ + +/*! + \qmlproperty url ContextMenuRequest::linkUrl + \readonly + + The URL of the link if the selected web page content is a link. + It is not guaranteed to be a valid URL. +*/ + +/*! + \qmlproperty url ContextMenuRequest::mediaUrl + \readonly + + The URL of media if the selected web content is a media element. +*/ + +/*! + \qmlproperty enumeration ContextMenuRequest::mediaType + \readonly + + The type of the media element or \c MediaTypeNone if + the selected web page content is not a media element. + + \value ContextMenuRequest.MediaTypeNone + Not a media. + \value ContextMenuRequest.MediaTypeImage + An image. + \value ContextMenuRequest.MediaTypeVideo + A video. + \value ContextMenuRequest.MediaTypeAudio + An audio element. + \value ContextMenuRequest.MediaTypeCanvas + A canvas. + \value ContextMenuRequest.MediaTypeFile + A file. + \value ContextMenuRequest.MediaTypePlugin + A plugin. +*/ + +/*! + \qmlproperty bool ContextMenuRequest::isContentEditable + \readonly + + Indicates whether the selected web content is editable. +*/ + +/*! + \qmlproperty string ContextMenuRequest::misspelledWord + \readonly + + If the context is a word considered misspelled by the spell-checker, + returns the misspelled word. +*/ + +/*! + \qmlproperty stringlist ContextMenuRequest::spellCheckerSuggestions + \readonly + + If the context is a word considered misspelled by the spell-checker, + returns a list of suggested replacements. +*/ + +/*! + \qmlproperty bool ContextMenuRequest::accepted + + Indicates whether the context menu request has been + handled by the signal handler. + + If the property is \c false after any signal handlers + for WebEngineView::contextMenuRequested have been executed, + a default context 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 context menu depends on the + web element for which the request was actually generated. +*/ + +/*! + \qmlproperty flags ContextMenuRequest::mediaFlags + \readonly + \since QtWebEngine 1.7 + + The current media element's status and its available operations. + \c MediaNone if the selected web page content is not a media element. + + \value ContextMenuRequest.MediaInError + An error occurred. + \value ContextMenuRequest.MediaPaused + Media is paused. + \value ContextMenuRequest.MediaMuted + Media is muted. + \value ContextMenuRequest.MediaLoop + Media can be looped. + \value ContextMenuRequest.MediaCanSave + Media can be saved. + \value ContextMenuRequest.MediaHasAudio + Media has audio. + \value ContextMenuRequest.MediaCanToggleControls + Media can show controls. + \value ContextMenuRequest.MediaControls + Media controls are shown. + \value ContextMenuRequest.MediaCanPrint + Media is printable. + \value ContextMenuRequest.MediaCanRotate + Media is rotatable. +*/ + +/*! + \qmlproperty flags ContextMenuRequest::editFlags + \readonly + \since QtWebEngine 1.7 + + The available edit operations in the current context or \c CanDoNone if no actions are available. + + \value ContextMenuRequest.CanUndo + Undo is available. + \value ContextMenuRequest.CanRedo + Redo is available. + \value ContextMenuRequest.CanCut + Cut is available. + \value ContextMenuRequest.CanCopy + Copy is available. + \value ContextMenuRequest.CanPaste + Paste is available. + \value ContextMenuRequest.CanDelete + Delete is available. + \value ContextMenuRequest.CanSelectAll + Select All is available. + \value ContextMenuRequest.CanTranslate + Translate is available. + \value ContextMenuRequest.CanEditRichly + Context is richly editable. +*/ diff --git a/src/webenginequick/doc/src/fullscreen_request.qdoc b/src/webenginequick/doc/src/fullscreen_request.qdoc new file mode 100644 index 000000000..60da2748c --- /dev/null +++ b/src/webenginequick/doc/src/fullscreen_request.qdoc @@ -0,0 +1,58 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype FullScreenRequest + \instantiates QWebEngineFullScreenRequest + \inqmlmodule QtWebEngine + \since QtWebEngine 1.1 + + \brief A utility type for the WebEngineView::fullScreenRequested() signal. + + \sa WebEngineView::fullScreenRequested() +*/ + +/*! + \qmlproperty url FullScreenRequest::origin + \readonly + The URL of the web page that issued the fullscreen request. +*/ + +/*! + \qmlproperty bool FullScreenRequest::toggleOn + \readonly + + Returns \c{true} if the application should toggle fullscreen mode on, \c{false} otherwise. + + \sa accept() +*/ + +/*! + \qmlmethod void FullScreenRequest::accept() + + Call this method to accept the fullscreen request. It sets the WebEngineView::isFullScreen + property to be equal to toggleOn. + + \qml + ApplicationWindow { + id: window + WebEngineView { + onFullScreenRequested: function(request) { + if (request.toggleOn) + window.showFullScreen() + else + window.showNormal() + request.accept() + } + } + } + \endqml + + \sa toggleOn +*/ + +/*! + \qmlmethod void FullScreenRequest::reject() + Rejects a fullscreen request. +*/ + diff --git a/src/webenginequick/doc/src/loading_info.qdoc b/src/webenginequick/doc/src/loading_info.qdoc new file mode 100644 index 000000000..c97799e24 --- /dev/null +++ b/src/webenginequick/doc/src/loading_info.qdoc @@ -0,0 +1,64 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype WebEngineLoadingInfo + \instantiates QWebEngineLoadingInfo + \inqmlmodule QtWebEngine + \since QtWebEngine 1.0 + + \brief A utility type for the WebEngineView::loadingChanged signal. + + Contains information about a request for loading a web page, such as the URL and + current loading status (started, succeeded, failed). + + \sa WebEngineView::loadingChanged +*/ +/*! + \qmlproperty url WebEngineLoadingInfo::url + \brief Holds the URL of the load request. + */ +/*! + \qmlproperty enumeration WebEngineLoadingInfo::status + + This enumeration represents the load status of a web page load request: + + \value WebEngineView.LoadStartedStatus Page is currently loading. + \value WebEngineView.LoadStoppedStatus + Loading the page was stopped by the stop() method or by the loader + code or network stack in Chromium. + \value WebEngineView.LoadSucceededStatus + Page has been loaded with success. + \value WebEngineView.LoadFailedStatus Page could not be loaded. + + \sa WebEngineView::loadingChanged +*/ +/*! + \qmlproperty string WebEngineLoadingInfo::errorString + \brief Holds the error message. +*/ +/*! + \qmlproperty enumeration WebEngineLoadingInfo::errorDomain + This enumeration holds the type of a load request error: + + \value WebEngineLoadingInfo.NoErrorDomain + Error type is not known. + \value WebEngineLoadingInfo.InternalErrorDomain + Content cannot be interpreted by \QWE. + \value WebEngineLoadingInfo.ConnectionErrorDomain + Error results from a faulty network connection. + \value WebEngineLoadingInfo.CertificateErrorDomain + Error is related to the SSL/TLS certificate. + \value WebEngineLoadingInfo.HttpErrorDomain + Error is related to the HTTP connection. + \value WebEngineLoadingInfo.FtpErrorDomain + 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 + \brief Holds the error code. +*/ diff --git a/src/webenginequick/doc/src/navigation_history.qdoc b/src/webenginequick/doc/src/navigation_history.qdoc new file mode 100644 index 000000000..94876799d --- /dev/null +++ b/src/webenginequick/doc/src/navigation_history.qdoc @@ -0,0 +1,113 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype WebEngineHistoryModel + \instantiates QWebEngineHistoryModel + \inqmlmodule QtWebEngine + \since QtWebEngine 1.1 + + \brief A data model that represents the history of a web engine page. + + The WebEngineHistoryModel type exposes the \e title, \e url, \e icon, and \e offset roles. + The \e title, \e url and \e icon specify the title, URL, and favicon of the visited page. + The \e offset specifies + the position of the page in respect to the current page (0). A positive number indicates that + the page was visited after the current page, whereas a negative number indicates that the page + was visited before the current page. + + This type is uncreatable, but it can be accessed by using the + \l{WebEngineView::history}{WebEngineView.history} property. + + \sa WebEngineHistory +*/ + +/*! + \qmltype WebEngineHistory + \instantiates QWebEngineHistory + \inqmlmodule QtWebEngine + \since QtWebEngine 1.1 + + \brief Provides data models that represent the history of a web engine page. + + The WebEngineHistory type can be accessed by using the + \l{WebEngineView::history}{WebEngineView.history} property. + + The WebEngineHistory type provides the following WebEngineHistoryModel data model objects: + + \list + \li \c backItems, which contains the URLs of visited pages. + \li \c forwardItems, which contains the URLs of the pages that were visited after visiting + the current page. + \li \c items, which contains the URLs of the back and forward items, as well as the URL of + the current page. + \endlist + + The easiest way to use these models is to use them in a ListView as illustrated by the + following code snippet: + + \code + ListView { + id: historyItemsList + anchors.fill: parent + model: webEngineView.history.items + delegate: + Text { + color: "black" + text: model.title + " - " + model.url + " (" + model.offset + ")" + } + } + \endcode + + The ListView shows the content of the corresponding model. The delegate is responsible for the + format of the list items. The appearance of each item of the list in the delegate can be defined + separately (it is not web engine specific). + + The model roles \e title, \e url, and \e icon specify the title, URL, and favicon of the + visited page. The \e offset + role specifies the position of the page in respect to the current page (0). A positive number + indicates that the page was visited after the current page, whereas a negative number indicates + that the page was visited before the current page. + + The data models can also be used to create a menu, as illustrated by the following code + snippet: + + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml + \skipto ToolBar + \printuntil onObjectRemoved + \printuntil } + \printuntil } + \printuntil } + + For the complete example, see \l{WebEngine Quick Nano Browser}. + + \sa WebEngineHistoryModel +*/ + +/*! + \qmlproperty WebEngineHistoryModel WebEngineHistory::items + \readonly + + URLs of back items, forward items, and the current item in the history. +*/ + +/*! + \qmlproperty WebEngineHistoryModel WebEngineHistory::backItems + \readonly + + URLs of visited pages. +*/ + +/*! + \qmlproperty WebEngineHistoryModel WebEngineHistory::forwardItems + \readonly + + URLs of the pages that were visited after visiting the current page. +*/ + +/*! + \qmlmethod void WebEngineHistory::clear() + \since QtWebEngine 1.11 + + Clears the history. +*/ diff --git a/src/webenginequick/doc/src/qtwebengine-examples.qdoc b/src/webenginequick/doc/src/qtwebengine-examples.qdoc new file mode 100644 index 000000000..eebf18ba1 --- /dev/null +++ b/src/webenginequick/doc/src/qtwebengine-examples.qdoc @@ -0,0 +1,15 @@ +// 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 Quick Examples + \brief Examples demonstrating the \QWE usage. + + 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 + a basic function Web browser. + + For widget-based applications, Qt provides an integrated Web browser component based on + Chromium, the popular open source browser engine. +*/ diff --git a/src/webenginequick/doc/src/qtwebengine-module.qdoc b/src/webenginequick/doc/src/qtwebengine-module.qdoc new file mode 100644 index 000000000..6f50cc2f4 --- /dev/null +++ b/src/webenginequick/doc/src/qtwebengine-module.qdoc @@ -0,0 +1,25 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \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 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-qmlmodule.qdoc b/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc new file mode 100644 index 000000000..ecf3a4a6e --- /dev/null +++ b/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc @@ -0,0 +1,29 @@ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmlmodule QtWebEngine + \title Qt WebEngine QML Types + \brief Provides QML types for rendering web content within a QML application. + \ingroup qtwebengine-modules + \ingroup qmlmodules + + To link against the module using build with qmake, + add the following QT variable to your qmake .pro 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 + + 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 new file mode 100644 index 000000000..01f4ec286 --- /dev/null +++ b/src/webenginequick/doc/src/quota_request.qdoc @@ -0,0 +1,36 @@ +// 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. + + The behavior of navigator.webkitPersistentStorage + is identical to navigator.webkitTemporaryStorage. + + For further details, see https://crbug.com/1233525 + + \sa WebEngineView::quotaRequested() +*/ + +/*! + \qmlproperty url QuotaRequest::origin + \readonly +*/ + +/*! + \qmlproperty qint64 QuotaRequest::requestedSize + \readonly +*/ + +/*! + \qmlmethod void QuotaRequest::accept() +*/ + +/*! + \qmlmethod void QuotaRequest::reject() +*/ + diff --git a/src/webenginequick/doc/src/register_protocol_handler_request.qdoc b/src/webenginequick/doc/src/register_protocol_handler_request.qdoc new file mode 100644 index 000000000..d69f4d264 --- /dev/null +++ b/src/webenginequick/doc/src/register_protocol_handler_request.qdoc @@ -0,0 +1,42 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype RegisterProtocolHandlerRequest + \instantiates QWebEngineRegisterProtocolHandlerRequest + \inqmlmodule QtWebEngine + \since QtWebEngine 1.7 + \brief The RegisterProtocolHandlerRequest type enables accepting + or rejecting requests from the \l registerProtocolHandler API. + + \sa WebEngineView::registerProtocolHandlerRequested() +*/ + +/*! + \qmlproperty url RegisterProtocolHandlerRequest::origin + \brief The URL template for the protocol handler. + + This is the second parameter from the \l registerProtocolHandler call. +*/ + +/*! + \qmlproperty string RegisterProtocolHandlerRequest::scheme + \brief The URL scheme for the protocol handler. + + This is the first parameter from the \l registerProtocolHandler call. +*/ + +/*! + \qmlmethod void RegisterProtocolHandlerRequest::accept() + \brief Accepts the request. + + Subsequent calls to accept() and reject() are ignored. +*/ + +/*! + \qmlmethod void RegisterProtocolHandlerRequest::reject() + \brief Accepts the request. + + Subsequent calls to accept() and reject() are ignored. +*/ + 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 new file mode 100644 index 000000000..93bad9fb1 --- /dev/null +++ b/src/webenginequick/doc/src/webengine_certificate_error.qdoc @@ -0,0 +1,108 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype WebEngineCertificateError + \instantiates QWebEngineCertificateError + \inqmlmodule QtWebEngine + \since QtWebEngine 1.1 + + \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 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 + web engine request. By default, an invalid certificate will be automatically rejected. + + 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(), + which is useful when waiting for user input. + + \sa WebEngineView::certificateError +*/ +/*! + \qmlmethod void WebEngineCertificateError::defer() + + 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 acceptCertificate() or rejectCertificate() is called. + */ +/*! + \qmlmethod void WebEngineCertificateError::acceptCertificate() + + The certificate error is ignored, and the web engine view continues to load the requested URL. + */ +/*! + \qmlmethod void WebEngineCertificateError::rejectCertificate() + + The certificate is rejected, and the web engine view stops loading the requested URL. + */ +/*! + \qmlproperty url WebEngineCertificateError::url + \readonly + + The URL that triggered the error. + */ +/*! + \qmlproperty enumeration WebEngineCertificateError::type + \readonly + + The type of the error. + + \value WebEngineCertificateError.SslPinnedKeyNotInCertificateChain + The certificate did not match the built-in public keys pinned for + the host name. + \value WebEngineCertificateError.CertificateCommonNameInvalid + The certificate's common name did not match the host name. + \value WebEngineCertificateError.CertificateDateInvalid + The certificate is not valid at the current date and time. + \value WebEngineCertificateError.CertificateAuthorityInvalid + The certificate is not signed by a trusted authority. + \value WebEngineCertificateError.CertificateContainsErrors + The certificate contains errors. + \value WebEngineCertificateError.CertificateNoRevocationMechanism + The certificate has no mechanism for determining if it has been + revoked. + \value WebEngineCertificateError.CertificateUnableToCheckRevocation + Revocation information for the certificate is not available. + \value WebEngineCertificateError.CertificateRevoked + The certificate has been revoked. + \value WebEngineCertificateError.CertificateInvalid + The certificate is invalid. + \value WebEngineCertificateError.CertificateWeakSignatureAlgorithm + The certificate is signed using a weak signature algorithm. + \value WebEngineCertificateError.CertificateNonUniqueName + The host name specified in the certificate is not unique. + \value WebEngineCertificateError.CertificateWeakKey + The certificate contains a weak key. + \value WebEngineCertificateError.CertificateNameConstraintViolation + The certificate claimed DNS names that are in violation of name + constraints. + \value WebEngineCertificateError.CertificateValidityTooLong + The certificate has a validity period that is too long. + (Added in 5.7) + \value WebEngineCertificateError.CertificateTransparencyRequired + Certificate Transparency was required for this connection, but the server + did not provide CT information that complied with the policy. (Added in 5.8) + \value WebEngineCertificateError.CertificateKnownInterceptionBlocked + The certificate is known to be used for interception by an entity other + the device owner. (Added in 5.15) + +*/ +/*! + \qmlproperty string WebEngineCertificateError::description + \readonly + + A short localized human-readable description of the error. +*/ +/*! + \qmlproperty bool WebEngineCertificateError::overridable + \readonly + + A boolean that indicates whether the certificate error can be overridden and ignored. +*/ diff --git a/src/webenginequick/doc/src/webengine_download_request.qdoc b/src/webenginequick/doc/src/webengine_download_request.qdoc new file mode 100644 index 000000000..96d84e0a3 --- /dev/null +++ b/src/webenginequick/doc/src/webengine_download_request.qdoc @@ -0,0 +1,278 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype WebEngineDownloadRequest + \instantiates QWebEngineDownloadRequest + \inqmlmodule QtWebEngine + \brief Provides information about a download. + + WebEngineDownloadRequest models a download throughout its life cycle, starting + with a pending download request and finishing with a completed download. It + can be used, for example, to get information about new downloads, to monitor + progress, and to pause, resume, and cancel downloads. + + Downloads are usually triggered by user interaction on a web page. It is the + WebEngineProfile's responsibility to notify the application of new download + requests, which it does by emitting the + \l{WebEngineProfile::downloadRequested}{downloadRequested} signal together + with a newly created WebEngineDownloadRequest. The application can then examine + this item and decide whether to accept it or not. A signal handler must + explicitly call accept() on the item for \QWE to actually start + downloading and writing data to disk. If no signal handler calls accept(), + then the download request will be automatically rejected and nothing will be + written to disk. + + \note Some properties, like the \l path under which the file will be saved, + can only be changed before calling accept(). + + \section2 Object Life Cycle + + All items are guaranteed to be valid during the emission of the + \l{WebEngineProfile::downloadRequested}{downloadRequested} signal. If + accept() is \e not called by any signal handler, then the item will be + deleted \e immediately after signal emission. This means that the + application \b{must not} keep references to rejected download items. + + \section2 Web Page Downloads + + In addition to normal file downloads, which consist simply of retrieving + some raw bytes from the network and writing them to disk, \QWE also + supports saving complete web pages, which involves parsing the page's HTML, + downloading any dependent resources, and potentially packaging everything + into a special file format (\l savePageFormat). To check if a download is + for a file or a web page, use \l isSavePageDownload. + + \sa WebEngineProfile, WebEngineProfile::downloadRequested, + WebEngineProfile::downloadFinished +*/ + +/*! + \qmlmethod void WebEngineDownloadRequest::accept() + + Accepts the download request, which will start the download. + + If the item is in the \c DownloadRequested state, then it will transition + into the \c DownloadInProgress state and the downloading will begin. If the + item is in any other state, then nothing will happen. + + \sa state +*/ + +/*! + \qmlmethod void WebEngineDownloadRequest::cancel() + + Cancels the download. + + If the item is in the \c DownloadInProgress state, then it will transition + into the \c DownloadCancelled state, the downloading will stop, and + partially downloaded files will be deleted from disk. + + If the item is in the \c DownloadCompleted state, then nothing will happen. + If the item is in any other state, then it will transition into the \c + DownloadCancelled state without further effect. + + \sa state +*/ + +/*! + \qmlmethod void WebEngineDownloadRequest::pause() + + Pauses the download. + + Has no effect if the state is not \c DownloadInProgress. Does not change the + state. + + \sa resume, isPaused +*/ + +/*! + \qmlmethod void WebEngineDownloadRequest::resume() + + Resumes the download if it was paused or interrupted. + + Has no effect if the state is not \c DownloadInProgress or \c + DownloadInterrupted. Does not change the state. + + \sa pause, isPaused +*/ + +/*! + \qmlproperty int WebEngineDownloadRequest::id + + Holds the download item's ID. +*/ + +/*! + \qmlproperty enumeration WebEngineDownloadRequest::state + + Describes the state of the download: + + \value WebEngineDownloadRequest.DownloadRequested + Download has been requested, but it has not been accepted yet. + \value WebEngineDownloadRequest.DownloadInProgress + Download is in progress. + \value WebEngineDownloadRequest.DownloadCompleted + Download completed successfully. + \value WebEngineDownloadRequest.DownloadCancelled + Download was cancelled by the user. + \value WebEngineDownloadRequest.DownloadInterrupted + Download has been interrupted (by the server or because of lost connectivity). +*/ + +/*! + \qmlproperty int WebEngineDownloadRequest::totalBytes + + Holds the total amount of data to download in bytes. + + \c -1 means the total size is unknown. +*/ + +/*! + \qmlproperty int WebEngineDownloadRequest::receivedBytes + + Holds the amount of data in bytes that has been downloaded so far. +*/ + +/*! + \qmlproperty url WebEngineDownloadRequest::url + \readonly + + Returns the download's origin URL. +*/ + +/*! + \qmlproperty string WebEngineDownloadRequest::mimeType + + Holds the MIME type of the download. +*/ + +/*! + \qmlproperty string WebEngineDownloadRequest::downloadDirectory + + Holds the full target path without file name where data is being downloaded to. + + The download directory can only be set in the + \l{WebEngineProfile::downloadRequested}{downloadRequested} handler before + the download is accepted. + + \sa WebEngineProfile::downloadRequested(), accept() +*/ + +/*! + \qmlproperty string WebEngineDownloadRequest::downloadFileName + + Holds the name of the file to which data is being downloaded. + + The download file name can only be set in the + \l{WebEngineProfile::downloadRequested}{downloadRequested} handler before + the download is accepted. + + \sa WebEngineProfile::downloadRequested(), accept() +*/ + +/*! + \qmlproperty string WebEngineDownloadRequest::suggestedFileName + + Returns the suggested file name. +*/ + +/*! + \qmlproperty enumeration WebEngineDownloadRequest::savePageFormat + + Describes the format that is used to save a web page. + + \value WebEngineDownloadRequest.UnknownSaveFormat + This is not a request for downloading a complete web page. + \value WebEngineDownloadRequest.SingleHtmlSaveFormat + The page is saved as a single HTML page. Resources such as images + are not saved. + \value WebEngineDownloadRequest.CompleteHtmlSaveFormat + The page is saved as a complete HTML page, for example a directory + containing the single HTML page and the resources. + \value WebEngineDownloadRequest.MimeHtmlSaveFormat + The page is saved as a complete web page in the MIME HTML format. +*/ + +/*! + \qmlproperty bool WebEngineDownloadRequest::isSavePageDownload + \readonly + + Whether this is a download request for saving a web page or a file. + + \sa savePageFormat +*/ + +/*! + \qmlproperty enumeration WebEngineDownloadRequest::interruptReason + \readonly + + Returns the reason why the download was interrupted: + + \value WebEngineDownloadRequest.NoReason Unknown reason or not interrupted. + \value WebEngineDownloadRequest.FileFailed General file operation failure. + \value WebEngineDownloadRequest.FileAccessDenied The file cannot be written locally, due to access restrictions. + \value WebEngineDownloadRequest.FileNoSpace Insufficient space on the target drive. + \value WebEngineDownloadRequest.FileNameTooLong The directory or file name is too long. + \value WebEngineDownloadRequest.FileTooLarge The file size exceeds the file system limitation. + \value WebEngineDownloadRequest.FileVirusInfected The file is infected with a virus. + \value WebEngineDownloadRequest.FileTransientError Temporary problem (for example the file is in use, + out of memory, or too many files are opened at once). + \value WebEngineDownloadRequest.FileBlocked The file was blocked due to local policy. + \value WebEngineDownloadRequest.FileSecurityCheckFailed An attempt to check the safety of the download + failed due to unexpected reasons. + \value WebEngineDownloadRequest.FileTooShort An attempt was made to seek past the end of a file when + opening a file (as part of resuming a previously interrupted download). + \value WebEngineDownloadRequest.FileHashMismatch The partial file did not match the expected hash. + + \value WebEngineDownloadRequest.NetworkFailed General network failure. + \value WebEngineDownloadRequest.NetworkTimeout The network operation has timed out. + \value WebEngineDownloadRequest.NetworkDisconnected The network connection has been terminated. + \value WebEngineDownloadRequest.NetworkServerDown The server has gone down. + \value WebEngineDownloadRequest.NetworkInvalidRequest The network request was invalid (for example, the + original or redirected URL is invalid, has an unsupported scheme, or is disallowed by policy). + + \value WebEngineDownloadRequest.ServerFailed General server failure. + \value WebEngineDownloadRequest.ServerBadContent The server does not have the requested data. + \value WebEngineDownloadRequest.ServerUnauthorized The server did not authorize access to the resource. + \value WebEngineDownloadRequest.ServerCertProblem A problem with the server certificate occurred. + \value WebEngineDownloadRequest.ServerForbidden Access forbidden by the server. + \value WebEngineDownloadRequest.ServerUnreachable Unexpected server response (might indicate that + the responding server may not be the intended server). + \value WebEngineDownloadRequest.UserCanceled The user canceled the download. + + \sa interruptReasonString +*/ + +/*! + \qmlproperty string WebEngineDownloadRequest::interruptReasonString + Returns a human-readable description of the reason for interrupting the download. + + \sa interruptReason +*/ + +/*! + \qmlproperty bool WebEngineDownloadRequest::isFinished + \readonly + + Whether this download is finished (completed, cancelled, or non-resumable interrupted state). + */ + +/*! + \qmlproperty bool WebEngineDownloadRequest::isPaused + \readonly + + Whether this download is paused. + + \sa pause, resume + */ + +/*! + \qmlproperty WebEngineView WebEngineDownloadRequest::view + \readonly + + Returns the view the download was requested on. If the download was not triggered by content in a view, + \c nullptr is returned. + + \sa WebEngineView +*/ diff --git a/src/webenginequick/doc/src/webengine_permission.qdoc b/src/webenginequick/doc/src/webengine_permission.qdoc new file mode 100644 index 000000000..f59f57fa0 --- /dev/null +++ b/src/webenginequick/doc/src/webengine_permission.qdoc @@ -0,0 +1,137 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype webEnginePermission + \instantiates QWebEnginePermission + \inqmlmodule QtWebEngine + \brief An object used to access and modify the state of a single permission that's been + granted or denied to a specific origin URL. + + The typical usage pattern is as follows: + \list 1 + \li A website requests a specific feature, triggering the WebEngineView::permissionRequested signal; + \li The signal handler triggers a prompt asking the user whether they want to grant the permission; + \li When the user has made their decision, the application calls \l grant() or \l deny(); + \endlist + + Alternatively, an application interested in modifying already granted permissions may use WebEngineProfile::listPermissions() + to get a list of existing permissions associated with a profile, or WebEngineProfile::getPermission() to get + a webEnginePermission object for a specific permission. + + The \l origin property can be used to query which origin the webEnginePermission is associated with, while the + \l feature property describes the associated feature. A website origin is the combination of its scheme, hostname, + and port. Permissions are granted on a per-origin basis; thus, if the web page \c{https://www.example.com:12345/some/page.html} + requests a permission, it will be granted to the origin \c{https://www.example.com:12345/}. + + The usability lifetime of a webEnginePermission is tied either to its associated WebEngineView + (for transient feature types), or WebEngineProfile (for permanent feature types). A transient permission is one which + needs to be explicitly granted or denied every time it's needed (e.g. webcam/screen sharing permission), whereas a permanent + one might be stored inside the current profile, depending on the value of WebEngineProfile::persistentPermissionsPolicy. + You can check whether a webEnginePermission is in a valid state using its \l isValid() property. For invalid objects, calls to \l grant(), + \l deny(), or \l reset() will do nothing, and their \l state() will always be WebEnginePermission.Invalid. + + The feature types Qt WebEngine supports are described in \l feature. + + \sa WebEngineView::permissionRequested, WebEngineProfile::getPermission(), + WebEngineProfile::listPermissions() +*/ + +/*! + \qmlproperty url webEnginePermission::origin + \brief The URL of the permission's associated origin. + + A website origin is the combination of its scheme, hostname, and port. Permissions are granted on a + per-origin basis; thus, if the web page \c{https://www.example.com:12345/some/page.html} + requests a permission, it will be granted to the origin \c{https://www.example.com:12345/}. +*/ + +/*! + \qmlproperty enumeration webEnginePermission::feature + \brief The feature type associated with this permission. + + \value WebEnginePermission.MediaAudioCapture Access to a microphone, or another audio source. This feature is transient. + \value WebEnginePermission.MediaVideoCapture Access to a webcam, or another video source. This feature is transient. + \value WebEnginePermission.MediaAudioVideoCapture Combination of \l MediaAudioCapture and \l MediaVideoCapture. This feature is transient. + \value WebEnginePermission.DesktopVideoCapture Access to the contents of the user's screen. This feature is transient. + \value WebEnginePermission.DesktopAudioVideoCapture Access to the contents of the user's screen, and application audio. This feature is transient. + \value WebEnginePermission.MouseLock Locks the pointer inside an element on the web page. This feature is transient. + \value WebEnginePermission.Notifications Allows the website to send notifications to the user. + \value WebEnginePermission.Geolocation Access to the user's physical location. + \value WebEnginePermission.ClipboardReadWrite Access to the user's clipboard. + \value WebEnginePermission.LocalFontsAccess Access to the fonts installed on the user's machine. Only available on desktops. + \value WebEnginePermission.Unsupported An unsupported feature type. + + \note Transient feature types are ones that will never be remembered by the underlying storage, and will trigger + a permission request every time a website tries to use them. +*/ + +/*! + \qmlproperty enumeration webEnginePermission::state + \brief The current state of the permission. + + \value WebEnginePermission.Invalid Object is in an invalid state, and any attempts to modify the described permission will fail. + \value WebEnginePermission.Ask Either the permission has not been requested before, or the feature() is transient. + \value WebEnginePermission.Granted Permission has already been granted. + \value WebEnginePermission.Denied Permission has already been denied. + + If a permission for the specified \l feature and \l origin has already been granted or denied, + the return value is WebEnginePermission.Granted, or WebEnginePermission.Denied, respectively. + When this is the first time the permission is requested, or if the \l feature is transient, + the return value is WebEnginePermission.Ask. If the object is in an invalid state, the returned + value is WebEnginePermission.Invalid. + + \sa isValid, isTransient +*/ + +/*! + \qmlproperty bool webEnginePermission::isValid + \brief Indicates whether attempts to change the permission's state will be successful. + + An invalid webEnginePermission is either: + \list + \li One whose \l feature is unsupported; + \li One whose \l feature is transient, and the associated page/view has been destroyed; + \li One whose \l feature is permanent, but the associated profile has been destroyed; + \li One whose \l origin is invalid. + \endlist + + \sa isTransient +*/ + +/*! + \qmlmethod void webEnginePermission::grant() + + Allows the associated origin to access the requested feature. Does nothing when \l isValid evaluates to false. + + \sa deny, reset, isValid +*/ + +/*! + \qmlmethod void webEnginePermission::deny() + + Stops the associated origin from accessing the requested feature. Does nothing when \l isValid evaluates to false. + + \sa grant, reset, isValid +*/ + +/*! + \qmlmethod void webEnginePermission::reset() + + Removes the permission from the profile's underlying storage. By default, permissions are stored on disk (except for + off-the-record profiles, where permissions are stored in memory and are destroyed with the profile). + This means that an already granted/denied permission will not be requested twice, but will get automatically + granted/denied every subsequent time a website requests it. Calling reset() allows the query to be asked + again the next time the website requests it. + + Does nothing when \l isValid evaluates to false. + + \sa grant, deny, isValid, WebEngineProfile::persistentPermissionsPolicy +*/ + +/*! + \qmlmethod void webEnginePermission::isTransient(WebEnginePermission.Feature feature) + + Returns whether \a feature is transient, meaning that a permission will be requested + every time the associated functionality is used by a web page. +*/ diff --git a/src/webenginequick/doc/src/webengineframe.qdoc b/src/webenginequick/doc/src/webengineframe.qdoc new file mode 100644 index 000000000..8f852501e --- /dev/null +++ b/src/webenginequick/doc/src/webengineframe.qdoc @@ -0,0 +1,129 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \qmltype webEngineFrame + \instantiates QQuickWebEngineFrame + \brief webEngineFrame provides information about and control over a page frame. + \since 6.8 + \ingroup qmlvaluetypes + \inqmlmodule QtWebEngine + + A web engine frame represents a single frame within a web page, such as those created by + \c <frame> or \c <iframe> HTML elements. + An active \l WebEngineView has one or more frames arranged in a tree structure. The top-level + frame, the root of this tree, can be accessed through the view's \l {WebEngineView::mainFrame} + {mainFrame} property. + + A frame's lifetime is, at most, as long as the \l WebEngineView object that produced it. + However, frames may be created and deleted spontaneously and dynamically, for example through + navigation and script execution. +*/ + +/*! + \qmlproperty bool webEngineFrame::isValid + + Returns \c{true} if this object represents an existing frame; \c{false} otherwise. + + Once a frame is invalid, it never becomes valid again. +*/ + +/*! + \qmlproperty string webEngineFrame::name + + Returns the frame name; that is, what would be returned by \c window.name in JavaScript. + + If the frame could not be found, returns an empty string. + + \sa htmlName +*/ + +/*! + \qmlproperty string webEngineFrame::htmlName + + Returns the value of the frame's \c name HTML attribute, or an empty string if it has none. + + If the frame could not be found, returns an empty string. + + \sa name +*/ + +/*! + \qmlproperty url webEngineFrame::url + + Returns the URL of the content currently loaded in this frame. + + If the frame could not be found, returns an empty URL. +*/ + +/*! + \qmlproperty size webEngineFrame::size + + Returns the size of the frame within the viewport. + + If the frame could not be found, returns a default size with dimensions (-1, -1). +*/ + +/*! + \qmlproperty bool webEngineFrame::isMainFrame + + Returns \c{true} if this object represents the page's main frame; \c{false} otherwise. +*/ + +/*! + \qmlmethod void webEngineFrame::runJavaScript(string script, variant callback) + \qmlmethod void webEngineFrame::runJavaScript(string script, uint worldId, variant callback) + + Runs the JavaScript code contained in \a script on this frame, without checking + whether the DOM of the page has been constructed. + + To avoid conflicts with other scripts executed on the page, the world in + which the script is run is specified by \a worldId. The world ID values are + the same as provided by QWebEngineScript::ScriptWorldId, and between \c 0 + and \c 256. If you leave out the \c world ID, the script is run in the + \c MainWorld. + + The \a callback parameter is optional. If a callback function is provided, it will be + invoked after the script finishes running. + \code + frame.runJavaScript("document.title", function(result) { console.log(result); }); + \endcode + + Only plain data can be returned from JavaScript as the result value. + Supported data types include all of the JSON data types as well as, for + example, \c{Date} and \c{ArrayBuffer}. Unsupported data types include, for + example, \c{Function} and \c{Promise}. + + The script will run in the same \e world as other scripts that are + part of the loaded site. + + \warning Do not execute lengthy routines in the callback function, because it might block the + rendering of the web content. + + For more information about injecting scripts, see \l {Script Injection}. + For an alternative way to inject scripts, see WebEngineView::userScripts. +*/ + +/*! + \qmlmethod void webEngineFrame::printToPdf(string filePath) + + Prints the frame's current content to a PDF document and stores it + under \a filePath. The resulting document will have A4 page size and + portrait orientation. + + This method issues an asynchronous request for printing the web page into a + PDF and returns immediately. To be informed about the result of the + request, connect to the signal \l WebEngineView::pdfPrintingFinished(). + + \sa WebEngineView::pdfPrintingFinished() +*/ + +/*! + \qmlmethod void webEngineFrame::printToPdf(variant callback) + + Prints the frame's current content to a PDF document and returns it in a byte array. The + resulting document will have A4 page size and portrait orientation. + + The \a callback must take a string parameter. This string will contain the document's data upon + successful printing and an empty string otherwise. +*/ 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 new file mode 100644 index 000000000..f7b17fa7b --- /dev/null +++ b/src/webenginequick/doc/src/webengineview_lgpl.qdoc @@ -0,0 +1,1639 @@ +// 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. + +/*! + \qmltype WebEngineView + \instantiates QQuickWebEngineView + \inherits Item + \inqmlmodule QtWebEngine + \since QtWebEngine 1.0 + \brief A WebEngineView renders web content within a QML application. + + The WebEngineView type enables QML applications to render regions of dynamic web content. It + may share the screen with other QML types, such as a TabView, or fill the screen, as specified + within the QML application. + + \section2 Initializing Web Engine + + For the web engine view to be rendered, the web engine must be initialized by using + \l QtWebEngineQuick::initialize in the application main source file, as illustrated by the + following code snippet: + + \quotefromfile minimal/main.cpp + \skipto main + \printuntil } + + \section2 Loading Web Pages + + An application can load pages into the WebEngineView, using either the \l url property or the + \l loadHtml method and navigate within the view's session history. The GET + method is always used to load URLs. + + The history is represented by a WebEngineHistory data model that is held by + the \l history property. + + The following sample QML application loads a web page using the \c url property: + + \quotefromfile minimal/main.qml + \skipto import + \printuntil /^\}/ + + The \l loading property holds whether an HTML page is currently loading. + The \l loadingChanged() signal is emitted when loading the page begins, ends, or fails. + + The title of an HTML page can be accessed with the \l title property. Additionally, a web + page may specify an icon, which can be accessed using the \l icon property. The \l zoomFactor + property enables zooming the contents of the web page by a scale factor. + + If a certificate error is raised while loading a web page, the \l certificateError() signal is + emitted. Certificate errors are handled by using the methods of the WebEngineCertificateError + type. + + \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 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 + 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. + + The \l setActiveFocusOnPress() method can be used to create a UI element that should not get + focus on press. This can be useful in a hybrid UI. + + The \l {WebEngineSettings::focusOnNavigationEnabled} {focusOnNavigationEnabled} setting can be + used to make the view automatically receive focus when a navigation operation occurs + (like loading or reloading a page or navigating through history). + + The \l linkHovered() signal is emitted when a mouse pointer passes over a link and thus + corresponds to the \c{mouseover} DOM event. + + Actions, such as selecting and editing content, can be performed on a web page by using the + \l triggerWebAction() method. The available actions are described by the \l WebAction property. + + The \l backgroundColorChanged() signal is emitted when the web page background color changes. + + \section2 User Scripts + + During the loading of a page, so called \e {user scripts} can be injected in the JavaScript + engine at different points. The script objects attached to the web engine view are held by the + \l userScripts property and injected by using the WebEngineScript type. Scripts can also be run + by using the runJavaScript() method in the same world as other scripts that are part of the + loaded site. + + The \l webChannel property can be used to expose a WebChannel instance in the JavaScript context + of the page it is rendering as \c qt.webChannelTransport. + + \section2 Fullscreen Mode + + A web page can request through the JavaScript API to be loaded in fullscreen mode. The + \l fullScreenRequested() signal is emitted when the web page issues the request. The + FullScreenRequest utility type can be used to toggle fullscreen requests. The + \l fullScreenCancelled method can be used to notify the browser engine when the windowing + system forces the application to leave fullscreen mode. + + \section2 Profiles + + Web engine views can be isolated from each other by using the WebEngineProfile type. A profile + contains settings, scripts, and the list of visited links shared by all views that belong to the + profile. For example, a dedicated profile could be created for a \e {private browsing} mode. The + current profile for the view is held by the \l profile property and the current settings are + held by the \l settings property. The settings are specified by using the WebEngineSettings + type. + + \section2 Platform Features + + Web pages can request access to platform features, such as geolocation or audio and video + capture devices. The \l permissionRequested() signal is emitted when a web page requests + to make use of a resource. The supported platform features are described by the QWebEnginePermission::Feature + property. + + \section2 Rendering to OpenGL Surface + + When using a QQuickRenderControl to render a Qt Quick user interface to an OpenGL surface, the + WebEngineView type is not rendered correctly. The web engine view attempts to use a global + OpenGL context created by \l QtWebEngineQuick::initialize, but there is no public API for accessing + that context in order to share it with the \c QQuickRenderControl context. + + To have the web engine view rendered correctly, it is possible to manually create a new + offscreen context that is shared with the \c QQuickRenderControl and to call the non-public + function \c qt_gl_set_global_share_context(), rather than calling \c initialize(). + If \c initialize() is called after setting a global context, it will do nothing. +*/ + +/*! + \qmlmethod void WebEngineView::goBack() + + Go backward within the browser's session history, if possible. + This function is equivalent to the \c{window.history.back()} DOM method. + + \sa canGoBack +*/ + +/*! + \qmlmethod void WebEngineView::goForward() + + Go forward within the browser's session history, if possible. + This function is equivalent to the \c{window.history.forward()} DOM method. +*/ + +/*! + \qmlmethod void WebEngineView::goBackOrForward(int offset) + \since QtWebEngine 1.1 + + If \a offset is positive, goes forward the specified number of offset + pages in the current session history. If offset is negative, it goes + back. If the offset is invalid, the page is not changed. + + \sa goBack(), goForward() +*/ + +/*! + \qmlmethod void WebEngineView::stop() + + Stops loading the current page. +*/ + +/*! + \qmlmethod void WebEngineView::reload() + + Reloads the current page. This function is equivalent to the + \c{window.location.reload()} DOM method. + + \sa reloadAndBypassCache() +*/ + +/*! + \qmlmethod void WebEngineView::reloadAndBypassCache() + \since QtWebEngine 1.1 + + Reloads the current page, ignoring any cached content. + + \sa reload() +*/ + +/*! + \qmlproperty url WebEngineView::url + + The location of the currently displayed HTML page. This writable + property offers the main interface to load a page into a web view. + It functions the same as the \c{window.location} DOM property. + + \sa loadHtml() +*/ + +/*! + \qmlproperty url WebEngineView::icon + \readonly + + An internal URL for accessing the currently displayed web site icon, + also known as favicon or shortcut icon. + This read-only URL corresponds to the image used within a mobile browser + application to represent a bookmarked page on the device's home screen. + + The following snippet uses the \c{icon} property to build an \c{Image} + component: + + \qml + Image { + id: appIcon + sourceSize: Qt.size(32, 32) + source: webView.icon != "" ? webView.icon : "fallbackFavicon.png"; + // ... + } + \endqml + + Specifying the \l {Image::sourceSize} property informs + the \QWE's favicon provider about the requested size and resizes the + icon to it. If \l {Image::sourceSize} property is not specified, + the provider provides the icon with the largest available resolution. +*/ + +/*! + \qmlproperty int WebEngineView::loadProgress + \readonly + + The amount of data from the page that has been loaded, expressed + as an integer percentage in the range from \c{0} to \c{100}. +*/ + +/*! + \qmlproperty bool WebEngineView::canGoBack + \readonly + + Returns \c{true} if there are prior session history entries, \c{false} + otherwise. +*/ + +/*! + \qmlproperty bool WebEngineView::canGoForward + \readonly + + Returns \c{true} if there are subsequent session history entries, + \c{false} otherwise. +*/ + +/*! + \qmlproperty bool WebEngineView::loading + \readonly + + Returns \c{true} if the HTML page is currently loading, \c{false} otherwise. +*/ + +/*! + \qmlproperty string WebEngineView::title + \readonly + + The title of the currently displayed HTML page. This is a + read-only value that reflects the contents of the \c{<title>} tag. +*/ + +/*! + \qmlproperty bool WebEngineView::isFullScreen + \since QtWebEngine 1.1 + \readonly + + Returns \c{true} if the web view is in fullscreen mode, \c{false} otherwise. + + \sa fullScreenRequested(), fullScreenCancelled() +*/ + +/*! + \qmlproperty WebEngineHistory WebEngineView::history + \since QtWebEngine 1.1 + \readonly + + The navigation history of the current view. + + \sa WebEngineHistory +*/ + +/*! + \qmlproperty QQmlWebChannel WebEngineView::webChannel + \since QtWebEngine 1.1 + + The web channel instance used by this view. + This channel is automatically using the internal QtWebEngine transport mechanism over Chromium IPC, + and exposed in the javascript context of the page it is rendering as \c qt.webChannelTransport. + This transport object is used when instantiating the JavaScript counterpart of QWebChannel using + the \l{Qt WebChannel JavaScript API}. + + \note The view does not take ownership for an assigned webChannel object. +*/ + +/*! + \qmlproperty WebEngineProfile WebEngineView::profile + \since QtWebEngine 1.1 + + The current profile used for the view. + + \sa WebEngineProfile +*/ + +/*! + \qmlproperty WebEngineSettings WebEngineView::settings + \readonly + \since QtWebEngine 1.1 + + Settings used by this view. + + \sa WebEngineSettings +*/ + + +/*! + \qmlproperty WebEngineScriptCollection WebEngineView::userScripts + \readonly + \since QtWebEngine 1.1 + + The user scripts' collection associated with the view. + + \sa WebEngineScriptCollection +*/ + +/*! + \qmlproperty real WebEngineView::zoomFactor + \since QtWebEngine 1.1 + + Zoom factor for the view. Valid values are within the range from \c{0.25} + to \c{5.0}. The default factor is \c{1.0}. +*/ + +/*! + \qmlproperty size WebEngineView::contentsSize + \since QtWebEngine 1.3 + + Size of the page contents. +*/ + +/*! + \qmlproperty point WebEngineView::scrollPosition + \since QtWebEngine 1.3 + + Scroll position of the page contents. +*/ + +/*! + \qmlproperty int WebEngineView::webChannelWorld + \since QtWebEngine 1.3 + + JavaScript world that the web channel instance used by this view is + installed in. The world must be a number between \c 0 and \c 256. +*/ + +/*! + \qmlmethod void WebEngineView::loadHtml(string html, url baseUrl) + Loads the specified \a html as the content of the web view. + + This method offers a lower-level alternative to the \c{url} property, + which references HTML pages via URL. + + \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}. + + \sa url +*/ + +/*! + \qmlmethod void WebEngineView::runJavaScript(string script, variant callback) + \qmlmethod void WebEngineView::runJavaScript(string script, int worldId, variant callback) + + Runs the specified \a script in the content of the web view. + + The \a callback parameter is optional. If a callback function is provided, + it will be invoked after the script finishes running. + + \code + runJavaScript("document.title", function(result) { console.log(result); }); + \endcode + + Only plain data can be returned from JavaScript as the result value. + Supported data types include all of the JSON data types as well as, for + example, \c{Date} and \c{ArrayBuffer}. Unsupported data types include, for + example, \c{Function} and \c{Promise}. + + To avoid conflicts with other scripts executed on the page, the world in + which the script is run can be specified by \a worldId. The world ID must be + between \c 0 and \c 256. If you leave out the \c world ID, the script is + run in the \c MainWorld. + + \warning Do not execute lengthy routines in the callback function, because it might block the + rendering of the web content. + + For more information about injecting scripts, see \l {Script Injection}. + For an alternative way to inject scripts, see WebEngineView::userScripts. +*/ + +/*! + \qmlmethod void WebEngineView::findText(string subString) + \since QtWebEngine 1.1 + Finds the specified string, \a subString, in the page. + The findTextFinished() signal is emitted when a string search is completed. + + To clear the search highlight, just pass an empty string. + + \sa findTextFinished() +*/ + +/*! + \qmlmethod void WebEngineView::findText(string subString, FindFlags options) + \since QtWebEngine 1.1 + Finds the specified string, \a subString, in the page, using the given \a options. + The findTextFinished() signal is emitted when a string search is completed. + + To clear the search highlight, just pass an empty string. + + \code + findText("Qt", WebEngineView.FindBackward | WebEngineView.FindCaseSensitively); + \endcode + + \sa findTextFinished() +*/ + +/*! + \qmlmethod void WebEngineView::findText(string subString, FindFlags options, variant resultCallback) + \since QtWebEngine 1.1 + Finds the specified string, \a subString, in the page, using the given \a options. + The findTextFinished() signal is emitted when a string search is completed. + + To clear the search highlight, just pass an empty string. + + The \a resultCallback must take an integer parameter. It will be called with + the number of found occurrences of the \a subString. + + \code + findText("Qt", WebEngineView.FindCaseSensitively, function(matchCount) { + if (matchCount > 0) + console.log("'Qt' tokens found:", matchCount); + }); + \endcode + + \sa findTextFinished() +*/ + +/*! + \qmlmethod void WebEngineView::grantFeaturePermission(url securityOrigin, Feature feature, bool granted) + \since QtWebEngine 1.1 + \deprecated [6.8] Use webEnginePermission.grant() or webEnginePermission.deny() instead. + + Sets or unsets the permission, depending on \a granted, for the web site + identified by \a securityOrigin to use \a feature. + + \sa featurePermissionRequested() +*/ + + +/*! + \qmlmethod void WebEngineView::fullScreenCancelled() + \since QtWebEngine 1.1 + + Immediately sets \c{isFullScreen} property to \c{false}. It can be used to notify the + browser engine when the windowing system forces the application to leave fullscreen mode. + + \qml + ApplicationWindow { + onVisibilityChanged: { + if (webEngineView.isFullScreen && visibility != Window.FullScreen) + webEngineView.fullScreenCancelled() + } + + WebEngineView { + id: webEngineView + // ... + } + } + \endqml + + \sa isFullScreen, fullScreenRequested() +*/ + +/*! + \qmlmethod void WebEngineView::setActiveFocusOnPress(bool arg) + \since QtWebEngine 1.2 + + Sets active focus to a clicked web engine view if \a arg is \c true. By setting it to \c false, + a web engine view can be used to create a UI element that should not get focus. This can be + useful in a hybrid UI. + + \sa activeFocusOnPress, activeFocusOnPressChanged, + WebEngineSettings::focusOnNavigationEnabled +*/ + +/*! + \qmlmethod void WebEngineView::triggerWebAction(WebAction action) + \since QtWebEngine 1.2 + + Triggers the web action \a action. + + \sa WebAction +*/ + +/*! + \qmlsignal WebEngineView::featurePermissionRequested(url securityOrigin, Feature feature) + \since QtWebEngine 1.1 + \deprecated [6.8] Use \l permissionRequested() instead. + + This signal is emitted when the web site identified by \a securityOrigin requests + to make use of the resource or device identified by \a feature. + + \sa grantFeaturePermission() +*/ + +/*! + \qmlsignal WebEngineView::permissionRequested(webEnginePermission permission) + \since QtWebEngine 6.8 + + This signal is emitted when a web site requests to make use of a feature (e.g. geolocation access, + permission to send notifications). The \a permission object can queried for the requesting URL + and the \c{WebEnginePermission.Feature} it's asking for, as well as to grant or deny permission. +*/ + +/*! + \qmlsignal WebEngineView::loadingChanged(WebEngineLoadingInfo loadingInfo) + + This signal is emitted when a page load begins, ends, or fails. + + When handling the signal with \c onLoadingChanged, various read-only + parameters are available on the WebEngineLoadingInfo specified by + \a loadingInfo. + + \sa loading, LoadStatus, ErrorDomain +*/ + +/*! + \qmlsignal WebEngineView::certificateError(WebEngineCertificateError error) + \since QtWebEngine 1.1 + + This signal is emitted when an invalid certificate error, \a error, is + raised while loading a given request. + + The certificate error can be handled by using the methods of the WebEngineCertificateError + type. +*/ + +/*! + \qmlsignal WebEngineView::linkHovered(url hoveredUrl) + + Within a mouse-driven interface, this signal is emitted when a mouse + pointer passes over a link, corresponding to the \c{mouseover} DOM + event. This event may also occur in touch interfaces for \c{mouseover} + events that are not cancelled with \c{preventDefault()}. \a{hoveredUrl} + provides the link's location. +*/ + +/*! + \qmlsignal WebEngineView::javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level, string message, int lineNumber, string sourceID) + This signal is emitted when a JavaScript program tries to print a \a message to the web browser's console. + + For example, in case of evaluation errors the source URL may be provided in \a sourceID as well + as the \a lineNumber. + + \a level indicates the severity of the event that triggered the message, that is, whether it + was triggered by an error or a less severe event. + + If no handler is specified, the view will log the messages into a \c js + \l{QLoggingCategory}{logging category}. + + \sa{Console Logging} +*/ + +/*! + \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 + through a JavaScript call to \c window.open, or because the user clicked on a link + 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 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 WebEngineNewWindowRequest, {WebEngine Quick Nano Browser} +*/ + +/*! + \qmlmethod void WebEngineView::acceptAsNewWindow(QWebEngineNewWindowRequest *request) + \since QtWebEngine 2.0 + + Handle the newWindowRequested signal by opening the \a request in this view. + + \sa newWindowRequested +*/ + +/*! + \qmlsignal WebEngineView::fullScreenRequested(FullScreenRequest request) + \since QtWebEngine 1.1 + + This signal is emitted when the web page issues the \a request for + fullscreen mode through the JavaScript API. + + \sa isFullScreen +*/ + +/*! + \qmlsignal WebEngineView::activeFocusOnPressChanged(bool activeFocusOnPress) + \since QtWebEngine 1.2 + + This signal is emitted when the value of \a activeFocusOnPress changes. + It specifies whether the view should gain active focus when pressed. + + \sa activeFocusOnPress, setActiveFocusOnPress() +*/ + +/*! + \qmlsignal WebEngineView::backgroundColorChanged() + \since QtWebEngine 1.2 + + This signal is emitted when the web engine view background color changes. +*/ + +/*! + \qmlsignal WebEngineView::renderProcessTerminated(RenderProcessTerminationStatus terminationStatus, int exitCode) + + \since QtWebEngine 1.2 + + This signal is emitted when the render process is terminated with a non-zero exit status. + \a terminationStatus is the termination status of the process and \a exitCode is the status code + with which the process terminated. + + \sa RenderProcessTerminationStatus +*/ + +/*! + \qmlsignal WebEngineView::windowCloseRequested() + \since QtWebEngine 1.2 + + This signal is emitted whenever the page requests the web browser window to be closed, + for example through the JavaScript \c{window.close()} call. +*/ + +/*! + \qmlproperty enumeration WebEngineView::ErrorDomain + + Describes various high-level error types: + + \value WebEngineView.NoErrorDomain + \value WebEngineView.InternalErrorDomain + Content fails to be interpreted by \QWE. + \value WebEngineView.ConnectionErrorDomain + Error results from faulty network connection. + \value WebEngineView.CertificateErrorDomain + Error related to the SSL/TLS certificate. + \value WebEngineView.HttpErrorDomain + Error related to the HTTP connection. + \value WebEngineView.FtpErrorDomain + Error related to the FTP connection. + \value WebEngineView.DnsErrorDomain + Error related to the DNS connection. +*/ + +/*! + \qmlproperty enumeration WebEngineView::JavaScriptConsoleMessageLevel + + Indicates the severity of a JavaScript console message: + + \value WebEngineView.InfoMessageLevel + Message is purely informative and can safely be ignored. + \value WebEngineView.WarningMessageLevel + Message indicates there might be a problem that may need attention. + \value WebEngineView.ErrorMessageLevel + Message indicates there has been an error. +*/ + +/*! + \qmlproperty enumeration WebEngineView::LoadStatus + + Reflects a page's load status: + + \value WebEngineView.LoadStartedStatus + Page is currently loading. + \value WebEngineView.LoadStoppedStatus + Loading the page was stopped by the stop() method or by the loader + code or network stack in Chromium. + \value WebEngineView.LoadSucceededStatus + Page has successfully loaded, and is not currently loading. + \value WebEngineView.LoadFailedStatus + Page has failed to load, and is not currently loading. +*/ + +/*! + \qmlproperty enumeration WebEngineView::FindFlags + + Describes the options available to the findText() function. The options + can be OR-ed together from the following list: + + \value WebEngineView.FindBackward + Searches backwards instead of forwards. + \value WebEngineView.FindFlags FindCaseSensitively + By default findText() works case insensitive. Specifying + this option changes the behavior to a case sensitive find operation. + + \sa findText() +*/ + +/*! + \qmlproperty enumeration WebEngineView::RenderProcessTerminationStatus + \since QtWebEngine 1.2 + + Describes the status with which the render process terminated: + + \value WebEngineView.NormalTerminationStatus + The render process terminated normally. + \value WebEngineView.AbnormalTerminationStatus + The render process terminated with a non-zero exit status. + \value WebEngineView.CrashedTerminationStatus + The render process crashed, for example because of a segmentation fault. + \value WebEngineView.KilledTerminationStatus + The render process was killed, for example by \c SIGKILL or task manager kill. +*/ + +/*! + \qmlproperty enumeration WebEngineView::WebAction + \since QtWebEngine 1.2 + + Describes the types of action that can be performed on a web page: + + \value WebEngineView.NoWebAction + No action is triggered. + \value WebEngineView.Back + Navigate back in the history of navigated links. + \value WebEngineView.Forward + Navigate forward in the history of navigated links. + \value WebEngineView.Stop + Stop loading the current page. + \value WebEngineView.Reload + Reload the current page. + \value WebEngineView.ReloadAndBypassCache + Reload the current page, but do not use any local cache. + \value WebEngineView.Cut + Cut the content currently selected into the clipboard. + \value WebEngineView.Copy + Copy the content currently selected into the clipboard. + \value WebEngineView.Paste + Paste content from the clipboard. + \value WebEngineView.Undo + Undo the last editing action. + \value WebEngineView.Redo + Redo the last editing action. + \value WebEngineView.SelectAll + Select all content. + This action is only enabled when the page's content is focused. + The focus can be forced by the JavaScript \c{window.focus()} call, or the + \l{WebEngineSettings::focusOnNavigationEnabled} {focusOnNavigationEnabled} setting + should be enabled to get automatic focus. + \value WebEngineView.PasteAndMatchStyle + Paste content from the clipboard with current style. + \value WebEngineView.OpenLinkInThisWindow + 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 newWindowRequested() signal. (Added in Qt 5.6) + \value WebEngineView.OpenLinkInNewTab + Open the current link in a new tab. Requires a handler for the + \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 + Copy the clicked image to the clipboard. (Added in Qt 5.6) + \value WebEngineView.CopyImageUrlToClipboard + Copy the clicked image's URL to the clipboard. (Added in Qt 5.6) + \value WebEngineView.CopyMediaUrlToClipboard + Copy the hovered audio or video's URL to the clipboard. (Added in Qt 5.6) + \value WebEngineView.ToggleMediaControls + Toggle between showing and hiding the controls for the hovered audio or video element. + (Added in Qt 5.6) + \value WebEngineView.ToggleMediaLoop + Toggle whether the hovered audio or video should loop on completetion or not. + (Added in Qt 5.6) + \value WebEngineView.ToggleMediaPlayPause + Toggle the play/pause state of the hovered audio or video element. (Added in Qt 5.6) + \value WebEngineView.ToggleMediaMute + Mute or unmute the hovered audio or video element. (Added in Qt 5.6) + \value WebEngineView.DownloadLinkToDisk + Download the current link to the disk. To implement download + actions, connect to the \l {QQuickWebEngineProfile::downloadRequested} + {WebEngineProfile.downloadRequested} signal. (Added in Qt 5.6) + \value WebEngineView.DownloadImageToDisk + Download the highlighted image to the disk. (Added in Qt 5.6) + \value WebEngineView.DownloadMediaToDisk + Download the hovered audio or video to the disk. (Added in Qt 5.6) + \value WebEngineView.InspectElement + Trigger any attached Web Inspector to inspect the highlighed element. + (Added in Qt 5.6) + \value WebEngineView.ExitFullScreen + 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 newWindowRequested() signal. (Added in Qt 5.8) + + \value WebEngineView.ToggleBold + Toggles boldness for the selection or at the cursor position. + Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.ToggleItalic + Toggles italics for the selection or at the cursor position. + Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.ToggleUnderline + Toggles underlining of the selection or at the cursor position. + Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.ToggleStrikethrough + Toggles striking through the selection or at the cursor position. + Requires \c contenteditable="true". (Added in Qt 5.10) + + \value WebEngineView.AlignLeft + Aligns the lines containing the selection or the cursor to the left. + Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.AlignCenter + Aligns the lines containing the selection or the cursor at the center. + Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.AlignRight + Aligns the lines containing the selection or the cursor to the right. + Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.AlignJustified + Stretches the lines containing the selection or the cursor so that each + line has equal width. + Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.Indent + Indents the lines containing the selection or the cursor. + Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.Outdent + Outdents the lines containing the selection or the cursor. + Requires \c contenteditable="true". (Added in Qt 5.10) + + \value WebEngineView.InsertOrderedList + Inserts an ordered list at the current cursor position, deleting the current selection. + Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.InsertUnorderedList + 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 +*/ + +/*! + \qmlproperty enumeration WebEngineView::Feature + \deprecated [6.8] Replaced by WebEnginePermission.Feature. + + Describes the platform feature access categories that the user may be asked to grant or deny + access to: + + \value WebEngineView.Geolocation + Location hardware or service. + \value WebEngineView.MediaAudioCapture + Audio capture devices, such as microphones. + \value WebEngineView.MediaVideoCapture + Video devices, such as cameras. + \value WebEngineView.MediaAudioVideoCapture + Both audio and video capture devices. + \value WebEngineView.DesktopVideoCapture + Video output capture, that is, the capture of the user's display. + (Added in Qt 5.10) + \value WebEngineView.DesktopAudioVideoCapture + Both audio and video output capture. (Added in Qt 5.10) + \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() +*/ + +/*! + \qmlproperty enumeration WebEngineView::PrintedPageSizeId + \since QtWebEngine 1.3 + + This enum type lists the available page sizes as defined in the Postscript + PPD standard. + + The enumeration values are mapped from and must match QPageSize::PageSizeId. They are also + duplicated in QPagedPaintDevice and QPrinter. + + The defined sizes are: + + \value WebEngineView.A0 841 x 1189 mm + \value WebEngineView.A1 594 x 841 mm + \value WebEngineView.A2 420 x 594 mm + \value WebEngineView.A3 297 x 420 mm + \value WebEngineView.A4 210 x 297 mm, 8.26 x 11.69 inches + \value WebEngineView.A5 148 x 210 mm + \value WebEngineView.A6 105 x 148 mm + \value WebEngineView.A7 74 x 105 mm + \value WebEngineView.A8 52 x 74 mm + \value WebEngineView.A9 37 x 52 mm + \value WebEngineView.B0 1000 x 1414 mm + \value WebEngineView.B1 707 x 1000 mm + \value WebEngineView.B2 500 x 707 mm + \value WebEngineView.B3 353 x 500 mm + \value WebEngineView.B4 250 x 353 mm + \value WebEngineView.B5 176 x 250 mm, 6.93 x 9.84 inches + \value WebEngineView.B6 125 x 176 mm + \value WebEngineView.B7 88 x 125 mm + \value WebEngineView.B8 62 x 88 mm + \value WebEngineView.B9 44 x 62 mm + \value WebEngineView.B10 31 x 44 mm + \value WebEngineView.C5E 163 x 229 mm + \value WebEngineView.Comm10E 105 x 241 mm, U.S. Common 10 Envelope + \value WebEngineView.DLE 110 x 220 mm + \value WebEngineView.Executive 7.5 x 10 inches, 190.5 x 254 mm + \value WebEngineView.Folio 210 x 330 mm + \value WebEngineView.Ledger 431.8 x 279.4 mm + \value WebEngineView.Legal 8.5 x 14 inches, 215.9 x 355.6 mm + \value WebEngineView.Letter 8.5 x 11 inches, 215.9 x 279.4 mm + \value WebEngineView.Tabloid 279.4 x 431.8 mm + \value WebEngineView.Custom Unknown, or a user defined size. + \value WebEngineView.A10 + \value WebEngineView.A3Extra + \value WebEngineView.A4Extra + \value WebEngineView.A4Plus + \value WebEngineView.A4Small + \value WebEngineView.A5Extra + \value WebEngineView.B5Extra + \value WebEngineView.JisB0 + \value WebEngineView.JisB1 + \value WebEngineView.JisB2 + \value WebEngineView.JisB3 + \value WebEngineView.JisB4 + \value WebEngineView.JisB5 + \value WebEngineView.JisB6 + \value WebEngineView.JisB7 + \value WebEngineView.JisB8 + \value WebEngineView.JisB9 + \value WebEngineView.JisB10 + \value WebEngineView.AnsiA = \c Letter + \value WebEngineView.AnsiB = \c Ledger + \value WebEngineView.AnsiC + \value WebEngineView.AnsiD + \value WebEngineView.AnsiE + \value WebEngineView.LegalExtra + \value WebEngineView.LetterExtra + \value WebEngineView.LetterPlus + \value WebEngineView.LetterSmall + \value WebEngineView.TabloidExtra + \value WebEngineView.ArchA + \value WebEngineView.ArchB + \value WebEngineView.ArchC + \value WebEngineView.ArchD + \value WebEngineView.ArchE + \value WebEngineView.Imperial7x9 + \value WebEngineView.Imperial8x10 + \value WebEngineView.Imperial9x11 + \value WebEngineView.Imperial9x12 + \value WebEngineView.Imperial10x11 + \value WebEngineView.Imperial10x13 + \value WebEngineView.Imperial10x14 + \value WebEngineView.Imperial12x11 + \value WebEngineView.Imperial15x11 + \value WebEngineView.ExecutiveStandard + \value WebEngineView.Note + \value WebEngineView.Quarto + \value WebEngineView.Statement + \value WebEngineView.SuperA + \value WebEngineView.SuperB + \value WebEngineView.Postcard + \value WebEngineView.DoublePostcard + \value WebEngineView.Prc16K + \value WebEngineView.Prc32K + \value WebEngineView.Prc32KBig + \value WebEngineView.FanFoldUS + \value WebEngineView.FanFoldGerman + \value WebEngineView.FanFoldGermanLegal + \value WebEngineView.EnvelopeB4 + \value WebEngineView.EnvelopeB5 + \value WebEngineView.EnvelopeB6 + \value WebEngineView.EnvelopeC0 + \value WebEngineView.EnvelopeC1 + \value WebEngineView.EnvelopeC2 + \value WebEngineView.EnvelopeC3 + \value WebEngineView.EnvelopeC4 + \value WebEngineView.EnvelopeC5 = \c C5E + \value WebEngineView.EnvelopeC6 + \value WebEngineView.EnvelopeC65 + \value WebEngineView.EnvelopeC7 + \value WebEngineView.EnvelopeDL = \c DLE + \value WebEngineView.Envelope9 + \value WebEngineView.Envelope10 = \c Comm10E + \value WebEngineView.Envelope11 + \value WebEngineView.Envelope12 + \value WebEngineView.Envelope14 + \value WebEngineView.EnvelopeMonarch + \value WebEngineView.EnvelopePersonal + \value WebEngineView.EnvelopeChou3 + \value WebEngineView.EnvelopeChou4 + \value WebEngineView.EnvelopeInvite + \value WebEngineView.EnvelopeItalian + \value WebEngineView.EnvelopeKaku2 + \value WebEngineView.EnvelopeKaku3 + \value WebEngineView.EnvelopePrc1 + \value WebEngineView.EnvelopePrc2 + \value WebEngineView.EnvelopePrc3 + \value WebEngineView.EnvelopePrc4 + \value WebEngineView.EnvelopePrc5 + \value WebEngineView.EnvelopePrc6 + \value WebEngineView.EnvelopePrc7 + \value WebEngineView.EnvelopePrc8 + \value WebEngineView.EnvelopePrc9 + \value WebEngineView.EnvelopePrc10 + \value WebEngineView.EnvelopeYou4 + \value WebEngineView.LastPageSize = \c EnvelopeYou4 + + \sa WebEngineView::printToPdf() +*/ + +/*! + \qmlproperty enumeration WebEngineView::PrintedPageOrientation + \since QtWebEngine 1.3 + + Describes the orientation of a PDF document that gets created from the WebEngineView's contents. + The enumeration values are mapped from and must match QPageLayout::Orientation. + + \value WebEngineView.Portrait + The document will be created using portrait orientation. + + \value WebEngineView.Landscape + The document will be created using landscape orientation. + + \sa WebEngineView::printToPdf() +*/ + +/*! + \qmlproperty bool WebEngineView::activeFocusOnPress + \since QtWebEngine 1.2 + + Specifies whether the view should gain active focus when pressed. + The default value is \c true. +*/ + +/*! + \qmlproperty color WebEngineView::backgroundColor + \since QtWebEngine 1.2 + + Changes the color of the WebEngineView's background, behind the document's + body. Can be set to \c "transparent" or to a translucent color to see + through the document or to match the web content in a hybrid app to prevent + the white flashes that may appear during loading. + + The default value is white. +*/ + +/*! + \qmlproperty bool WebEngineView::audioMuted + \brief The state of whether the current page audio is muted. + \since QtWebEngine 1.3 + \sa recentlyAudible +*/ + +/*! + \qmlsignal WebEngineView::audioMutedChanged(bool muted) + \since QtWebEngine 1.3 + + This signal is emitted when the value of \a muted changes. The value is + specified using the \l audioMuted property. + \note Not to be confused with a specific HTML5 audio / video element being muted. + + \sa audioMuted, recentlyAudibleChanged +*/ + +/*! + \qmlproperty bool WebEngineView::recentlyAudible + \brief Returns the current page's audible state (audio was recently played, or not). + \since QtWebEngine 1.3 + \readonly + \sa audioMuted, recentlyAudibleChanged +*/ + +/*! + \qmlsignal WebEngineView::recentlyAudibleChanged(bool recentlyAudible) + \since QtWebEngine 1.3 + + This signal is emitted when the page's audible state, specified by + \a recentlyAudible, is changed, due to audio being played or stopped. + + \note The signal is also emitted when the \l audioMuted property changes. + Also if the audio is paused, this signal is emitted with an approximate \b{two-second + delay}, from the moment the audio is paused. + + 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. + This means that the signal is emitted both when any kind of sound is + generated and when everything is completely silent within a web page, + regardless of the number of audio streams. + + Spurious signal emissions might also happen. For example, when sound is + stopped, this signal gets emitted first with a value of \c true, and then + with a value of \c false. Further, when audio starts playing, the signal is + emitted twice with a value of \c true. + + \sa recentlyAudible +*/ + +/*! + \qmlsignal WebEngineView::pdfPrintingFinished(string filePath, bool success) + \since QtWebEngine 1.5 + + This signal is emitted when printing the web page into a PDF file has + finished. + \a filePath will contain the path the file was requested to be created + at, and \a success will be \c true if the file was successfully created and + \c false otherwise. + + \sa printToPdf() +*/ + +/*! + \qmlmethod void WebEngineView::printToPdf(const string filePath, PrintedPageSizeId pageSizeId, PrintedPageOrientation orientation) + \since QtWebEngine 1.3 + + Prints the WebEngineView's current content to a PDF document and stores it + under \a filePath. The document's size will be determined by the value of + \a pageSizeId and its orientation will be determined using \a orientation. + + This method issues an asynchronous request for printing the web page into a + PDF and returns immediately. To be informed about the result of the + request, connect to the signal pdfPrintingFinished(). + + If you leave out \a pageSizeId, it defaults to \c A4. If you leave out + \a orientation, it defaults to \c Portrait. + + \sa pdfPrintingFinished() +*/ + +/*! + \qmlmethod void WebEngineView::printToPdf(variant resultCallback, PrintedPageSizeId pageSizeId, PrintedPageOrientation orientation) + \since QtWebEngine 1.3 + + Prints the WebEngineView's current content to a PDF document and returns it in a byte array. The document's size will be determined + by the value of \a pageSizeId and its orientation will be determined using \a orientation. + + The \a resultCallback must take a string parameter. This string will contain the document's data upon successful printing and an empty + string otherwise. + + If you leave out \a pageSizeId, it defaults to \c A4. If you leave out + \a orientation, it defaults to \c Portrait. +*/ + +/*! + \qmlmethod void WebEngineView::replaceMisspelledWord(const QString &replacement) + \since QtWebEngine 1.3 + + Replace the current misspelled word with \a replacement. +*/ + +/*! + \qmlsignal WebEngineView::wasRecentlyAudibleChanged(bool wasRecentlyAudible) + \since QtWebEngine 1.3 + + This signal is emitted when the page's audible state, specified by + \a wasRecentlyAudible, is changed, due to audio being played or stopped. + + \note The signal is also emitted when calling the setAudioMuted method. +*/ + +/*! + \qmlsignal WebEngineView::authenticationDialogRequested(AuthenticationDialogRequest request) + \since QtWebEngine 1.4 + + This signal is emitted when an authentication dialog is requested. + + The \a request can be handled by using the methods of the AuthenticationDialogRequest + type. + + \note Signal handlers need to call \c{request.accepted = true} to prevent a + default dialog from showing up. Make sure to call either + AuthenticationDialogRequest::dialogAccept() or AuthenticationDialogRequest::dialogReject() + afterwards. +*/ + +/*! + \qmlsignal WebEngineView::javaScriptDialogRequested(JavaScriptDialogRequest request) + \since QtWebEngine 1.4 + + This signal is emitted when a JavaScript dialog is requested. + + The \a request can be handled by using the methods of the JavaScriptDialogRequest + type. + + \note Signal handlers need to call \c{request.accepted = true} to prevent a + default dialog from showing up. Make sure to call either + JavaScriptDialogRequest::dialogAccept() or JavaScriptDialogRequest::dialogReject() + afterwards. +*/ + +/*! + \qmlsignal WebEngineView::colorDialogRequested(ColorDialogRequest request) + \since QtWebEngine 1.4 + + This signal is emitted when a color picker dialog is requested. + + The \a request can be handled by using the methods of the ColorDialogRequest + type. + + \note Signal handlers need to call \c{request.accepted = true} to prevent a + default dialog from showing up. Make sure to call either + ColorDialogRequest::dialogAccept() or ColorDialogRequest::dialogReject() afterwards. +*/ + +/*! + \qmlsignal WebEngineView::fileDialogRequested(FileDialogRequest request) + \since QtWebEngine 1.4 + + This signal is emitted when a file picker dialog is requested. + + The \a request can be handled by using the methods of the FileDialogRequest + type. + + \note Signal handlers need to call \c{request.accepted = true} to prevent a + default dialog from showing up. Make sure to call either FileDialogRequest::dialogAccept() + or FileDialogRequest::dialogReject() afterwards. +*/ + +/*! + \qmlsignal WebEngineView::contextMenuRequested(ContextMenuRequest request) + \since QtWebEngine 1.4 + + This signal is emitted when a context menu is requested. + + The \a request can be handled by using the properties of the ContextMenuRequest + type. + + \note Signal handlers need to call \c{request.accepted = true} to prevent a + default context menu from showing up. +*/ + +/*! \qmlsignal WebEngineView::navigationRequested(WebEngineNavigationRequest request) + This signal is emitted when the navigation request \a request is issued. +*/ + +/*! + \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. + + For further details, see https://crbug.com/1233525 + + \sa QuotaRequest +*/ + +/*! + \qmlsignal WebEngineView::registerProtocolHandlerRequested(RegisterProtocolHandlerRequest request) + \since QtWebEngine 1.7 + + This signal is emitted when the web page tries to register a custom protocol + by issuing a \l registerProtocolHandler \a request. + + \sa RegisterProtocolHandlerRequest +*/ + +/*! + \qmlsignal WebEngineView::geometryChangeRequested(rect geometry, rect frameGeometry) + \since QtWebEngine 1.7 + + This signal is emitted whenever the document wants to change the position and size of the + page to \a frameGeometry. This can happen for example through JavaScript. + + While \a frameGeometry includes, \a geometry excludes the size of frame margins. + + \note Geometry related properties of QML Window expect a size excluding the window + decoration. You have to use \a geometry to handle this signal correctly. + + \qml + onGeometryChangeRequested: { + window.x = geometry.x + window.y = geometry.y + window.width = geometry.width + window.height = geometry.height + } + \endqml +*/ + +/*! + \qmlproperty WebEngineView WebEngineView::inspectedView + \since QtWebEngine 1.7 + + The view this view is currently inspecting, if any. Setting it + will navigate to an internal URL with the developer tools of + the view set. + + It is recommended to unset this property when developer tools + are not visible; otherwise some debug information may appear + in the inspected WebEngineView. + + \sa devToolsView +*/ + +/*! + \qmlproperty WebEngineView WebEngineView::devToolsView + \since QtWebEngine 1.7 + + The view currently hosting the developer tools for this view. + Setting it to a new view will navigate that view to an internal + URL with the developer tools, and bind it to this view. + + \sa inspectedView +*/ + +/*! + \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 + + Returns a \l WebEngineAction for the specified \l WebAction \a action. + WebEngineView also takes care of implementing the action, + so that upon triggering the corresponding action is performed on the view. + + \code + var copyAction = webEngineView.action(WebEngineView.Copy); + \endcode + + \sa WebEngineAction +*/ + +/*! + \qmlsignal WebEngineView::printRequested + \since QtWebEngine 1.8 + + This signal is emitted when the JavaScript \c{window.print()} method is called on the main + frame, or the user pressed the print button of PDF viewer plugin. + Typically, the signal handler can simply call printToPdf(). + + Since QtWebEngine 6.8, this signal is only emitted for the main frame, instead of being emitted + for any frame that requests printing. + + \sa printToPdf +*/ + +/*! + \qmlsignal WebEngineView::printRequestedByFrame(webEngineFrame frame) + \since QtWebEngine 6.8 + + This signal is emitted when the JavaScript \c{window.print()} method is called on \a frame. + If the frame is the main frame, \c{printRequested} is emitted instead. + + \sa printRequested +*/ + +/*! + \qmlsignal WebEngineView::selectClientCertificate(WebEngineClientCertificateSelection clientCertificateSelection) + \since QtWebEngine 1.9 + + This signal is emitted when a web site requests an SSL client certificate, and one or more were + found in the system's client certificate store. + + Handling the signal is asynchronous, and loading will be waiting until a certificate is selected, + or the last copy of \a clientCertificateSelection is destroyed. + + If the signal is not handled, \a clientCertificateSelection is automatically destroyed, and loading + will continue without a client certificate. + + \sa WebEngineClientCertificateSelection +*/ + +/*! + \qmlsignal WebEngineView::tooltipRequested(TooltipRequest request) + \since QtWebEngine 1.10 + + This signal is emitted when the web page sends a \a request to show a tooltip at + a specified position. + + \note Signal handlers need to call \c{request.accepted = true} to prevent a default tooltip from showing up. + + \sa TooltipRequest +*/ + +/*! + \qmlproperty enumeration WebEngineView::LifecycleState + \since QtWebEngine 1.10 + + This enum describes the lifecycle state of the page: + + \value WebEngineView.LifecycleState.Active + Normal state. + \value WebEngineView.LifecycleState.Frozen + Low CPU usage state where most HTML task sources are suspended. + \value WebEngineView.LifecycleState.Discarded + Very low resource usage state where the entire browsing context is discarded. + + \sa lifecycleState, {Page Lifecycle API}, {WebEngine Lifecycle Example} +*/ + +/*! + \qmlproperty LifecycleState WebEngineView::lifecycleState + \since QtWebEngine 1.10 + + \brief The current lifecycle state of the page. + + The following restrictions are enforced by the setter: + + \list + \li A visible page must remain in the \c{Active} state. + \li If the page is being inspected by a \l{devToolsView} then both pages must + remain in the \c{Active} states. + \li A page in the \c{Discarded} state can only transition to the \c{Active} + state. This will cause a reload of the page. + \endlist + + These are the only hard limits on the lifecycle state, but see also + \l{recommendedState} for the recommended soft limits. + + \sa recommendedState, {Page Lifecycle API}, {WebEngine Lifecycle Example} +*/ + +/*! + \qmlproperty LifecycleState WebEngineView::recommendedState + \since QtWebEngine 1.10 + + \brief The recommended limit for the lifecycle state of the page. + + Setting the lifecycle state to a lower resource usage state than the + recommended state may cause side-effects such as stopping background audio + playback or loss of HTML form input. Setting the lifecycle state to a higher + resource state is however completely safe. + + \sa lifecycleState, {Page Lifecycle API}, {WebEngine Lifecycle Example} +*/ + +/*! + \qmltype FindTextResult + \instantiates QWebEngineFindTextResult + \inqmlmodule QtWebEngine + \since QtWebEngine 1.10 + + \brief A utility type for encapsulating the result of a string search on a page. + + \sa WebEngineView::findTextFinished() +*/ + +/*! + \qmlproperty int FindTextResult::numberOfMatches + \readonly + + \brief The number of matches found. +*/ + +/*! + \qmlproperty int FindTextResult::activeMatch + \readonly + + \brief The index of the currently highlighted match. +*/ + +/*! + \qmlsignal WebEngineView::findTextFinished(FindTextResult result) + \since QtWebEngine 1.10 + + This signal is emitted when a string search on a page is completed. \a result is + the result of the string search. + + \sa findText(), FindTextResult +*/ + +/*! + \qmlproperty qint64 WebEngineView::renderProcessPid + \brief Returns the process ID (PID) of the render process assigned to the + current page's main frame. + \since QtWebEngine 1.11 + \readonly + + If no render process is available yet, \c 0 is returned. + + \sa renderProcessPidChanged +*/ +/*! + \qmlsignal WebEngineView::renderProcessPidChanged(qint64 pid) + \since QtWebEngine 1.11 + \readonly + + If no render process is available yet, \c 0 is returned. + This signal is emitted when \a pid (process ID) of the page's underlying + render process changed. + + \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. + +*/ + +/*! + \qmlproperty webEngineFrame WebEngineView::mainFrame + \since QtWebEngine 6.8 + + The main, top-level frame of the page. All other frames on this page are accessible + as children of the main frame. + */ + +/*! + \qmlmethod webEngineFrame WebEngineView::findFrameByName(string name) + \since QtWebEngine 6.8 + + Returns the frame with the given \a name. If there are multiple frames with the same + name, which one is returned is arbitrary. If no frame was found, returns an + \l{webEngineFrame::isValid}{invalid} frame. +*/ + +/*! + \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 +*/ + +/*! + \qmlsignal WebEngineView::zoomFactorChanged(qreal factor); + \since QtWebEngine 6.8 + + This signal is emitted whenever the zoom \a factor for the page changes. + + \sa zoomFactor +*/ + + \sa {WebEngine Qt Quick Custom Touch Handle Example} +*/ |