class QWebEngineFrame

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

Added in version 6.8.

Synopsis

Properties

Methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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.

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property htmlNameᅟ: str
Access functions:
property isMainFrameᅟ: bool
Access functions:
property isValidᅟ: bool
Access functions:
property nameᅟ: str
Access functions:
property sizeᅟ: QSizeF
Access functions:
property urlᅟ: QUrl
Access functions:
children()
Return type:

.list of QWebEngineFrame

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

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

htmlName()
Return type:

str

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 a null QString.

See also

name

Getter of property htmlNameᅟ .

isMainFrame()
Return type:

bool

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

Getter of property isMainFrameᅟ .

isValid()
Return type:

bool

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

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

Getter of property isValidᅟ .

name()
Return type:

str

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

See also

htmlName

Getter of property nameᅟ .

__ne__(rhs)
Parameters:

rhs – QWebEngineFrame

Return type:

bool

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

__eq__(rhs)
Parameters:

rhs – QWebEngineFrame

Return type:

bool

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

printToPdf(resultCallback)
Parameters:

resultCallback – PyCallable

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

Note

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

Note

We guarantee that the resultCallback 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, QWebEngineFrame, or QWebEngineView instance inside it.

printToPdf(callback)
Parameters:

callback – QJSValue

printToPdf(filePath)
Parameters:

filePath – str

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

Note

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

runJavaScript(scriptSource, resultCallback)
Parameters:

  • scriptSource – str

  • resultCallback – PyCallable

runJavaScript(scriptSource, worldId[, resultCallback={}])
Parameters:

  • scriptSource – str

  • worldId – int

  • resultCallback – PyCallable

Runs the JavaScript code contained in scriptSource 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 (0).

When the script has been executed, the callable resultCallback is called with the result of the last executed statement.

Only plain data can be returned from JavaScript as the result value.

Note

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

Note

We guarantee that the resultCallback 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, QWebEngineFrame, or QWebEngineView instance inside it.

size()
Return type:

QSizeF

Returns the size of the frame within the viewport.

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

Getter of property sizeᅟ .

url()
Return type:

QUrl

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

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

Getter of property urlᅟ .