diff options
Diffstat (limited to 'src/webenginequick/doc/src')
8 files changed, 248 insertions, 71 deletions
diff --git a/src/webenginequick/doc/src/qtwebengine-examples.qdoc b/src/webenginequick/doc/src/qtwebengine-examples.qdoc index b3eb548e5..eebf18ba1 100644 --- a/src/webenginequick/doc/src/qtwebengine-examples.qdoc +++ b/src/webenginequick/doc/src/qtwebengine-examples.qdoc @@ -5,7 +5,6 @@ \group webengine-examples \title Qt WebEngine Quick Examples \brief Examples demonstrating the \QWE usage. - \ingroup all-examples These examples and demonstrations show a range of different uses for \l{Qt WebEngine}, from displaying Web pages within a QML user interface to an implementation of diff --git a/src/webenginequick/doc/src/qtwebengine-module.qdoc b/src/webenginequick/doc/src/qtwebengine-module.qdoc index 21d8b4749..6f50cc2f4 100644 --- a/src/webenginequick/doc/src/qtwebengine-module.qdoc +++ b/src/webenginequick/doc/src/qtwebengine-module.qdoc @@ -12,11 +12,6 @@ The \QWE Quick module exposes C++ functionality to Qt Quick. - To include the definitions of the module's classes, use the - following directive: - - \snippet qtwebengine_build_snippet.qdoc 1 - \if !defined(qtforpython) To link against the module, add the following to your qmake project file: diff --git a/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc b/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc index 7899fad56..ecf3a4a6e 100644 --- a/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc +++ b/src/webenginequick/doc/src/qtwebengine-qmlmodule.qdoc @@ -8,11 +8,6 @@ \ingroup qtwebengine-modules \ingroup qmlmodules - The QML types can be imported into your application using the following import statements in - your .qml file: - - \snippet qtwebengine_build_snippet.qdoc 1 - To link against the module using build with qmake, add the following QT variable to your qmake .pro file: @@ -22,4 +17,13 @@ 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 index 579d78008..01f4ec286 100644 --- a/src/webenginequick/doc/src/quota_request.qdoc +++ b/src/webenginequick/doc/src/quota_request.qdoc @@ -6,8 +6,12 @@ \instantiates QWebEngineQuotaRequest \inqmlmodule QtWebEngine \since QtWebEngine 1.7 + \deprecated [6.5] Requesting host quota is no longer supported by Chromium. - \brief A utility type for the WebEngineView::quotaRequested() signal. + The behavior of navigator.webkitPersistentStorage + is identical to navigator.webkitTemporaryStorage. + + For further details, see https://crbug.com/1233525 \sa WebEngineView::quotaRequested() */ @@ -15,36 +19,18 @@ /*! \qmlproperty url QuotaRequest::origin \readonly - - The URL of the web page that issued the quota request. */ /*! \qmlproperty qint64 QuotaRequest::requestedSize \readonly - - Contains the size of the requested disk space in bytes. */ /*! \qmlmethod void QuotaRequest::accept() - - Accepts the quota request. - - \qml - WebEngineView { - onQuotaRequested: function(request) { - if (request.requestedSize <= 5 * 1024 * 1024) - request.accept(); - else - request.reject(); - } - } - \endqml */ /*! \qmlmethod void QuotaRequest::reject() - Rejects the quota request. */ diff --git a/src/webenginequick/doc/src/webengine_certificate_error.qdoc b/src/webenginequick/doc/src/webengine_certificate_error.qdoc index aec8e2d42..93bad9fb1 100644 --- a/src/webenginequick/doc/src/webengine_certificate_error.qdoc +++ b/src/webenginequick/doc/src/webengine_certificate_error.qdoc @@ -9,7 +9,7 @@ \brief A utility type for ignoring certificate errors or rejecting erroneous certificates. - This QML type contains information about a certificate error that occurred. The \l error + This QML type contains information about a certificate error that occurred. The \l type property holds the reason that the error occurred and the \l description property holds a short localized description of the error. The \l url property holds the URL that triggered the error. @@ -49,7 +49,7 @@ The URL that triggered the error. */ /*! - \qmlproperty enumeration WebEngineCertificateError::error + \qmlproperty enumeration WebEngineCertificateError::type \readonly The type of the error. diff --git a/src/webenginequick/doc/src/webengineframe.qdoc b/src/webenginequick/doc/src/webengineframe.qdoc new file mode 100644 index 000000000..e1c63b923 --- /dev/null +++ b/src/webenginequick/doc/src/webengineframe.qdoc @@ -0,0 +1,99 @@ +// 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). +*/ + +/*! + \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. +*/ diff --git a/src/webenginequick/doc/src/webenginescript.qdoc b/src/webenginequick/doc/src/webenginescript.qdoc index 5919b29e3..9708ffbf8 100644 --- a/src/webenginequick/doc/src/webenginescript.qdoc +++ b/src/webenginequick/doc/src/webenginescript.qdoc @@ -32,7 +32,7 @@ \l{WebEngineScriptCollection::find}{WebEngineScriptCollection.find} method. */ -*! +/*! \qmlproperty url WebEngineScript::sourceUrl This property holds the remote source location of the user script (if any). diff --git a/src/webenginequick/doc/src/webengineview_lgpl.qdoc b/src/webenginequick/doc/src/webengineview_lgpl.qdoc index 6e3d9ebe3..bbefcd2bc 100644 --- a/src/webenginequick/doc/src/webengineview_lgpl.qdoc +++ b/src/webenginequick/doc/src/webengineview_lgpl.qdoc @@ -1,24 +1,7 @@ -/* - * Copyright (C) 2019 The Qt Company Ltd. - * Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies) - * Copyright (c) 2012 Hewlett-Packard Development Company, L.P. - * - * This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU Library General Public - * License as published by the Free Software Foundation; either - * version 2 of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Library General Public License for more details. - * - * You should have received a copy of the GNU Library General Public License - * along with this program; see the file COPYING.LIB. If not, write to - * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - * Boston, MA 02110-1301, USA. - * - */ +// Copyright (C) 2019 The Qt Company Ltd. +// Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies) +// Copyright (c) 2012 Hewlett-Packard Development Company, L.P. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // The documentation in this file was imported from QtWebKit and is thus constrained // by its LGPL license. @@ -41,7 +24,7 @@ \l QtWebEngineQuick::initialize in the application main source file, as illustrated by the following code snippet: - \quotefromfile webenginequick/minimal/main.cpp + \quotefromfile minimal/main.cpp \skipto main \printuntil } @@ -56,7 +39,7 @@ The following sample QML application loads a web page using the \c url property: - \quotefromfile webenginequick/minimal/main.qml + \quotefromfile minimal/main.qml \skipto import \printuntil /^\}/ @@ -373,9 +356,8 @@ This method offers a lower-level alternative to the \c{url} property, which references HTML pages via URL. - External objects, such as stylesheets or images referenced in the HTML - document, should be located relative to \a baseUrl. For external objects to - be loaded, \c baseUrl cannot be empty. For example, if \a html + \a baseUrl is optional and used to resolve relative URLs in the document, + such as referenced images or stylesheets. For example, if \a html is retrieved from \c http://www.example.com/documents/overview.html, which is the base URL, then an image referenced with the relative URL, \c diagram.png, should be at \c{http://www.example.com/documents/diagram.png}. @@ -385,6 +367,8 @@ /*! \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, @@ -399,8 +383,10 @@ 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. + 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. @@ -804,6 +790,7 @@ 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) @@ -848,6 +835,10 @@ Inserts an unordered list at the current cursor position, deleting the current selection. Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.ChangeTextDirectionLTR + Changes text direction to left-to-right in the focused input element. (Added in Qt 6.6) + \value WebEngineView.ChangeTextDirectionRTL + Changes text direction to right-to-left in the focused input element. (Added in Qt 6.6) \omitvalue WebActionCount */ @@ -865,13 +856,22 @@ Video devices, such as cameras. \value WebEngineView.MediaAudioVideoCapture Both audio and video capture devices. - \value DesktopVideoCapture + \value WebEngineView.DesktopVideoCapture Video output capture, that is, the capture of the user's display. (Added in Qt 5.10) - \value DesktopAudioVideoCapture + \value WebEngineView.DesktopAudioVideoCapture Both audio and video output capture. (Added in Qt 5.10) - \value WebEnginView.Notifications + \value WebEngineView.Notifications Web notifications for the end-user. + \value WebEngineView.ClipboardReadWrite + Read and write access for the clipboard. If both \l{WebEngineSettings::JavascriptCanPaste} + {JavascriptCanPaste} and \l{WebEngineSettings::JavascriptCanAccessClipboard} + {JavascriptCanAccessClipboard} settings are enabled, this permission will always be granted + automatically and no feature requests will be made. + (Added in Qt 6.8) + \value WebEngineView.LocalFontsAccess + Access to the fonts installed on the user's machine. Only available on desktop platforms. + (Added in Qt 6.8) \sa featurePermissionRequested(), grantFeaturePermission() */ @@ -1013,8 +1013,6 @@ \value WebEngineView.EnvelopePrc10 \value WebEngineView.EnvelopeYou4 \value WebEngineView.LastPageSize = \c EnvelopeYou4 - \omitvalue NPageSize - \omitvalue NPaperSize \sa WebEngineView::printToPdf() */ @@ -1247,10 +1245,13 @@ /*! \qmlsignal WebEngineView::quotaRequested(QuotaRequest request) \since QtWebEngine 1.7 + \deprecated [6.5] This signal is no longer emitted. + + Requesting host quota is no longer supported by Chromium. + The behavior of navigator.webkitPersistentStorage + is identical to navigator.webkitTemporaryStorage. - This signal is emitted when the web page issues a \a request for a larger persistent storage - than the application's current allocation in File System API. The default quota - is 0 bytes. + For further details, see https://crbug.com/1233525 \sa QuotaRequest */ @@ -1314,6 +1315,20 @@ */ /*! + \qmlproperty WebEngineView WebEngineView::devToolsId + \since QtWebEngine 6.6 + \readonly + + The id of the developer tools host associated with this page. + + If remote debugging is enabled (see \l{Qt WebEngine Developer Tools}), the id can be used to + build the URL to connect to the developer tool websocket: + \c{ws://localhost:<debugggin-port>/devtools/page/<id>)}. The websocket can be used to to interact + with the page using the \l{https://chromedevtools.github.io/devtools-protocol/}{DevTools + Protocol}. +*/ + +/*! \qmlmethod WebEngineAction WebEngineView::action(WebAction action) \since 5.12 @@ -1329,10 +1344,11 @@ */ /*! - \qmlsignal WebEngineView::printRequest + \qmlsignal WebEngineView::printRequested \since QtWebEngine 1.8 - This signal is emitted when the JavaScript \c{window.print()} method is called. + This signal is emitted when the JavaScript \c{window.print()} method is called or the user pressed the print + button of PDF viewer plugin. Typically, the signal handler can simply call printToPdf(). \sa printToPdf @@ -1515,6 +1531,84 @@ // ... } \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} |