- Qt 6.12
- Qt WebEngine
- C++ Classes
- QtWebEngineCore
- QWebEngineFrame
- Qt 6.12.0 Reference Documentation

# QWebEngineFrame Class

The QWebEngineFrame class gives information about and control over a page frame. More...

Header: | `#include <QWebEngineFrame>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)` `target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore)`
qmake: | `QT += webenginecore`
Since: | Qt 6.8
In QML: | webEngineFrame

- List of all members, including inherited members

## Properties

children : QList<QWebEngineFrame> htmlName : QString isMainFrame : bool isValid : bool | name : QString size : QSizeF url : QUrl

## Public Functions

| QWebEngineFrame()
| QWebEngineFrame(const QWebEngineFrame &other)
| QWebEngineFrame(QWebEngineFrame &&other)
| ~QWebEngineFrame()
QList<QWebEngineFrame> | children() const
QString | htmlName() const
bool | isMainFrame() const
bool | isValid() const
QString | name() const
void | printToPdf(const QString &filePath)
void | printToPdf(const std::function<void (const QByteArray &)> &callback)
void | runJavaScript(const QString &script, Functor &&callback)
void | runJavaScript(const QString &script, quint32 worldId = 0)
void | runJavaScript(const QString &script, quint32 worldId, Functor &&callback)
QSizeF | size() const
QUrl | url() const
QWebEngineFrame & | operator=(QWebEngineFrame &&other)
QWebEngineFrame & | operator=(const QWebEngineFrame &other)

## Related Non-Members

bool | operator!=(const QWebEngineFrame &left, const QWebEngineFrame &right)
bool | operator==(const QWebEngineFrame &left, const QWebEngineFrame &right)

## Detailed Description

A web engine frame represents a single frame within a web page, such as those created by `<frame>` or `<iframe>` HTML elements. An active QWebEnginePage has one or more frames arranged in a tree structure. The top-level frame, the root of this tree, can be accessed through the mainFrame() method, and children() provides a frame's direct descendants.

A frame's lifetime is, at most, as long as the QWebEnginePage object that produced it. However, frames may be created and deleted spontaneously and dynamically, for example through navigation and script execution. Because of this, many QWebEngineFrame methods return optional values, which will be `std::nullopt` if the frame no longer exists.

## Property Documentation

### `[read-only]` children : QList<QWebEngineFrame>

This property holds a list of the frame's children in an arbitrary order.

If the frame could not be found, returns an empty list.

Access functions:

QList<QWebEngineFrame> | children() const

### `[read-only]` htmlName : QString

This property holds the value of the frame's `name` HTML attribute, or an empty string if it has none.

If the frame could not be found, returns a null QString.

Access functions:

QString | htmlName() const

See also name.

### `[read-only]` isMainFrame : bool

This property holds whether this object represents the page's main frame.

Access functions:

bool | isMainFrame() const

### `[read-only]` isValid : bool

This property holds whether this object represents an existing frame.

Once a frame is invalid, it never becomes valid again.

Access functions:

bool | isValid() const

### `[read-only]` name : QString

This property holds the frame name; that is, what would be returned by `window.name` in JavaScript.

If the frame could not be found, returns a null QString.

Access functions:

QString | name() const

See also htmlName.

### `[read-only]` size : QSizeF

This property holds the size of the frame within the viewport, measured in logical pixels.

On devices with a scale factor other than 100%, this will not correspond to the on-screen size; instead, it will be the size before scaling is applied. In such cases, the size may contain fractional values.

If the frame could not be found, returns QSizeF().

Access functions:

QSizeF | size() const

### `[read-only]` url : QUrl

This property holds the URL of the content currently loaded in this frame.

If the frame could not be found, returns an empty QUrl.

Access functions:

QUrl | url() const

## Member Function Documentation

### `[noexcept default]` QWebEngineFrame::QWebEngineFrame()

Default-constructs an instance of QWebEngineFrame.

### `[noexcept default]` QWebEngineFrame::QWebEngineFrame(const QWebEngineFrame &other)

Copy-constructs an instance of QWebEngineFrame.

### `[noexcept default]` QWebEngineFrame::QWebEngineFrame(QWebEngineFrame &&other)

Move-constructs an instance of QWebEngineFrame.

### `[noexcept default]` QWebEngineFrame::~QWebEngineFrame()

Destroys the instance of QWebEngineFrame.

### `[invokable]` void QWebEngineFrame::printToPdf(const QString &filePath)

Renders the current content of the frame into a PDF document and saves it in the location specified in filePath. Printing uses a page size of A4, portrait layout, and includes the full range of pages.

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 QWebEnginePage::pdfPrintingFinished() signal.

Note: The QWebEnginePage::Stop web action can be used to interrupt this asynchronous operation.

If a file already exists at the provided file path, it will be overwritten.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also QWebEnginePage::pdfPrintingFinished().

### void QWebEngineFrame::printToPdf(const std::function<void (const QByteArray &)> &callback)

Renders the current content of the frame into a PDF document and returns a byte array containing the PDF data as parameter to callback. Printing uses a page size of A4, portrait layout, and includes the full range of pages.

The callback must take a const reference to a QByteArray as parameter. If printing was successful, this byte array will contain the PDF data, otherwise, the byte array will be empty.

Note: The QWebEnginePage::Stop web action can be used to interrupt this operation.

### template <typename Functor> requires QtWebEngine::if_callback_taking_t<Functor, const QVariant &> void QWebEngineFrame::runJavaScript(const QString &script, Functor &&callback)

### `[invokable]` void QWebEngineFrame::runJavaScript(const QString &script, quint32 worldId = 0)

### template <typename Functor> requires QtWebEngine::if_callback_taking_t<Functor, const QVariant &> void QWebEngineFrame::runJavaScript(const QString &script, quint32 worldId, Functor &&callback)

Runs the JavaScript code contained in 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 worldId. The world ID values are the same as provided by QWebEngineScript::ScriptWorldId, and between `0` and `256`. If you leave out the `world` ID, the script is run in the `MainWorld`. When the script has been executed, callback is called with the result of the last executed statement. `callback` can be any of a function pointer, a functor or a lambda, and it is expected to take a QVariant parameter. For example:

     page.runJavaScript("document.title", [](const QVariant &v) { qDebug() << v.toString(); });

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, `Date` and `ArrayBuffer`. Unsupported data types include, for example, `Function` and `Promise`.

Note: In Qt versions prior to 6.12, the callback had to be copyable.

Warning: Do not execute lengthy routines in the callback function, because it might block the rendering of the web engine page.

Warning: We guarantee that the callback is always called, but it might be done during page destruction. When QWebEnginePage is deleted, the callback is triggered with an invalid value and it is not safe to use the corresponding QWebEnginePage or QWebEngineView instance inside it.

See also QWebEngineScript::ScriptWorldId, QWebEnginePage::runJavaScript, and Script Injection.

### `[noexcept default]` QWebEngineFrame &QWebEngineFrame::operator=(QWebEngineFrame &&other)

Move-assigns other to this QWebEngineFrame instance.

### `[noexcept default]` QWebEngineFrame &QWebEngineFrame::operator=(const QWebEngineFrame &other)

Copy-assigns other to this QWebEngineFrame instance.

## Related Non-Members

### `[noexcept]` bool operator!=(const QWebEngineFrame &left, const QWebEngineFrame &right)

Returns `true` if left and right represent different frames in the same web page, otherwise `false`.

### `[noexcept]` bool operator==(const QWebEngineFrame &left, const QWebEngineFrame &right)

Returns `true` if left and right represent the same frame in the same web page, otherwise `false`.