diff options
Diffstat (limited to 'src/webenginequick/doc/src/webengineframe.qdoc')
-rw-r--r-- | src/webenginequick/doc/src/webengineframe.qdoc | 99 |
1 files changed, 99 insertions, 0 deletions
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. +*/ |