diff options
Diffstat (limited to 'src/webenginequick/doc/src/webengineview_lgpl.qdoc')
-rw-r--r-- | src/webenginequick/doc/src/webengineview_lgpl.qdoc | 214 |
1 files changed, 160 insertions, 54 deletions
diff --git a/src/webenginequick/doc/src/webengineview_lgpl.qdoc b/src/webenginequick/doc/src/webengineview_lgpl.qdoc index 7c13d140a..eeae34dcc 100644 --- a/src/webenginequick/doc/src/webengineview_lgpl.qdoc +++ b/src/webenginequick/doc/src/webengineview_lgpl.qdoc @@ -1,24 +1,7 @@ -/* - * Copyright (C) 2019 The Qt Company Ltd. - * Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies) - * Copyright (c) 2012 Hewlett-Packard Development Company, L.P. - * - * This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU Library General Public - * License as published by the Free Software Foundation; either - * version 2 of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Library General Public License for more details. - * - * You should have received a copy of the GNU Library General Public License - * along with this program; see the file COPYING.LIB. If not, write to - * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - * Boston, MA 02110-1301, USA. - * - */ +// Copyright (C) 2019 The Qt Company Ltd. +// Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies) +// Copyright (c) 2012 Hewlett-Packard Development Company, L.P. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // The documentation in this file was imported from QtWebKit and is thus constrained // by its LGPL license. @@ -41,7 +24,7 @@ \l QtWebEngineQuick::initialize in the application main source file, as illustrated by the following code snippet: - \quotefromfile webengine/minimal/main.cpp + \quotefromfile minimal/main.cpp \skipto main \printuntil } @@ -56,7 +39,7 @@ The following sample QML application loads a web page using the \c url property: - \quotefromfile webengine/minimal/main.qml + \quotefromfile minimal/main.qml \skipto import \printuntil /^\}/ @@ -74,10 +57,10 @@ \section2 Interaction By default, links to different pages load within the same WebEngineView object, but web sites - may request them to be opened as a new tab, window, or dialog. The \l newViewRequested() signal + may request them to be opened as a new tab, window, or dialog. The \l newWindowRequested() signal is emitted when a request to load the page in a separate web engine view is issued. The NewViewDestination property describes how the new view should be opened. In addition, the - WebEngineNewViewRequest utility type can be used to load web pages in separate web engine views. + WebEngineNewWindowRequest utility type can be used to load web pages in separate web engine views. The \l findText() method can be used to search for a string on a web page, using the options described by \l FindFlags. @@ -327,11 +310,13 @@ /*! - \qmlproperty list<WebEngineScript> WebEngineView::userScripts + \qmlproperty WebEngineScriptCollection WebEngineView::userScripts \readonly \since QtWebEngine 1.1 - List of WebEngineScript objects attached to the view. + The user scripts' collection associated with the view. + + \sa WebEngineScriptCollection */ /*! @@ -371,9 +356,8 @@ This method offers a lower-level alternative to the \c{url} property, which references HTML pages via URL. - External objects, such as stylesheets or images referenced in the HTML - document, should be located relative to \a baseUrl. For external objects to - be loaded, \c baseUrl cannot be empty. For example, if \a html + \a baseUrl is optional and used to resolve relative URLs in the document, + such as referenced images or stylesheets. For example, if \a html is retrieved from \c http://www.example.com/documents/overview.html, which is the base URL, then an image referenced with the relative URL, \c diagram.png, should be at \c{http://www.example.com/documents/diagram.png}. @@ -570,8 +554,8 @@ */ /*! - \qmlsignal WebEngineView::newViewRequested(WebEngineNewViewRequest request) - \since QtWebEngine 1.1 + \qmlsignal WebEngineView::newWindowRequested(WebEngineNewWindowRequest request) + \since QtWebEngine 2.0 This signal is emitted when \a request is issued to load a page in a separate web engine view. This can either be because the current page requested it explicitly @@ -579,23 +563,23 @@ while holding Shift, Ctrl, or a built-in combination that triggers the page to open in a new window. - The signal is handled by calling acceptAsNewView() on the destination view. + The signal is handled by calling acceptAsNewWindow() on the destination view. If this signal is not handled, the requested load will fail. An example implementation: \snippet qtwebengine_webengineview_newviewrequested.qml 0 - \sa WebEngineNewViewRequest, {WebEngine Quick Nano Browser} + \sa WebEngineNewWindowRequest, {WebEngine Quick Nano Browser} */ /*! - \qmlmethod void WebEngineView::acceptAsNewView(QWebEngineNewWindowRequest *request) + \qmlmethod void WebEngineView::acceptAsNewWindow(QWebEngineNewWindowRequest *request) \since QtWebEngine 2.0 - Handle the newViewRequested signal by opening the \a request in this view. + Handle the newWindowRequested signal by opening the \a request in this view. - \sa newViewRequested + \sa newWindowRequested */ /*! @@ -765,10 +749,10 @@ Open the current link in the current window. (Added in Qt 5.6) \value WebEngineView.OpenLinkInNewWindow Open the current link in a new window. Requires a handler for the - \l newViewRequested() signal. (Added in Qt 5.6) + \l newWindowRequested() signal. (Added in Qt 5.6) \value WebEngineView.OpenLinkInNewTab Open the current link in a new tab. Requires a handler for the - \l newViewRequested() signal. (Added in Qt 5.6) + \l newWindowRequested() signal. (Added in Qt 5.6) \value WebEngineView.CopyLinkToClipboard Copy the current link to the clipboard. (Added in Qt 5.6) \value WebEngineView.CopyImageToClipboard @@ -802,9 +786,10 @@ Exit the fullscreen mode. (Added in Qt 5.6) \value WebEngineView.SavePage Save the current web page to disk. (Added in Qt 5.7) + \omitvalue WebEngineView.OpenLinkInNewBackgroundTab \value WebEngineView.ViewSource Show the source of the current page in a new tab. Requires a handler for the - \l newViewRequested() signal. (Added in Qt 5.8) + \l newWindowRequested() signal. (Added in Qt 5.8) \value WebEngineView.ToggleBold Toggles boldness for the selection or at the cursor position. @@ -846,6 +831,10 @@ Inserts an unordered list at the current cursor position, deleting the current selection. Requires \c contenteditable="true". (Added in Qt 5.10) + \value WebEngineView.ChangeTextDirectionLTR + Changes text direction to left-to-right in the focused input element. (Added in Qt 6.6) + \value WebEngineView.ChangeTextDirectionRTL + Changes text direction to right-to-left in the focused input element. (Added in Qt 6.6) \omitvalue WebActionCount */ @@ -863,13 +852,22 @@ Video devices, such as cameras. \value WebEngineView.MediaAudioVideoCapture Both audio and video capture devices. - \value DesktopVideoCapture + \value WebEngineView.DesktopVideoCapture Video output capture, that is, the capture of the user's display. (Added in Qt 5.10) - \value DesktopAudioVideoCapture + \value WebEngineView.DesktopAudioVideoCapture Both audio and video output capture. (Added in Qt 5.10) - \value WebEnginView.Notifications + \value WebEngineView.Notifications Web notifications for the end-user. + \value WebEngineView.ClipboardReadWrite + Read and write access for the clipboard. If both \l{WebEngineSettings::JavascriptCanPaste} + {JavascriptCanPaste} and \l{WebEngineSettings::JavascriptCanAccessClipboard} + {JavascriptCanAccessClipboard} settings are enabled, this permission will always be granted + automatically and no feature requests will be made. + (Added in Qt 6.8) + \value WebEngineView.LocalFontsAccess + Access to the fonts installed on the user's machine. Only available on desktop platforms. + (Added in Qt 6.8) \sa featurePermissionRequested(), grantFeaturePermission() */ @@ -1011,8 +1009,6 @@ \value WebEngineView.EnvelopePrc10 \value WebEngineView.EnvelopeYou4 \value WebEngineView.LastPageSize = \c EnvelopeYou4 - \omitvalue NPageSize - \omitvalue NPaperSize \sa WebEngineView::printToPdf() */ @@ -1090,8 +1086,6 @@ Also if the audio is paused, this signal is emitted with an approximate \b{two-second delay}, from the moment the audio is paused. - This signal is also emitted for Flash plugin audio. - If a web page contains two videos that are started in sequence, this signal gets emitted only once, for the first video to generate sound. After both videos are stopped, the signal is emitted upon the last sound generated. @@ -1167,8 +1161,6 @@ \a wasRecentlyAudible, is changed, due to audio being played or stopped. \note The signal is also emitted when calling the setAudioMuted method. - Also if the audio is paused, this signal is emitted with an approximate \b{2 second - delay}, from the moment the audio is paused. */ /*! @@ -1249,10 +1241,13 @@ /*! \qmlsignal WebEngineView::quotaRequested(QuotaRequest request) \since QtWebEngine 1.7 + \deprecated [6.5] This signal is no longer emitted. + + Requesting host quota is no longer supported by Chromium. + The behavior of navigator.webkitPersistentStorage + is identical to navigator.webkitTemporaryStorage. - This signal is emitted when the web page issues a \a request for a larger persistent storage - than the application's current allocation in File System API. The default quota - is 0 bytes. + For further details, see https://crbug.com/1233525 \sa QuotaRequest */ @@ -1316,6 +1311,20 @@ */ /*! + \qmlproperty WebEngineView WebEngineView::devToolsId + \since QtWebEngine 6.6 + \readonly + + The id of the developer tools host associated with this page. + + If remote debugging is enabled (see \l{Qt WebEngine Developer Tools}), the id can be used to + build the URL to connect to the developer tool websocket: + \c{ws://localhost:<debugggin-port>/devtools/page/<id>)}. The websocket can be used to to interact + with the page using the \l{https://chromedevtools.github.io/devtools-protocol/}{DevTools + Protocol}. +*/ + +/*! \qmlmethod WebEngineAction WebEngineView::action(WebAction action) \since 5.12 @@ -1331,10 +1340,11 @@ */ /*! - \qmlsignal WebEngineView::printRequest + \qmlsignal WebEngineView::printRequested \since QtWebEngine 1.8 - This signal is emitted when the JavaScript \c{window.print()} method is called. + This signal is emitted when the JavaScript \c{window.print()} method is called or the user pressed the print + button of PDF viewer plugin. Typically, the signal handler can simply call printToPdf(). \sa printToPdf @@ -1477,3 +1487,99 @@ \sa renderProcessPid */ + +/*! + \qmlsignal WebEngineView::touchSelectionMenuRequested(TouchSelectionMenuRequest *request) + \since QtWebEngine 6.3 + \readonly + + This signal is emitted when a touch selection menu is requested at a specified position. + + The \a request can be handled by using the methods of the TouchSelectionMenuRequest + type. + + \note Signal handlers need to call \c{request.accepted = true} to prevent a default touch + selection menu from showing up. + + \sa TouchSelectionMenuRequest +*/ + +/*! + \qmlproperty Component WebEngineView::touchHandleDelegate + \since QtWebEngine 6.4 + + The \a touchHandleDelegate provides a template defining visual touch handles instantiated by the view + whenever touch selection handling is required. + + The handle's position, opacity, and visibility are updated automatically. + The delegate should be a QML Item or any QML type which inherits it. + + \note If no QML Item is set, the default touch handles will be shown. + + The following code uses a custom touch handle delegate: + + \code + WebEngineView { + // ... + touchHandleDelegate: Rectangle { + color: "red" + } + // ... + } + \endcode + + The touch handles can be also switched dynamically: + + \code + Component { + id: circleTouchHandle + Rectangle { + color: "blue" + radius: 50 + } + } + function showDefaultHandle(isDefault) { + if (isDefault) + webEngineView.touchHandleDelegate = circleTouchHandle + else + webEngineView.touchHandleDelegate = null + } + \endcode + + \note If no delegate is provided, Chromium's default touch handles will appear. + +*/ + +/*! + \qmlmethod void WebEngineView::save(const QString &filePath, QWebEngineDownloadRequest::SavePageFormat format) + \since QtWebEngine 6.6 + + Save the current web page to disk. + + The web page is saved to \a filePath in the specified \a{format}. + + This is a shortcut for the following actions: + \list + \li Trigger the Save web action. + \li Accept the next download item and set the specified file path and save format. + \endlist + + This function issues an asynchronous download request for the web page and returns immediately. + + \sa QWebEngineDownloadRequest::SavePageFormat +*/ + +/*! + \qmlsignal WebEngineView::webAuthUxRequested(QWebEngineWebAuthUxRequest *request); + \since QtWebEngine 6.7 + + This signal is emitted when a WebAuth authenticator requires user interaction + during the authentication process. These requests are handled by displaying a dialog to the user. + + The \a request contains the information and API required to complete the WebAuth UX request. + + \sa QWebEngineWebAuthUxRequest +*/ + + \sa {WebEngine Qt Quick Custom Touch Handle Example} +*/ |