webEngineFrame QML Value Type | Qt WebEngine | Qt 6.12.0
Description: webEngineFrame provides information about and control over a page frame.
Keywords: qmlvaluetype

- Qt 6.12
- Qt WebEngine
- QML Types
- webEngineFrame
- Qt 6.12.0 Reference Documentation

# webEngineFrame QML Value Type

webEngineFrame provides information about and control over a page frame. More...

Import Statement: | `import QtWebEngine`
Since: | Qt 6.8
In C++: | QWebEngineFrame

## Properties

- children : list<webEngineFrame> `(since QtWebEngine 6.10)`
- htmlName : string
- isMainFrame : bool
- isValid : bool
- name : string
- size : size
- url : url

## Methods

- void printToPdf(string filePath)
- void printToPdf(variant callback)
- void runJavaScript(string script, variant callback)
- void runJavaScript(string script, uint worldId, variant callback)

## 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 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 mainFrame property.

A frame's lifetime is, at most, as long as the WebEngineView object that produced it. However, frames may be created and deleted spontaneously and dynamically, for example through navigation and script execution.

## Property Documentation

### children : list<webEngineFrame> `[read-only, since QtWebEngine 6.10]`

Returns a list of the frame's children in an arbitrary order.

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

This property was introduced in QtWebEngine 6.10.

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

Returns 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 an empty string.

See also name.

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

Returns `true` if this object represents the page's main frame; `false` otherwise.

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

Returns `true` if this object represents an existing frame; `false` otherwise.

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

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

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

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

See also htmlName.

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

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 a default size with dimensions (-1, -1).

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

Returns the URL of the content currently loaded in this frame.

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

## Method Documentation

### void printToPdf(string filePath)

Prints the frame's current content to a PDF document and stores it under 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 WebEngineView::pdfPrintingFinished().

See also WebEngineView::pdfPrintingFinished().

### void 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 callback must take a string parameter. This string will contain the document's data upon successful printing and an empty string otherwise.

### void runJavaScript(string script, variant callback)

### void runJavaScript(string script, uint worldId, variant 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`.

The callback parameter is optional. If a callback function is provided, it will be invoked after the script finishes running.

     frame.runJavaScript("document.title", function(result) { console.log(result); });

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`.

The script will run in the same 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 Script Injection. For an alternative way to inject scripts, see WebEngineView::userScripts.